Window.SetTitleBar(UIElement) Method

Reference

Definition

Namespace:: Microsoft.UI.Xaml

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Enables title bar behavior on a XAML element when ExtendsContentIntoTitleBar is true.

public:
 virtual void SetTitleBar(UIElement ^ titleBar) = SetTitleBar;

void SetTitleBar(UIElement const& titleBar);

public void SetTitleBar(UIElement titleBar);

function setTitleBar(titleBar)

Public Sub SetTitleBar (titleBar As UIElement)

Parameters

titleBar: UIElement

The element to support title bar behavior.

Examples

This example shows how to extend the window's content area and replace the system title bar with a Grid that contains an icon and title text.

<Window ... >
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="32"/>
            <RowDefinition/>
        </Grid.RowDefinitions>

        <Grid x:Name="AppTitleBar">
            <Image Source="Images/WindowIcon.png"
                   HorizontalAlignment="Left" 
                   Width="16" Height="16" 
                   Margin="8,0"/>
            <TextBlock x:Name="AppTitleTextBlock" Text="App title"
                       TextWrapping="NoWrap"
                       Style="{StaticResource CaptionTextBlockStyle}" 
                       VerticalAlignment="Center"
                       Margin="28,0,0,0"/>
        </Grid>

        <NavigationView Grid.Row="1">
            <!-- Page content -->
        </NavigationView>
    </Grid>
</Window>

public MainWindow()
{
    this.InitializeComponent();

    ExtendsContentIntoTitleBar = true;
    SetTitleBar(AppTitleBar);  // skip call to this api to get a default custom title bar
}

Remarks

Call this method to replace the system title bar with a custom title bar UI for your app. The specified element supports the same system interactions as the system title bar, including drag, double-click to resize, and right-click to show the system menu. As a result, pointer input (mouse, touch, pen, and so on) is no longer recognized by the element and its child elements.

The rectangular area occupied by the specified element acts as the title bar for pointer purposes, even if the element is blocked by another element, or the element is transparent.

If you want to place interactive elements in the title bar area, you can use InputNonClientPointerSource APIs. Refer to the Titlebar page in the WinUI Gallery sample for an example.

Extend content into title bar

To specify a custom title bar, you must set ExtendsContentIntoTitleBar to true to hide the default system title bar. If ExtendsContentIntoTitleBar is false, the call to SetTitleBar does not have any effect. Your custom title bar element is shown in the body of your app window as an ordinary UI element and does not get the title bar behaviors.

If you set ExtendsContentIntoTitleBar to true but do not call SetTitleBar (or call SetTitlebar with a null argument), a default custom title bar is provided. This default title bar is a direct replacement of the system title bar in position, width, and height. If you want a specialized title bar, you can call SetTitleBar with a `UIElement` and get a title bar area on that UIElement's position, width, and height. That UIElement can be hosted anywhere within the contents of the app, not just the non-client area.

Title bar element

Only a single element can be specified as the title bar. If multiple elements are required, they can be specified as child elements of a single container (such as a Grid or StackPanel).

The custom title bar works best when it is not deep nested within the app. Deep nesting the UIElement within the XAML tree can cause unpredictable layout behaviors. The title bar will always be a of rectangular shape. In case of a non-rectangular UIElement, its rectangular bounding rectangle will be used for dimensions of the title bar.

Colors

A custom title bar uses an AppWindow title bar for its implementation. As a result, you can use AppWindowTitleBar theming APIs for colors like ButtonBackgroundColor, ButtonForegroundColor, etc.

The resource based theming used in earlier versions (like WindowCaptionBackground) is deprecated and doesn't have any effect.

Applies to