Skip to content

Introduce "Composition" > "Basics" page #2205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Tera (0x5bfa) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Introduce "Composition" > "Basics" page #2205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions WinUIGallery/SampleSupport/Data/ControlInfoData.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3799,6 +3799,39 @@
}
]
},
{
"UniqueId": "Composition",
"Title": "Composition",
"IconGlyph": "\uE81E",
"Items": [
{
"UniqueId": "CompositionBasics",

@marcelwgn Marcel W. (marcelwgn) Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you expect an "CompositionAdvanced" page or why is this called basics?

@0x5bfa Tera (0x5bfa) Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's the list of pages trying to implement, the one we discussed earlier.

image

Do you have something else in mind?

"Title": "Basics",
"ApiNamespace": "Microsoft.UI.Composition",
"Subtitle": "Connect XAML elements to the Visual layer and apply fundamental transforms and clips.",
"ImagePath": "ms-appx:///Assets/ControlImages/AnimationInterop.png",
"Description": "Learn the foundations of XAML and Composition interop by retrieving and attaching visuals, working with coordinate systems, applying transform matrices, and clipping content.",
"IsNew": true,
"Docs": [
{
"Title": "Composition overview",
"Uri": "https://learn.microsoft.com/windows/apps/windows-app-sdk/composition"
},
{
"Title": "ElementCompositionPreview - API",
"Uri": "https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.hosting.elementcompositionpreview"
},
{
"Title": "Visual - API",
"Uri": "https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.visual"
}
],
"RelatedControls": [
"XamlCompInterop"
]
}
]
},
{
"UniqueId": "Motion",
"Title": "Motion",
Expand Down
33 changes: 33 additions & 0 deletions WinUIGallery/Samples/CompositionBasics/CompositionBasicsChildVisual.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
--- header
Attach a Composition child Visual and position it with AnchorPoint
--- xaml
<Grid
x:Name="ChildVisualHost"
Height="220"
SizeChanged="ChildVisualHost_SizeChanged" />
--- c#
private SpriteVisual? _childVisual;

private void ChildVisualExample_Loaded(object sender, RoutedEventArgs e)
{
Visual hostVisual = ElementCompositionPreview.GetElementVisual(ChildVisualHost);
_childVisual = hostVisual.Compositor.CreateSpriteVisual();
_childVisual.Size = new Vector2(80);
_childVisual.Brush = hostVisual.Compositor.CreateColorBrush(Colors.DodgerBlue);

ElementCompositionPreview.SetElementChildVisual(ChildVisualHost, _childVisual);
UpdateChildVisual();
}

private void UpdateChildVisual()
{
// AnchorPoint is normalized: (0,0) is the top-left and (1,1) is the bottom-right.
_childVisual.AnchorPoint = new Vector2(anchorX, anchorY);
_childVisual.Offset = new Vector3(ChildVisualHost.ActualSize / 2, 0);
}

private void Page_Unloaded(object sender, RoutedEventArgs e)
{
ElementCompositionPreview.SetElementChildVisual(ChildVisualHost, null);
_childVisual?.Dispose();
}
26 changes: 26 additions & 0 deletions WinUIGallery/Samples/CompositionBasics/CompositionBasicsClip.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
--- header
Clip a XAML element through its Composition Visual
--- xaml
<Grid
x:Name="ClipTarget"
Width="240"
Height="140">
<!-- Sample content -->
</Grid>
--- c#
private InsetClip? _insetClip;

private void ClipExample_Loaded(object sender, RoutedEventArgs e)
{
Visual visual = ElementCompositionPreview.GetElementVisual(ClipTarget);
_insetClip = visual.Compositor.CreateInsetClip();
visual.Clip = _insetClip;
}

private void UpdateClip(float horizontalInset, float verticalInset)
{
_insetClip.LeftInset = horizontalInset;
_insetClip.RightInset = horizontalInset;
_insetClip.TopInset = verticalInset;
_insetClip.BottomInset = verticalInset;
}
32 changes: 32 additions & 0 deletions WinUIGallery/Samples/CompositionBasics/CompositionBasicsGetElementVisual.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
--- header
Get and transform the Visual backing a XAML element
--- xaml
<Border
x:Name="ElementVisualTarget"
Width="160"
Height="100"
SizeChanged="ElementVisualTarget_SizeChanged">
<TextBlock Text="XAML element" />
</Border>
--- c#
private Visual? _elementVisual;

private void ElementVisualExample_Loaded(object sender, RoutedEventArgs e)
{
_elementVisual = ElementCompositionPreview.GetElementVisual(ElementVisualTarget);
UpdateVisual();
}

private void UpdateVisual()
{
if (_elementVisual is null)
{
return;
}

// CenterPoint uses pixels in the Visual's coordinate space.
_elementVisual.CenterPoint = new Vector3(ElementVisualTarget.ActualSize / 2, 0);
// Translation is also exposed directly on UIElement as a Composition facade.
ElementVisualTarget.Translation = new Vector3(translationX, translationY, 0);
_elementVisual.RotationAngleInDegrees = rotation;
}
175 changes: 175 additions & 0 deletions WinUIGallery/Samples/CompositionBasics/CompositionBasicsPage.xaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
<?xml version="1.0" encoding="utf-8" ?>
<Page
x:Class="WinUIGallery.ControlPages.CompositionBasicsPage"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:controls="using:WinUIGallery.Controls"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d">

<StackPanel>
<controls:ControlExample
SampleDefinition="CompositionBasics\CompositionBasicsGetElementVisual.txt"
Loaded="ElementVisualExample_Loaded">
<controls:ControlExample.Options>
<StackPanel MinWidth="180" Spacing="8">
<Slider
x:Name="TranslationXSlider"
Header="Translation X"
Maximum="80"
Minimum="-80"
ValueChanged="ElementVisualTransform_ValueChanged" />
<Slider
x:Name="TranslationYSlider"
Header="Translation Y"
Maximum="50"
Minimum="-50"
ValueChanged="ElementVisualTransform_ValueChanged" />
<Slider
x:Name="RotationSlider"
Header="Rotation"
Maximum="360"
ValueChanged="ElementVisualTransform_ValueChanged" />
</StackPanel>
</controls:ControlExample.Options>

<Grid Height="240">
<Border
x:Name="ElementVisualTarget"
Width="160"
Height="100"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Background="{ThemeResource AccentFillColorDefaultBrush}"
CornerRadius="8"
SizeChanged="ElementVisualTarget_SizeChanged">
<TextBlock
HorizontalAlignment="Center"
VerticalAlignment="Center"
Foreground="{ThemeResource TextOnAccentFillColorPrimaryBrush}"
Text="XAML element" />
</Border>
</Grid>
</controls:ControlExample>

<controls:ControlExample
SampleDefinition="CompositionBasics\CompositionBasicsChildVisual.txt"
Loaded="ChildVisualExample_Loaded">
<controls:ControlExample.Options>
<StackPanel MinWidth="180" Spacing="8">
<Slider
x:Name="AnchorXSlider"
Header="AnchorPoint X"
Maximum="1"
StepFrequency="0.1"
Value="0.5"
ValueChanged="AnchorPointSlider_ValueChanged" />
<Slider
x:Name="AnchorYSlider"
Header="AnchorPoint Y"
Maximum="1"
StepFrequency="0.1"
Value="0.5"
ValueChanged="AnchorPointSlider_ValueChanged" />
</StackPanel>
</controls:ControlExample.Options>

<Grid
x:Name="ChildVisualHost"
Height="220"
MinWidth="280"
Background="{ThemeResource CardBackgroundFillColorDefaultBrush}"
BorderBrush="{ThemeResource CardStrokeColorDefaultBrush}"
BorderThickness="1"
CornerRadius="8"
SizeChanged="ChildVisualHost_SizeChanged">
<TextBlock
Margin="12"
VerticalAlignment="Bottom"
Foreground="{ThemeResource TextFillColorSecondaryBrush}"
Text="The child visual's offset stays at the center of this host." />
</Grid>
</controls:ControlExample>

<controls:ControlExample
SampleDefinition="CompositionBasics\CompositionBasicsTransformMatrix.txt"
Loaded="TransformMatrixExample_Loaded">
<controls:ControlExample.Options>
<StackPanel MinWidth="180" Spacing="8">
<Slider
x:Name="SkewXSlider"
Header="Horizontal skew"
Maximum="45"
Minimum="-45"
ValueChanged="TransformMatrixSlider_ValueChanged" />
<Slider
x:Name="ScaleXSlider"
Header="Horizontal scale"
Maximum="1.5"
Minimum="0.5"
StepFrequency="0.1"
Value="1"
ValueChanged="TransformMatrixSlider_ValueChanged" />
</StackPanel>
</controls:ControlExample.Options>

<Grid Height="220">
<Border
x:Name="TransformMatrixTarget"
Width="170"
Height="100"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Background="{ThemeResource AccentFillColorSecondaryBrush}"
CornerRadius="8"
SizeChanged="TransformMatrixTarget_SizeChanged">
<TextBlock
HorizontalAlignment="Center"
VerticalAlignment="Center"
Foreground="{ThemeResource TextOnAccentFillColorPrimaryBrush}"
Text="TransformMatrix" />
</Border>
</Grid>
</controls:ControlExample>

<controls:ControlExample
SampleDefinition="CompositionBasics\CompositionBasicsClip.txt"
Loaded="ClipExample_Loaded">
<controls:ControlExample.Options>
<StackPanel MinWidth="180" Spacing="8">
<Slider
x:Name="HorizontalClipSlider"
Header="Left and right inset"
Maximum="70"
ValueChanged="ClipSlider_ValueChanged" />
<Slider
x:Name="VerticalClipSlider"
Header="Top and bottom inset"
Maximum="40"
ValueChanged="ClipSlider_ValueChanged" />
</StackPanel>
</controls:ControlExample.Options>

<Grid Height="220">
<Grid
x:Name="ClipTarget"
Width="240"
Height="140"
HorizontalAlignment="Center"
VerticalAlignment="Center"
Background="{ThemeResource AccentFillColorDefaultBrush}">
<Ellipse
Width="170"
Height="170"
Fill="{ThemeResource LayerFillColorAltBrush}" />
<TextBlock
HorizontalAlignment="Center"
VerticalAlignment="Center"
Foreground="{ThemeResource TextFillColorPrimaryBrush}"
Text="Composition clip" />
</Grid>
</Grid>
</controls:ControlExample>
</StackPanel>
</Page>
Loading