Window.SetTitleBar(UIElement) Method

Reference

Definition

Namespace:: Windows.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

Makes a XAML element interact with the system as if it’s the title bar.

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

void SetTitleBar(UIElement const& value);

public void SetTitleBar(UIElement value);

function setTitleBar(value)

Public Sub SetTitleBar (value As UIElement)

Parameters

value: UIElement

Custom XAML content that should act as the title bar. To use multiple objects, wrap them in a container element such as one derived from Panel.

Remarks

This method lets you specify a XAML element that interacts with the system as if it’s the app window's title bar. When you use this method, you typically set the CoreApplicationViewTitleBar.ExtendViewIntoTitleBar property to true in order to hide the default system title bar. However, even when the default system title bar is not hidden, this can be used to make additional regions in your app behave like the title bar.

Use the CoreApplicationView.TitleBar property to get the instance of CoreApplicationViewTitleBar for your app window, like this.

// Requires using Windows.ApplicationModel.Core
CoreApplicationView coreView = CoreApplication.GetCurrentView();
CoreApplicationViewTitleBar coreTitleBar = coreView.TitleBar;
coreTitleBar.ExtendViewIntoTitleBar = true;

// -- OR --

CoreApplication.GetCurrentView().TitleBar.ExtendViewIntoTitleBar = true;

Note

This method has no effect when an app is run on a mobile device, because apps are always full-screen on mobile devices and do not have a window title bar.

Input

When you call this method to set a XAML UIElement as the title bar, it lets Windows handle input to the title bar UIElement the same way it handles input to the default system title bar. For example, a user can move the window by dragging the XAML UIElement, or invoke the window context menu by right-clicking it.

This means that your app no longer receives pointer input when the user interacts with the target UIElement or its children using touch, mouse, or pen. However, you must still handle (or prevent) keyboard input, and determine whether content in the title bar can receive focus by tabbing to it with the keyboard.

Layout and appearance

You must update the visual content and layout of the target UIElement in response to title bar changes, like visibility and size.

To match the visibility of the system title bar, handle the CoreApplicationViewTitleBar.IsVisibleChanged event and respect the CoreApplicationViewTitleBar.IsVisible property by showing and hiding your custom title bar as appropriate. This ensures that your custom title bar content is correctly hidden when the system title bar is hidden; for example, when the user chooses to display your app in full-screen mode.

To ensure that your title bar matches the size of other title bar elements like the always-present system Minimize, Maximize, and Close buttons, handle the CoreApplicationViewTitleBar.LayoutMetricsChanged event and respect the CoreApplicationViewTitleBar.Height, SystemOverlayLeftInset, and SystemOverlayRightInset properties.

The default title bar buttons, such as Minimize, Maximize, and Close, are always shown by the system, so you might also want to modify their color to match your custom XAML title bar content. To do this, use the Windows.UI.ViewManagement.ApplicationView.TitleBar property to get the instance of ApplicationViewTitleBar for your app window. You can then set the various color properties on ApplicationViewTitleBar to modify the default buttons.

Applies to

Jaa