Window Window Window Class

Definition

Represents an application window.

public sealed class Window : IWindow, IWindow2, IWindow3public sealed class Window : IWindow, IWindow2, IWindow3Public NotInheritable Class Window Implements IWindow, IWindow2, IWindow3
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This class represents the window of the current Application. In the same manner as the static Application property, the static Current property will return the app window object. From this object, an app can utilize the Dispatcher or determine the size of the Window from the Bounds property. The most common usage for Window is setting a UIElement to the Content that represents the app UI. This is usually done as part of app activation (for example in the OnLaunched override.) You can change this window content throughout the lifetime of the window.

There is no XAML representation of the Window class because it is not a control.

A Window object is just surfacing information from CoreWindow, which in turn is referencing the window created by the system.

Make sure to call Activate on any Window you use on initial activation. If you use the default app templates from Microsoft Visual Studio, calling Window.Activate is part of the initial code in the app.xaml code-behind file.

The LayoutAwarePage class that is part of some application templates in Microsoft Visual Studio has handling for the SizeChanged event, which is used for keeping track of visual states that match values of ApplicationViewState. LayoutAwarePage also has code that checks Bounds and uses this value to influence how page-wide input events are handled.

Examples

The following code example shows the OnLaunched method override generated for the blank application template in Microsoft Visual Studio. This code demonstrates typical usage patterns for the Current and Content properties and the Activate method.

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    // Create a Frame to act navigation context and navigate to the first page
    var rootFrame = new Frame();
    rootFrame.Navigate(typeof(BlankPage));

    // Place the frame in the current Window and ensure that it is active
    Window.Current.Content = rootFrame;
    Window.Current.Activate();
}
Protected Overrides Sub OnLaunched(args As 
    Windows.ApplicationModel.Activation.LaunchActivatedEventArgs)

    ' Create a Frame to act navigation context and navigate to the first page
    Dim rootFrame As New Frame()
    rootFrame.Navigate(GetType(BlankPage))

    ' Place the frame in the current Window and ensure that it is active
    Window.Current.Content = rootFrame
    Window.Current.Activate()
End Sub

Properties

Bounds Bounds Bounds

Gets a Rect value containing the height and width of the application window in units of effective (view) pixels.

public Rect Bounds { get; }public Rect Bounds { get; }Public ReadOnly Property Bounds As Rect
Value
Rect Rect Rect

A value that reports the height and width of the application window.

Attributes

Compositor Compositor Compositor

Gets the Compositor for this window.

public Compositor Compositor { get; }public Compositor Compositor { get; }Public ReadOnly Property Compositor As Compositor
Value
Compositor Compositor Compositor

The Compositor for this window.

Attributes
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Content Content Content

Gets or sets the visual root of an application window.

public UIElement Content { get; set; }public UIElement Content { get; set; }Public ReadWrite Property Content As UIElement
Value
UIElement UIElement UIElement

The visual root of an application window.

Attributes

CoreWindow CoreWindow CoreWindow

Gets an internal core object for the application window.

public CoreWindow CoreWindow { get; }public CoreWindow CoreWindow { get; }Public ReadOnly Property CoreWindow As CoreWindow
Value
CoreWindow CoreWindow CoreWindow

A CoreWindow object.

Attributes

Current Current Current

Gets the currently activated window for an application.

public static Window Current { get; }public static Window Current { get; }Public Static ReadOnly Property Current As Window
Value
Window Window Window

The currently activated window.

Attributes

Dispatcher Dispatcher Dispatcher

Gets the CoreDispatcher object for the Window, which is generally the CoreDispatcher for the UI thread.

public CoreDispatcher Dispatcher { get; }public CoreDispatcher Dispatcher { get; }Public ReadOnly Property Dispatcher As CoreDispatcher
Value
CoreDispatcher CoreDispatcher CoreDispatcher

An object that references the UI thread for the Window.

Attributes

Visible Visible Visible

Gets a value that reports whether the window is visible.

public PlatForm::Boolean Visible { get; }public bool Visible { get; }Public ReadOnly Property Visible As bool
Value
bool bool bool

true if the window is visible; false if the window is not visible.

Attributes

Methods

Activate() Activate() Activate()

Attempts to activate the application window by bringing it to the foreground and setting the input focus to it.

public void Activate()public void Activate()Public Function Activate() As void
Attributes

Remarks

If you use the default app templates from Microsoft Visual Studio, Window.Activate is part of the initial code in the app.xaml code-behind file. Specifically, Activate is called from the default OnLaunched override. In cases where the template produces a page navigation experience, previous states are detected so that the navigation framework isn't overwritten if it already existed, but Activate is called regardless.

Calling Activate is required for all app activation scenario, not just app launch.

This method is important for the correct operation of an app. If an app does not call Activate on the Current window, and the app is not visible on screen, then the app will be terminated after 15 seconds. If the app or its splash screen is kept on screen there is no time limit, but eventually the app needs to call Activate to progress. Also, certain app contracts extend the time limit.

