ThemeShadow Class

Reference

Definition

Namespace:: Windows.UI.Xaml.Media

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

A ThemeShadow is a preconfigured shadow effect that can be applied to any XAML element to draw shadows appropriately based on x, y, z coordinates. ThemeShadow also automatically adjusts for other environmental specifications:

Adapts to changes in lighting, user theme, app environment, and shell.
Shadows elements automatically based on their elevation.
Keeps elements in sync as they move and change elevation.
Keeps shadows consistent throughout and across applications.

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 524288)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class ThemeShadow : Shadow

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 524288)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class ThemeShadow : Shadow

Public Class ThemeShadow
Inherits Shadow

Inheritance: Object IInspectable DependencyObject Shadow ThemeShadow

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows requirements

Device family	Windows 10, version 1903 (introduced in 10.0.18362.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v8.0)

Examples

Tip

For more info, design guidance, and code examples, see Z-depth and shadow.

Many common controls automatically cast shadows using ThemeShadow.

If you have the WinUI 2 Gallery app installed and meet the minimum Windows 10 version requirements above, click here to open the app and see ThemeShadow in action on common controls.

Remarks

Tip

For more info, design guidance, and code examples, see Z-depth and shadow.

A ThemeShadow can be applied to any XAML element to draw shadows based on the relative x, y, and z coordinates between a conceptual caster UIElement and one or more receiver UIElements which have the caster's shadow rendered onto them.

ThemeShadow supports only rectangular shadows. For custom shadow effects, you can use a DropShadow.

ThemeShadows in Popups

ThemeShadow automatically casts shadows when applied to any XAML element in a Popup. It will cast shadows on the app background content behind it and any other open Popups below it.

To use ThemeShadow with Popups, use the UIElement.Shadow property to apply a ThemeShadow to a XAML element. Then, elevate the element from other elements behind it, for example by using the z component of the UIElement.Translation property. For most Popup UI, the recommended default elevation relative to the app background content is 32 effective pixels.

ThemeShadow in other elements

To cast a shadow from a XAML element that isn't in a Popup, you must explicitly specify the other elements that can receive the shadow in the ThemeShadow.Receivers collection. Receivers cannot be an ancestor of the caster in the visual tree.

Performance best practices for ThemeShadow

Limit the number of custom receiver elements to the minimum necessary.
If multiple receiver elements are at the same elevation then try to combine them by targeting a single parent element instead.
If multiple elements will cast the same type of shadow onto the same receiver elements then add the shadow as a shared resource and reuse it.

Constructors

ThemeShadow()

Initializes a new instance of the ThemeShadow class.

Properties

Dispatcher	Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)
Receivers	Gets a collection of UI elements that this ThemeShadow is cast on.

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

Applies to

Jaa