XamlLight Class

Reference

Definition

Namespace:: Microsoft.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

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 : DependencyObject

Public Class XamlLight
Inherits DependencyObject

Inheritance: Object IInspectable DependencyObject XamlLight

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

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 `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` 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)

Methods

AddTargetBrush(String, Brush)	Sets a Brush as a target of a XamlLight.
AddTargetElement(String, UIElement)	Sets a UIElement as a target of a XamlLight.
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)	Stops a Brush from being a target of a XamlLight.
RemoveTargetElement(String, UIElement)	Stops a UIElement from being a target of a XamlLight.
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

Share via