Window Window Window Class

Represents an application window.

Syntax

Declaration

public sealed class Windowpublic sealed class WindowPublic NotInheritable Class Window

Remarks

This class represents the window of the current Application. In the same manner as the static @Windows.UI.Xaml.Application.#ctor 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(Windows.ApplicationModel.Activation.LaunchActivatedEventArgs) 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 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(Windows.ApplicationModel.Activation.LaunchActivatedEventArgs) 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 summary

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

Gets or sets the visual root of an application window.

Gets an internal core object for the application window.

Gets the currently activated window for an application.

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

Gets a value that reports whether the window is visible.

Prerelease. Gets the Compositor for this window.

Methods summary

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

Closes the application window.

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

Events summary

Occurs when the window has successfully been activated.

Occurs when the window has closed.

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

Occurs when the value of the Visible property changes.

Properties

  • Bounds
    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

    Property Value

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

  • Content
    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

    Property Value

  • CoreWindow
    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

    Property Value

  • Current
    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

    Property Value

  • Dispatcher
    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

    Property Value

  • Visible
    Visible
    Visible
    Visible

    Gets a value that reports whether the window is visible.

    public bool Visible { get; }public bool Visible { get; }Public ReadOnly Property Visible As bool

    Property Value

    • bool
      bool
      bool

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

  • Compositor
    Compositor
    Compositor
    Compositor

    Prerelease. Gets the Compositor for this window.

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

    Property Value

Methods

  • Activate()
    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

    Remarks

    If you use the default app templates from Microsoft Visual Studio, Activate() is part of the initial code in the app.xaml code-behind file. Specifically, Activate() is called from the default OnLaunched(Windows.ApplicationModel.Activation.LaunchActivatedEventArgs) 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(Windows.ApplicationModel.Activation.LaunchActivatedEventArgs) 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.

  • Close()
    Close()
    Close()
    Close()

    Closes the application window.

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

    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(Windows.UI.Xaml.UIElement)
    SetTitleBar(Windows.UI.Xaml.UIElement)
    SetTitleBar(Windows.UI.Xaml.UIElement)
    SetTitleBar(Windows.UI.Xaml.UIElement)

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

    public void SetTitleBar(Windows.UI.Xaml.UIElement value)public void SetTitleBar(Windows.UI.Xaml.UIElement value)Public Function SetTitleBar(value As Windows.UI.Xaml.UIElement) As void

    Parameters

    • value

      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 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 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 IsVisibleChanged event and respect the 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 LayoutMetricsChanged event and respect the 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 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
    Activated

    Occurs when the window has successfully been activated.

    public event WindowActivatedEventHandler Activatedpublic event WindowActivatedEventHandler ActivatedPublic Event Activated

    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 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
    Closed

    Occurs when the window has closed.

    public event WindowClosedEventHandler Closedpublic event WindowClosedEventHandler ClosedPublic Event Closed

    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
    SizeChanged

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

    public event WindowSizeChangedEventHandler SizeChangedpublic event WindowSizeChangedEventHandler SizeChangedPublic Event SizeChanged

    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.

    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 SizeChanged fires. Exactly how you interpret width/height ratios is up to you.

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

    A 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 SizeChanged handling to detect when the app window is using minimum width.

    For more info on how to use 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). SizeChanged events might fire in many of the same circumstances that cause 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 SizeChanged event.

  • VisibilityChanged
    VisibilityChanged
    VisibilityChanged
    VisibilityChanged

    Occurs when the value of the Visible property changes.

    public event WindowVisibilityChangedEventHandler VisibilityChangedpublic event WindowVisibilityChangedEventHandler VisibilityChangedPublic Event VisibilityChanged

    Remarks

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

Attributes

Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.UI.Xaml.dll