XamlLight Class
Definition
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.
Provides a base class used to create XAML lights that use a CompositionLight to apply lighting effects to XAML elements and brushes.
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class XamlLight : DependencyObject[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class XamlLight : DependencyObjectPublic Class XamlLight
Inherits DependencyObject- Inheritance
- Attributes
Examples
See the code example in Lighting.
Remarks
You can use XamlLight to create custom lights.
For example, it can be used to create a light that applies a composition SpotLight to target elements to light them.
XamlLight provides methods for targeting UIElements or XAML Brushes, applying lights to trees of UIElements, and helping manage the lifetime of CompositionLight resources based on whether they're currently in use.
Custom XamlLights can be used in conjunction with custom Brushes derived from XamlCompositionBrushBase which use a SceneLightingEffect to controls the reflective properties of elements when being lit by a XamlLight.
Targeting objects
If you target a Brush with a XamlLight then the portions of any UIElements using that Brush will be lit by the light.
If you target a UIElement with a XamlLight then the entire UIElement and its child UIElements will all be lit by the light.
Targets can be added and removed by calling methods on a XamlLight instance. XamlLights can also define custom attached properties to add and remove targets from markup.
Managing resources
When creating a XamlLight, it's usually a good practice to delay creating a CompositionLight and any related resources until the light is being used. The OnConnected method is called when a XamlLight is first used to target an element or brush on screen, so you can override OnConnected to safely create resources only when they're needed.
It's also a good practice to dispose of composition resources when they're no longer in use. The OnDisconnected method is called when a XamlLight instance is no longer in use anywhere on the screen, so you can override OnDisconnected to safely dispose of resources. If the XamlLight is later used again after being disconnected then OnConnected will be called again.
Warning
On Windows 10 Creators Update (SDK 15063), CompositionLight can't be accessed after Dispose is called, so setting it to null after calling Dispose causes an error. To work around this issue, you can save the CompositionLight to a temporary variable and call Dispose on that after you set CompositionLight to null. var temp = CompositionLight; CompositionLight = null; temp.Dispose();
This issue is fixed in later versions of the SDK. See Version adaptive apps for info about how to target different SDK versions.
Constructors
| XamlLight() |
Initializes a new instance of the XamlLight class. |
Properties
| CompositionLight |
Gets or sets the CompositionLight instance used to apply lighting effects. |
| Dispatcher |
Always returns |
| DispatcherQueue |
Gets the |
Methods
| AddTargetBrush(String, Brush) | |
| AddTargetElement(String, UIElement) | |
| 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) |
| GetId() |
Returns the identifier for the custom XamlLight type. In most cases you should use a unique identifier to prevent conflicts. For example, you can use the FullName of your custom XamlLight type. The identifier is used to add and remove Brushes and UIElements as targets for a specific light type. |
| GetValue(DependencyProperty) |
Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject) |
| OnConnected(UIElement) |
This method is automatically called when the XamlLight is first in use on the screen, or after being previously disconnected then used again. This provides an opportunity to create resources such as the CompositionLight only when required. OnDisconnected will be called when the XamlLight is no longer being used to light any UIElements or Brushes. |
| OnDisconnected(UIElement) |
This method is automatically called when the XamlLight is no longer in use anywhere on the screen. This provides an opportunity to safely dispose of resources such as the CompositionLight when they aren't currently required. OnConnected will be called again if the XamlLight is later used to light any UIElements or Brushes after being disconnected. |
| 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) |
| RemoveTargetBrush(String, Brush) | |
| RemoveTargetElement(String, UIElement) | |
| 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) |