You can modify the default OnLaunched implementation in order to delay calling Activate. You might do this to have all app rendering be complete before the main Window is shown. For example, a delay can be useful to finish loading Image source files in the initial UI. (These load asynchronously and it's impractical to handle ImageOpened from app.xaml code-behind.) On the other hand, delaying the call can create an undesirable user experience if the splash screen is visible for too long.

For secondary windows, you also need to call Activate. Secondary windows are an uncommon scenario for most Windows Store app using C++, C#, or Visual Basic.

See Also

Close() Close() Close()

Closes the application window.

public void Close()public void Close()Public Function Close() As void
Attributes

Remarks

Windows Store app typically use a single Window instance, and do not open and close additional Window instances. Additionally, you will not typically provide custom UI to enable users to close the app window.

The Closed event occurs when a Window closes.

SetTitleBar(UIElement) SetTitleBar(UIElement) SetTitleBar(UIElement)

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

public void SetTitleBar(UIElement value)public void SetTitleBar(UIElement value)Public Function SetTitleBar(value As UIElement) As void
Parameters
value
UIElement UIElement 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.

Attributes

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.

Events

Activated Activated Activated

Occurs when the window has successfully been activated.

public event WindowActivatedEventHandler Activatedpublic event WindowActivatedEventHandler ActivatedPublic Event Activated
Attributes

Remarks

This event occurs when a Window has been activated or deactivated by the system. An app can determine what the status of the Window activation is by checking the WindowActivatedEventArgs.WindowActivationState property. A Window could be visible on screen but not be active (for example, in snapped apps). Additionally, if any other parts of the system takes focus away from the window, this event will occur. This could happen as a result of user interaction or code, and the WindowActivationState will indicate which action has taken place.

Examples

The following code example demonstrates a typical usage pattern for this event.

void Current_Activated(object sender, Windows.UI.Core.WindowActivatedEventArgs e)
{
    if (e.WindowActivationState == 
        Windows.UI.Core.CoreWindowActivationState.Deactivated)
    {
        // Show the "paused" UI. 
        VisualStateManager.GoToState(this, "PauseUI", false);
    }
    else if (e.WindowActivationState == 
        Windows.UI.Core.CoreWindowActivationState.PointerActivated)
    {
        // Show the "active" UI. 
        VisualStateManager.GoToState(this, "ActivateUI", false);
    }
}

Closed Closed Closed

Occurs when the window has closed.

public event WindowClosedEventHandler Closedpublic event WindowClosedEventHandler ClosedPublic Event Closed
Attributes

Remarks

The Closed event occurs when a Window closes. However, Windows Store app typically use a single Window instance, and do not open and close additional Window instances.

SizeChanged SizeChanged SizeChanged

Occurs when the app window has first rendered or has changed its rendering size.

public event WindowSizeChangedEventHandler SizeChangedpublic event WindowSizeChangedEventHandler SizeChangedPublic Event SizeChanged
Attributes

Remarks

This event occurs whenever there are changes in the Bounds values for the app window. This might be because the user resizes your app or changes the display orientation. Another trigger is if the user moves your app to a new display that has a different resolution and the app window expands to fill it.

Window.SizeChanged is the event to handle in order to detect that the user has deliberately resized your app or rotated the display on a PC that detects orientation. You may want to detect that the app window has changed from landscape to portrait orientation or vice versa. The app window orientation might influence how you want the individual controls within the app window to appear. For example, you might want to display data lists in a ListView for portrait orientation, but in a GridView for landscape orientation. Typically you would compare the ratio of Window.Current.Bounds.Width to Window.Current.Bounds.Height in order to determine the orientation based on the Bounds, and you'd do this whenever Window.SizeChanged fires. Exactly how you interpret width/height ratios is up to you.

If you're attaching handlers for Window.SizeChanged at the Page level within a handler for the FrameworkElement.Loaded event, you should detach those handlers in a FrameworkElement.Unloaded event handler from that Page. The Window.Current instance remains active between page navigations and should only have a handler active for the most current page code.

A Window.SizeChanged handler is not how you enforce the minimum size that your app can be resized to. That's controlled by the app manifest. However, your logic for changing the visual states should be able to load a state that's designed for the minimum width you intended, and you'd typically use the Bounds values and Window.SizeChanged handling to detect when the app window is using minimum width.

For more info on how to use Window.SizeChanged to detect changes in the app window environment and load the appropriate visual states for your app, see Quickstart: Designing apps for different window sizes.

There's another event named SizeChanged that exists on FrameworkElement derived types (Window is not a FrameworkElement type). FrameworkElement.SizeChanged events might fire in many of the same circumstances that cause Window.SizeChanged to fire. An app window size change can cause the root visual element (typically a Page or panel) to change its size. This sets off a cascade of layout invalidations for any the subelements that are using adaptive layout to fill available space. Each element that has new dimensions because of a layout pass will fire its own FrameworkElement.SizeChanged event.

See Also

VisibilityChanged VisibilityChanged VisibilityChanged

Occurs when the value of the Visible property changes.

public event WindowVisibilityChangedEventHandler VisibilityChangedpublic event WindowVisibilityChangedEventHandler VisibilityChangedPublic Event VisibilityChanged
Attributes

Remarks

VisibilityChangedEventArgs includes a Boolean Visible property that you should check to determine the current visibility state.

See Also