Windows UI (WinUI) Documentation

Welcome to WinUI

Welcome to the official documentation for Windows UI (WinUI)! WinUI is the modern, native UI platform for Windows applications. It provides a rich set of controls, APIs, and tools to help you build beautiful, performant, and accessible experiences that feel at home on Windows.

WinUI is part of the Windows App SDK, offering a unified set of APIs that can be used by any Windows app type, including unpackaged desktop apps, MSIX-packaged apps, and apps built with frameworks like C++, C#, and the WebView2 runtime.

This documentation will guide you through understanding WinUI concepts, using its various controls, and implementing advanced features. Whether you're new to Windows development or looking to modernize your existing application, WinUI is the recommended path forward.

Getting Started

Begin your WinUI journey by setting up your development environment and creating your first WinUI application.

Prerequisites

• Windows 10 version 1903 (Build 18362) or later.
• Visual Studio 2019 version 16.9 or later with the ".NET desktop development" and "Universal Windows Platform development" workloads.
• Windows App SDK Runtime (available via NuGet or as a system component).

Creating Your First App

Use the Visual Studio templates to create a new WinUI project:

1. Open Visual Studio.
2. Select "Create a new project".
3. Search for "WinUI" and choose the appropriate template (e.g., "Blank App, Packaged (WinUI 3)").
4. Follow the project creation wizard.

Explore the generated project structure and run the application to see your basic WinUI app in action.

Core Controls

WinUI offers a comprehensive set of controls designed for modern Windows applications. These controls adhere to Fluent Design principles, providing a consistent and delightful user experience.

Layout Controls

Arrange your UI elements effectively with these layout containers.

• Grid: A flexible two-dimensional layout panel.
• StackPanel: Arranges child elements in a single line, either horizontally or vertically.
• RelativePanel: Positions elements relative to each other or the panel itself.
• Canvas: Allows for absolute positioning of elements.

Navigation Controls

Facilitate user movement and discovery within your application.

• NavigationView: Provides a hierarchical navigation experience, common in many Windows apps.
• Pivot: Allows users to switch between different views or categories.
• CommandBar: Displays contextual commands.

Data Display Controls

Showcase and manage data effectively.

• ListView: Displays a list of items. Supports virtualization for large datasets.
• GridView: Displays items in a grid layout.
• DataGrid: A powerful control for displaying tabular data.
• TreeView: Represents hierarchical data.

Input Controls

Gather user input with a variety of intuitive controls.

• TextBox: For single-line text input.
• PasswordBox: For masked text input.
• RichEditBox: For multi-line rich text input.
• Button: Triggers an action.
• CheckBox, RadioButton: For selection.
• Slider: For selecting a value from a range.
• DatePicker, TimePicker: For selecting dates and times.

Feedback Controls

Provide visual cues and confirmations to the user.

• ProgressBar: Indicates the progress of an operation.
• ProgressRing: Shows indeterminate progress.
• TextBlock: Displays text.
• Dialogs/MessageDialogs: For alerts and confirmations.

Styling and Theming

Customize the look and feel of your application to match your brand or user preferences.

Resources

WinUI leverages XAML resources for defining styles, templates, and other reusable UI elements. You can define these in your App.xaml or in separate resource dictionary files.

<Application xmlns="..." ...>
    <Application.Resources>
        <Style TargetType="Button" BasedOn="{StaticResource MaterialDesignButton}">
            <Setter Property="Background" Value="{StaticResource PrimaryButtonStyle}" />
            <Setter Property="Foreground" Value="White" />
        </Style>
    </Application.Resources>
</Application>

Theme Resources

WinUI provides built-in theme resources for Light, Dark, and High Contrast modes. You can apply these to your application or create custom themes.

Use the ElementTheme property on controls or the `Application.RequestedTheme` property to set the theme.

<Window ...
        xmlns:winui="using:Microsoft.UI.Xaml"
        winui:ElementTheme="Dark">
    <!-- Window content -->
</Window>

Animations

Engage users with smooth and meaningful animations. WinUI provides powerful animation APIs.

Common Animations

• Entrance Animations: For showing elements.
• Content Transitions: For moving between different states or views.
• Implicit Animations: Automatically animate property changes.

XAML Storyboards

Define complex animations directly in XAML using Storyboard and related animation types.

<Page.Resources>
    <Storyboard x:Name="FadeInStoryboard">
        <DoubleAnimation
            Storyboard.TargetProperty="Opacity"
            From="0.0"
            To="1.0"
            Duration="0:0:0.5" />
    </Storyboard>
</Page.Resources>

<Grid>
    <TextBlock Text="Hello, WinUI!" FontSize="32" VerticalAlignment="Center" HorizontalAlignment="Center" />
    <!-- Start the animation when the page loads -->
    <!-- Using code-behind to trigger: FadeInStoryboard.Begin() -->
</Grid>

Accessibility

Ensure your application is usable by everyone. WinUI provides robust accessibility features.

Automation Properties

Use automation properties like AutomationProperties.Name, AutomationProperties.HelpText, and AutomationProperties.AccessibilityView to provide semantic information for screen readers and other assistive technologies.

<Button Content="Submit"
        AutomationProperties.Name="Submit Form Button"
        AutomationProperties.HelpText="Click to submit your form data." />

Keyboard Navigation

Ensure all interactive elements are accessible and operable via the keyboard. WinUI controls generally handle this out of the box, but custom implementations require careful attention.

Samples

Explore the official WinUI samples repository on GitHub to see controls and patterns in action:

WinUI Gallery Sample App

These samples demonstrate best practices and provide starting points for your own applications.