Windows Composition Samples

repository·master·Indexed 22 days ago

https://github.com/microsoft/windowscompositionsamples

A collection of samples and demos for advanced UI capabilities using Microsoft.UI.Composition and Microsoft.UI.Input APIs within the Windows App SDK (WinUI 3). It includes ExpressionBuilder, a type-safe C# alternative to string-based Windows.UI.Composition.ExpressionAnimation objects, as well as a Sample Gallery and various demos for building high-performance interfaces using the Fluent Design System.

Tokens
2.1K
Snippets
3
Records
13
Agent score
78%

What's inside windowscompositionsamples

  1. Overview of Windows Input and Composition APIs

    master

    This project provides code samples and demos for building high-performance, engaging user interfaces using the Fluent Design System in WinUI 3. The focus is on low-level platform building blocks within the following namespaces:

    • Microsoft.UI.Composition: For creating visual content and animations.
    • Microsoft.UI.Input: For handling advanced input interactions.

    These samples are designed for developers working with the Windows App SDK to create innovative UI experiences beyond standard XAML controls.

  2. What is ExpressionBuilder and why use it?

    master

    ExpressionBuilder is a C#-only alternative to building Windows.UI.Composition.ExpressionAnimation objects using strings.

    Standard ExpressionAnimation objects require writing mathematical relationships as strings (e.g., "visualA.Offset.X + 50"), which leads to several developer pain points:

    • No type safety checks: Errors in the equation are only caught at runtime.
    • No IntelliSense: You lose autocomplete and semantic guidance while writing equations.
    • Runtime errors: Semantic errors in the string equation cause failures during execution rather than at compile time.

    ExpressionBuilder alleviates these issues by providing a type-safe, fluent API to construct expressions using ExpressionNode objects.

  3. Core components of an ExpressionBuilder expression

    master

    ExpressionBuilder constructs expressions using four primary building blocks:

    • Parameters: Key-value pairs that can be references to a CompositionObject or constant values. These can be updated later using string-based keys.
    • Functions: Mathematical functions provided via the ExpressionFunctions class (e.g., Clamp, Max, Min, Cos).
    • Keywords: Known phrases in the Expression language (e.g., referencing CurrentValue).
    • Operators: Mathematical operators (+, -, *, /) and logical operators (& for AND, | for OR) that combine components into an equation.

    To simplify usage, it is recommended to use aliases for the main classes:

    using EF = ExpressionBuilder.ExpressionFunctions;
    using EV = ExpressionBuilder.ExpressionValues;
  4. Understand the project structure and components

    master

    The repository is organized into several functional areas:

    • Demos: Standalone code demos that combine multiple concepts and features into complex user experiences.
    • Sample Gallery: A central application containing numerous individual samples, each demonstrating a specific API or concept. These samples are compatible with Windows 10 version 1809 (build 17763) or higher.
    • Samples Common: Shared code patterns, utilities, prototypes, and early reference implementations used across the demos and samples.
    • ExpressionBuilder: A set of C# classes designed to provide a type-safe environment for building ExpressionAnimations.
    • Samples Native: A native library used to access low-level functionality that lacks WinRT projections.
  5. Template expressions with ExpressionBuilder

    master

    Templating allows you to define an expression once and bind it to multiple objects later. To make a part of an expression modifiable at runtime, you must define it as a parameter using a string name via ExpressionValues.

    To update a template's parameters (like changing which visual is referenced or changing a constant value), use SetReferenceParameter or SetScalarParameter on the ExpressionNode.

    // 1. Define parameters with string names for later updates
    var additionOffset = ExpressionValues.Constant.CreateScalarConstant("addOffset", 50f);
    var expressionNode = ExpressionValues.Reference.CreateVisualReference("visualA", _visualA) + additionOffset;
    
    // ... later in the code ...
    
    // 2. Update the template parameters
    expressionNode.SetReferenceParameter("visualA", _visualC);
    expressionNode.SetScalarParameter("addOffset", 100f);
    var additionOffset = ExpressionValues.Constant.CreateScalarConstant("addOffset", 50f);
    var expressionNode = ExpressionValues.Reference.CreateVisualReference("visualA", _visualA) + additionOffset;
    
    // Update the template
    expressionNode.SetReferenceParameter("visualA", _visualC);
    expressionNode.SetScalarParameter("addOffset", 100f);
  6. Install and set up ExpressionBuilder

    master

    To use the ExpressionBuilder classes in your application, follow these steps:

    1. Download a copy of the source code.
    2. Add the ExpressionBuilder project into your Visual Studio solution.
    3. Update the project references in your application to include the ExpressionBuilder project.
    4. Add the following using statement to your C# files to access the classes:
    using ExpressionBuilder;
  7. Clone and build the Windows Composition Samples project

    master

    To run the sample gallery locally, follow these steps:

    1. Clone the repository: Use standard Git cloning procedures to pull the microsoft/windowscompositionsamples repository to your local machine.
    2. Open the solution: Open the SampleGallery.sln file in Visual Studio.
    3. Configure the Startup Project:
      • Open the Solution Explorer (View > Solution Explorer).
      • Right-click the SampleGalleryPkg project.
      • Select Set as Startup Project.
    4. Set the Platform: Change the solution platform from Arm64 to x64.
    5. Manage Dependencies:
      • Right-click the SampleGallery project and select Manage NuGet Packages to restore or install necessary dependencies to avoid build errors.
    6. Build and Run: Clean the solution, then build and deploy it to run the application.
  8. Use GetReference() for type-safe single-use animations

    master

    If you do not need to reuse an expression as a template, you can use the GetReference() extension method on a CompositionObject. This allows you to build an expression and start an animation in a single, type-safe line without manually calling SetReferenceParameter.

    Standard String Approach:

    var expression = _compositor.CreateExpressionAnimation("visualA.Offset.X + 50");
    expression.SetReferenceParameter("visualA", _visualA);
    _visualB.StartAnimation("Offset.X", expression);

    ExpressionBuilder Approach:

    _visualB.StartAnimation("Offset.X", _visualA.GetReference().Offset.X + 50f);
  9. InteractionTracker InertiaModifier extensions

    master

    If you are using ExpressionBuilder to create expressions for InteractionTracker's InertiaModifiers, the following extension methods are available:

    • InteractionTrackerInertiaRestingValue.SetCondition
    • InteractionTrackerInertiaRestingValue.SetRestingValue
    • InteractionTrackerInertiaMotion.SetCondition
    • InteractionTrackerInertiaMotion.SetMotion
  10. Syntax differences between String Expressions and ExpressionBuilder

    master

    When moving from string-based expressions to ExpressionBuilder, note the following syntax changes:

    FeatureString SyntaxExpressionBuilder Syntax
    Ternary Operatorcondition ? ifTrue : ifFalseEF.Conditional(condition, ifTrue, ifFalse)
    Logical AND&&&
    Logical OR|||

    Note: EF is a common alias for ExpressionBuilder.ExpressionFunctions.