Visual Visual Visual Visual Class
Definition
Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Prerelease APIs are identified by a Prerelease label.
[Contains prerelease APIs.]
The base visual object in the visual hierarchy.
public : class Visual : CompositionObject, IVisual, IVisual2, IVisual3public class Visual : CompositionObject, IVisual, IVisual2, IVisual3Public Class Visual Inherits CompositionObject Implements IVisual, IVisual2, IVisual3// This API is not available in Javascript.
- Inheritance
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
Inherited Members
Inherited methods
Inherited properties
Remarks
Visual objects compose and render serialized drawing content and form the basis of a retained mode visual system. The Visual class supports basic position and clipping and can have 2D and 3D transformations applied to them. Additional functionality like solid colors, images, and content with effects is provided through subclasses like SpriteVisual or ContainerVisual, and by setting the Brush property of the visual to CompositionBrush subclasses such as CompositionColorBrush, CompositionEffectBrush, or CompositionSurfaceBrush.
Visual objects are thread-agile and not bound to the UI thread.
Animatable properties
The following properties of Visual are animatable by associating them with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation:
- Size
- Offset
- Opacity
- Orientation
- CenterPoint
- RotationAngle
- RotationAngleInDegrees
- RotationAxis
- TransformMatrix
Rotation
Visual supports two forms of rotation:
axis-angle
Axis-angle rotation uses the RotationAngle, RotationAxis, and CenterPoint properties to specify the rotation in degrees, which axis to rotate around, and the center point of the visual to rotate around.
orientation
Rotation by orientation uses the Orientation property to specify a quaternion describing an orientation and rotation in 3D space.
Properties
AnchorPoint AnchorPoint AnchorPoint AnchorPoint
The point on the visual to be positioned at the visual's offset. Value is normalized with respect to the size of the visual. Animatable.
public : Vector2 AnchorPoint { get; set; }public Vector2 AnchorPoint { get; set; }Public ReadWrite Property AnchorPoint As Vector2// This API is not available in Javascript.
- Value
- Vector2 Vector2 Vector2 Vector2
The point on the visual to be positioned at the visual's offset. Value is normalized with respect to the size of the visual.
| Device family |
Windows 10 (introduced v10.0.10586.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v2)
|
Examples
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Composition;
using Windows.UI.Xaml.Hosting;
using System.Numerics;
namespace AnchorPointSample
{
/// <summary>
/// Using AnchorPoint to Center a Rectangle
/// </summary>
public sealed partial class MainPage : Page
{
public MainPage()
{
this.InitializeComponent();
this.Loaded += MainPage_Loaded;
}
private void MainPage_Loaded(object sender, RoutedEventArgs e)
{
// Get the backing visual for the "CenteredElement" XAML Element
Visual root = ElementCompositionPreview.GetElementVisual(CenteredElement);
Compositor compositor = root.Compositor;
// Create a solid color visual
SpriteVisual mainVisual = compositor.CreateSpriteVisual();
mainVisual.Size = new Vector2(200, 200);
mainVisual.Brush = compositor.CreateColorBrush(Windows.UI.Colors.Blue);
// Set the anchor point to center the rectangle
mainVisual.AnchorPoint = new Vector2(0.5f, 0.5f);
// Insert the rectangle as a child of the XAML element
ElementCompositionPreview.SetElementChildVisual(CenteredElement, mainVisual);
}
}
}
BackfaceVisibility BackfaceVisibility BackfaceVisibility BackfaceVisibility
Specifies whether the back face of the visual should be visible during a 3D transform.
public : CompositionBackfaceVisibility BackfaceVisibility { get; set; }public CompositionBackfaceVisibility BackfaceVisibility { get; set; }Public ReadWrite Property BackfaceVisibility As CompositionBackfaceVisibility// This API is not available in Javascript.
- Value
- CompositionBackfaceVisibility CompositionBackfaceVisibility CompositionBackfaceVisibility CompositionBackfaceVisibility
Whether the back face of the visual should be visible during a 3D transform.
| Device family |
Windows 10 (introduced v10.0.10586.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v2)
|
BorderMode BorderMode BorderMode BorderMode
Specifies how to compose the edges of bitmaps and clips associated with a visual, or with all visuals in the subtree rooted at this visual. Setting BorderMode at a parent Visual will affect all children visuals in the subtree and can be selectively turned off at each child visual.
public : CompositionBorderMode BorderMode { get; set; }public CompositionBorderMode BorderMode { get; set; }Public ReadWrite Property BorderMode As CompositionBorderMode// This API is not available in Javascript.
How to compose the edges of bitmaps and clips associated with a visual, or with all visuals in the subtree rooted at this visual.
| Device family |
Windows 10 (introduced v10.0.10586.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v2)
|
CenterPoint CenterPoint CenterPoint CenterPoint
The point about which rotation or scaling occurs. Animatable
public : Vector3 CenterPoint { get; set; }public Vector3 CenterPoint { get; set; }Public ReadWrite Property CenterPoint As Vector3// This API is not available in Javascript.
- Value
- Vector3 Vector3 Vector3 Vector3
The point about which rotation or scaling occurs.
Remarks
CenterPoint is relative to the offset specified in the AnchorPoint property.
This property is animatable and can be associated with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation.
Clip Clip Clip Clip
Specifies the clipping region for the visual. When a visual is rendered, only the portion of the visual that falls inside the clipping region is displayed, while any content that extends outside the clipping region is clipped (that is, not displayed).
public : CompositionClip Clip { get; set; }public CompositionClip Clip { get; set; }Public ReadWrite Property Clip As CompositionClip// This API is not available in Javascript.
Specifies the clipping region for the visual.
CompositeMode CompositeMode CompositeMode CompositeMode
Specifies how a visual's bitmap is blended with the screen.
public : CompositionCompositeMode CompositeMode { get; set; }public CompositionCompositeMode CompositeMode { get; set; }Public ReadWrite Property CompositeMode As CompositionCompositeMode// This API is not available in Javascript.
- Value
- CompositionCompositeMode CompositionCompositeMode CompositionCompositeMode CompositionCompositeMode
How a visual's bitmap is blended with the screen.
| Device family |
Windows 10 (introduced v10.0.10586.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v2)
|
IsVisible IsVisible IsVisible IsVisible
Indicates whether the visual and its entire subtree of child visuals is visible.
public : PlatForm::Boolean IsVisible { get; set; }public bool IsVisible { get; set; }Public ReadWrite Property IsVisible As bool// This API is not available in Javascript.
- Value
- PlatForm::Boolean bool bool bool
Indicates whether the visual and its entire subtree of child visuals is visible.
| Device family |
Windows 10 (introduced v10.0.10586.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v2)
|
Offset Offset Offset Offset
The offset of the visual relative to its parent or for a root visual the offset relative to the upper-left corner of the windows that hosts the visual. Animatable.
public : Vector3 Offset { get; set; }public Vector3 Offset { get; set; }Public ReadWrite Property Offset As Vector3// This API is not available in Javascript.
- Value
- Vector3 Vector3 Vector3 Vector3
Offset of the visual relative to its parent.
Remarks
This property is animatable and can be associated with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation.
Opacity Opacity Opacity Opacity
The opacity of the visual. Animatable.
The opacity property determines the transparency, if any, of the Visual and is a value from 0 to 1. 0 is fully transparent and 1 is full opaque. A Visual with an Opacity property of 0 is still present in the tree. Like other properties on the Visual, Opacity can be animated using the Windows,UI.Composition animation system.
public : float Opacity { get; set; }public float Opacity { get; set; }Public ReadWrite Property Opacity As float// This API is not available in Javascript.
- Value
- float float float float
The opacity of the visual.
Remarks
This property is animatable and can be associated with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation.
Orientation Orientation Orientation Orientation
A quaternion describing an orientation and rotation in 3D space that will be applied to the visual. Animatable.
public : Quaternion Orientation { get; set; }public Quaternion Orientation { get; set; }Public ReadWrite Property Orientation As Quaternion// This API is not available in Javascript.
- Value
- Quaternion Quaternion Quaternion Quaternion
A quaternion describing an orientation and rotation in 3D space that will be applied to the visual.
Parent Parent Parent Parent
The parent of the visual.
public : ContainerVisual Parent { get; }public ContainerVisual Parent { get; }Public ReadOnly Property Parent As ContainerVisual// This API is not available in Javascript.
The parent of the visual.
ParentForTransform ParentForTransform ParentForTransform ParentForTransform
Visual specifying the coordinate system in which this visual is composed.
public : Visual ParentForTransform { get; set; }public Visual ParentForTransform { get; set; }Public ReadWrite Property ParentForTransform As Visual// This API is not available in Javascript.
Visual specifying the coordinate system in which this visual is composed.
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
ParentForTransform allows you to change the coordinate system in which a visual is composed. You can specify another visual that acts as a visual's "transform parent". That is, the visual in question will inherit accumulated transforms as though it were the child of that other visual. Note that this includes the effects of all properties that relate to transform, such as Visual.RotationAngle, or Visual.AnchorPoint, on the specified "transform parent" visual and all of its "transform ancestors".
RelativeOffsetAdjustment RelativeOffsetAdjustment RelativeOffsetAdjustment RelativeOffsetAdjustment
Specifies the offset of the visual with respect to the size of its parent visual.
public : Vector3 RelativeOffsetAdjustment { get; set; }public Vector3 RelativeOffsetAdjustment { get; set; }Public ReadWrite Property RelativeOffsetAdjustment As Vector3// This API is not available in Javascript.
- Value
- Vector3 Vector3 Vector3 Vector3
The offset of the visual with respect to the size of its parent visual.
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
Value is normalized with respect to the size of the visual�s parent. For example, a value of (0.0, 0.5, 0.0) means that the vertical position of the visual is at the midpoint between the top and bottom of its parent visual�s bounds. This property is a Vector3 for consistency with the Offset property, however the Z component of the RelativeOffsetAdjustment property currently has no effect.
RelativeSizeAdjustment RelativeSizeAdjustment RelativeSizeAdjustment RelativeSizeAdjustment
The size of the visual with respect to the size of its parent visual.
public : Vector2 RelativeSizeAdjustment { get; set; }public Vector2 RelativeSizeAdjustment { get; set; }Public ReadWrite Property RelativeSizeAdjustment As Vector2// This API is not available in Javascript.
- Value
- Vector2 Vector2 Vector2 Vector2
The size of the visual with respect to the size of its parent visual.
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Remarks
Value is normalized with respect to the size of the visual's parent. For example, a value of (1.0, 0.5) indicates that the visual should be the full width of its parent but only half the height.
RotationAngle RotationAngle RotationAngle RotationAngle
The rotation angle in radians of the visual. Animatable.
To use degrees instead of radians use RotationAngleInDegrees. This property is animatable and can be associated with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation.
Visual supports two forms of rotation, by axis-angle, and by orientation.
public : float RotationAngle { get; set; }public float RotationAngle { get; set; }Public ReadWrite Property RotationAngle As float// This API is not available in Javascript.
- Value
- float float float float
The rotation angle in radians of the visual.
RotationAngleInDegrees RotationAngleInDegrees RotationAngleInDegrees RotationAngleInDegrees
The rotation angle of the visual in degrees. Animatable.
public : float RotationAngleInDegrees { get; set; }public float RotationAngleInDegrees { get; set; }Public ReadWrite Property RotationAngleInDegrees As float// This API is not available in Javascript.
- Value
- float float float float
The rotation angle of the visual in degrees.
| Device family |
Windows 10 (introduced v10.0.10586.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v2)
|
RotationAxis RotationAxis RotationAxis RotationAxis
The axis to rotate the visual around. Animatable.
This property is animatable and can be associated with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation.
Visual supports two forms of rotation, by axis-angle, and by orientation.
public : Vector3 RotationAxis { get; set; }public Vector3 RotationAxis { get; set; }Public ReadWrite Property RotationAxis As Vector3// This API is not available in Javascript.
- Value
- Vector3 Vector3 Vector3 Vector3
The axis to rotate the visual around. For example, a value of Vector3(1,0,0) indicates rotation along the x-axis.
Scale Scale Scale Scale
The scale to apply to the visual.
public : Vector3 Scale { get; set; }public Vector3 Scale { get; set; }Public ReadWrite Property Scale As Vector3// This API is not available in Javascript.
- Value
- Vector3 Vector3 Vector3 Vector3
The scale to apply to the visual. A value of Vector3 (1.0,1.0,1.0) is equivalent to 100%.
Remarks
The CenterPoint property affects the center point of the scale transform.
Size Size Size Size
The width and height of the visual. Animatable.
public : Vector2 Size { get; set; }public Vector2 Size { get; set; }Public ReadWrite Property Size As Vector2// This API is not available in Javascript.
- Value
- Vector2 Vector2 Vector2 Vector2
The width and height of the visual.
Examples
// Create a simple scene.
Compositor compositor = new Compositor();
SpriteVisual child = compositor.CreateSpriteVisual();
child.Offset = new Vector3(50.0f, 50.0f, 0.0f);
child.Size = new Vector2(200, 200);
child.Brush = compositor.CreateColorBrush(Color.FromArgb(0xFF, 0x00, 0xCC, 0x00));
// Create a simple scene.
_compositor = ref new Compositor();
auto child = _compositor->CreateSpriteVisual();
child->Offset = Vector3(50.0f, 50.0f, 0.0f);
child->Size = Vector2(200, 200);
child->Brush = _compositor->CreateColorBrush(ColorHelper::FromArgb(0xFF, 0x00, 0xCC, 0x00));
Remarks
This property is animatable and can be associated with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation.
TransformMatrix TransformMatrix TransformMatrix TransformMatrix
The transformation matrix to apply to the visual. Animatable.
public : Matrix4x4 TransformMatrix { get; set; }public Matrix4x4 TransformMatrix { get; set; }Public ReadWrite Property TransformMatrix As Matrix4x4// This API is not available in Javascript.
- Value
- Matrix4x4 Matrix4x4 Matrix4x4 Matrix4x4
The transformation matrix to apply to the visual.
Remarks
This property is animatable and can be associated with a KeyFrameAnimation or ExpressionAnimation using CompositionObject::StartAnimation.