DOCSEARCHbyAlgolia
Submit Docs

WinUI 3 Gallery

repository·main·Indexed 25 days ago

https://github.com/microsoft/winui-gallery

An interactive companion app for WinUI and Windows App SDK developers. It showcases WinUI controls, styles, and adaptive UI patterns through live samples and code snippets, providing guidance on Microsoft.UI.Xaml library usage, Fluent Design, and accessibility best practices.

Tokens
1.4K
Snippets
3
Records
9
Agent score
86%

What's inside WinUI 3 Gallery

  1. Overview of WinUI 3 Gallery features

    main

    The WinUI 3 Gallery is a companion app for WinUI and Windows App SDK APIs. It provides:

    • WinUI controls samples: Interactive pages showing markup and codebehind for various controls.
    • Microsoft.UI.Xaml (WinUI) library usage: Demonstrates controls like NavigationView, SwipeControl, and more using the latest WinUI NuGet packages.
    • Adaptive UI demonstrations: Shows how controls respond to different form factors and how to achieve responsive layouts.
    • Design & accessibility guidance: Provides resources to help developers follow Fluent Design guidelines and accessibility best practices.

  2. Run WinUI Gallery scripts

    main

    You can run the utility scripts located in the scripts folder using two methods:

    Method 1: From File Explorer

    1. Navigate to the scripts folder.
    2. Right-click the desired .ps1 script (e.g., Get-LatestAddedSamples.ps1) and select Run with PowerShell.

    Method 2: From Visual Studio

    1. Open the WinUIGallery project in Visual Studio.
    2. Navigate to the scripts menu and select Open PowerShell Window.
    3. Execute the script by typing its relative path in the PowerShell window:
      ..\scripts\Get-LatestAddedSamples.ps1

  4. Build the WinUI 3 Gallery

    main

    To build the WinUI 3 Gallery locally, follow these steps:

    1. Set up the environment: Install Visual Studio 2022 or later. Ensure the Windows application development workload is installed. The app requires Windows 10 or later to execute.
    2. Clone the Repository: Use git to clone the repository.
    3. Build: Open WinUIGallery.slnx in Visual Studio, ensure the WinUIGallery project is set as the startup project, and build.
    git clone https://github.com/microsoft/WinUI-Gallery.git

  5. Set PowerShell execution policy to run scripts

    main

    Before running any PowerShell scripts in the scripts folder, you must set the execution policy to allow locally created scripts to run. Use the following command to set the policy for the current user:

    Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

  6. Troubleshoot WinUI Gallery build errors

    main

    If you encounter the following build error:

    Assets file '...\project.assets.json' not found. Run a NuGet package restore to generate this file.

    Try deleting the nuget.config file and building the project again.

  7. Add descriptions and help text to controls for accessibility

    main

    To improve accessibility for screen readers, you can associate visible text descriptions with controls using AutomationProperties.FullDescription and provide additional context using AutomationProperties.HelpText or ToolTipService.ToolTip.

    Connecting visible text to a control

    Use AutomationProperties.FullDescription on a control to link it to a TextBlock that contains the descriptive text. This allows screen readers to read the description when the control is focused.

    Providing nuance and tooltips

    Use AutomationProperties.HelpText to provide specific instructions or nuances that a screen reader will announce. You can also use ToolTipService.ToolTip to provide a visual tooltip for sighted users.

    <StackPanel Spacing="8">
    <!-- Use FullDescription to connect visible descriptions to their controls -->
    <StackPanel Spacing="8">
        <CheckBox Content="Clear cache on exit"
                    AutomationProperties.FullDescription="{x:Bind ClearCacheDescription.Text}" />
        <TextBlock x:Name="ClearCacheDescription"
                    Text="Deletes all cached items when closing the browser. This includes cookies, images, and browsing history."
                    AutomationProperties.AccessibilityView="Raw"
                    Foreground="{ThemeResource TextFillColorSecondaryBrush}" />
    </StackPanel>

<!-- Use HelpText and/or tooltips to explain nuances of controls -->
    <Button Content="Cancel RSS subscriptions"
            ToolTipService.ToolTip="Launch the cancellation wizard"
            AutomationProperties.HelpText="Launch the cancellation wizard" />
</StackPanel>

  8. Identify newly added samples with Get-LatestAddedSamples

    main
    The Get-LatestAddedSamples.ps1 script identifies newly added files in the ControlPages directory and provides their first commit dates. This is used to track progress and identify which new samples to showcase on the home page.

  9. Identify updated samples with Get-LatestUpdatedSamples

    main
    The Get-LatestUpdatedSamples.ps1 script identifies files in the ControlPages directory that have been updated and provides their last commit dates. This helps monitor changes to existing samples for potential showcasing on the home page.