ThemeShadow Class
Definition
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.
Equivalent WinUI class: Microsoft.UI.Xaml.Media.ThemeShadow.
/// [Windows.Foundation.Metadata.Composable(Windows.UI.Xaml.Media.IThemeShadowFactory, Windows.Foundation.Metadata.CompositionType.Public, 524288, "Windows.Foundation.UniversalApiContract")]
/// [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)]
/// [Windows.Foundation.Metadata.WebHostHidden]
class ThemeShadow : Shadow[Windows.Foundation.Metadata.Composable(typeof(Windows.UI.Xaml.Media.IThemeShadowFactory), Windows.Foundation.Metadata.CompositionType.Public, 524288, "Windows.Foundation.UniversalApiContract")]
[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)]
[Windows.Foundation.Metadata.WebHostHidden]
public class ThemeShadow : ShadowPublic Class ThemeShadow
Inherits Shadow- Inheritance
- Attributes
Windows 10 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 XAML Controls 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. Equivalent WinUI constructor: Microsoft.UI.Xaml.Media.ThemeShadow.ThemeShadow. |
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. Equivalent WinUI property: Microsoft.UI.Xaml.DependencyObject.Dispatcher. (Inherited from DependencyObject) |
| Receivers |
Gets a collection of UI elements that this ThemeShadow is cast on. Equivalent WinUI property: Microsoft.UI.Xaml.Media.ThemeShadow.Receivers. |