CoreWindow CoreWindow CoreWindow Class

Represents the Windows Store app with input events and basic user interface behaviors.

Syntax

Declaration

public sealed class CoreWindowpublic sealed class CoreWindowPublic NotInheritable Class CoreWindow

Remarks

New instances of this class are obtained by calling CreateNewView(IFrameworkViewSource) and then inspecting the CoreWindow property on the returned CoreApplicationView instance. Or you can obtain existing CoreWindow instances for a running app from the Views property, or by calling GetForCurrentThread(), as seen in the following example.

void MyCoreWindowEvents::Run() // this is an implementation of IFrameworkView::Run() used to show context
{
    CoreWindow::GetForCurrentThread()->Activate();

    /...

    CoreWindow::GetForCurrentThread()->Dispatcher->ProcessEvents(CoreProcessEventsOption::ProcessUntilQuit);
}
Note

: This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see Threading and Marshaling (C++/CX).

Properties summary

Gets the automation provider assigned to this window.

Gets the bounding rectangle of the window.

Gets the set of custom properties for the window.

Gets the event dispatcher for the window.

Gets or sets the horizontal origin of the window's reading order alignment. If the language specified by the user interface is right-aligned (such as in Arabic or Hebrew), the horizontal origin of the reading layout for the window is on the right edge.

Gets or sets a value that indicates whether input is enabled for the app.

Gets or sets the cursor used by the app.

Gets the client coordinates of the pointer.

Gets a value that indicates whether the window is visible.

Methods summary

Activates the window. This method is called to present the window on the screen.

Closes a secondary window and exits the message loop.

Asynchronously retrieves the state of a virtual key.

Retrieves the unique ID for the input device that generated this key event.

GetCurrentKeyEventDeviceId() is not supported for all input devices.

Gets the CoreWindow instance for the currently active thread.

Retrieves the state of a virtual key.

Dissociates pointer input from the app, if previously associated through SetPointerCapture(), and restores normal pointer input processing.

Associates pointer input with the app. Once a pointer is captured, all subsequent events associated with that pointer are fired by the app.

Events summary

Is fired when the window completes activation or deactivation.

Is fired when a request for an automation handler is generated.

Is fired when a new character is received by the input queue.

Is fired when the app terminates.

Note

Not intended for general use.

Occurs when a framework input manager requests the bounding rectangle of an interactive element within a specific bounding rectangle and closest to a specific pointer.

Occurs when input is enabled or disabled for the app.

Is fired when a non-system key is pressed.

Is fired when a non-system key is released after a press.

Occurs when a pointer moves to another app. This event is raised after PointerExited and is the final event received by the app for this pointer.

Occurs when a pointer moves into the bounding box of the app.

Occurs when the pointer moves outside the bounding box of the app.

Occurs when a pointer moves within the bounding box of the app.

Occurs when a mouse button is clicked, or the digitizer surface has been touched by a finger or pen, within the bounding rectangle of the app.

An interaction session starts when a single contact is detected and ends when that contact, and all subsequent contacts in the same session, are no longer detected.

This event is fired for the first contact detected in the interaction session. Details for all other concurrent contact pointers are exposed through a PointerPointProperties object (obtained by getting the Properties property from a PointerPoint object).

Occurs when a pressed mouse button is released, or a touch or pen contact is lifted from the digitizer surface, within the bounding rectangle of the app (or outside the bounding rectangle, if the pointer is captured).

Occurs on the process receiving input when the pointer input is routed to another process.

Occurs on a process associated with, but not currently receiving input from, a pointer that fires a PointerReleased event on a different process.

Occurs on the process not currently receiving input, but designated to begin receiving input from another process.

Occurs when the wheel button is rotated.

Prerelease. Occurs when a user finishes resizing the window.

Prerelease. Occurs when a user starts to resize the window.

Occurs when the window size is changed.

Occurs when a touch contact area intersects the bounding rectangle (or polygon) of a window that is registered for touch hit testing.

Is fired when the window visibility is changed.

Properties

  • AutomationHostProvider
    AutomationHostProvider
    AutomationHostProvider
    AutomationHostProvider

    Gets the automation provider assigned to this window.

    public object AutomationHostProvider { get; }public object AutomationHostProvider { get; }Public ReadOnly Property AutomationHostProvider As objectpublic object AutomationHostProvider { get; }

    Property Value

    • object
      object
      object

      The automation provider for this window.

  • Bounds
    Bounds
    Bounds
    Bounds

    Gets the bounding rectangle of the window.

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

    Property Value

    • The bounding rectangle of the window, in device-independent pixels (DIPs).

    Remarks

    To convert from DIPs to physical pixels (and back), use these equations (where DPI is the dots per inch value for the screen):

    • DIP value = (physical pixel x 96) / DPI
    • physical pixel value = (DIP x DPI) / 96
  • CustomProperties
    CustomProperties
    CustomProperties
    CustomProperties

    Gets the set of custom properties for the window.

    public IPropertySet CustomProperties { get; }public IPropertySet CustomProperties { get; }Public ReadOnly Property CustomProperties As IPropertySetpublic IPropertySet CustomProperties { get; }

    Property Value

  • Dispatcher
    Dispatcher
    Dispatcher
    Dispatcher

    Gets the event dispatcher for the window.

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

    Property Value

  • FlowDirection
    FlowDirection
    FlowDirection
    FlowDirection

    Gets or sets the horizontal origin of the window's reading order alignment. If the language specified by the user interface is right-aligned (such as in Arabic or Hebrew), the horizontal origin of the reading layout for the window is on the right edge.

    public CoreWindowFlowDirection FlowDirection { get; set; }public CoreWindowFlowDirection FlowDirection { get; set; }Public ReadWrite Property FlowDirection As CoreWindowFlowDirectionpublic CoreWindowFlowDirection FlowDirection { get; set; }

    Property Value

  • IsInputEnabled
    IsInputEnabled
    IsInputEnabled
    IsInputEnabled

    Gets or sets a value that indicates whether input is enabled for the app.

    public bool IsInputEnabled { get; set; }public bool IsInputEnabled { get; set; }Public ReadWrite Property IsInputEnabled As boolpublic bool IsInputEnabled { get; set; }

    Property Value

    • bool
      bool
      bool

      True if input is enabled for the app; false if it is disabled.

  • PointerCursor
    PointerCursor
    PointerCursor
    PointerCursor

    Gets or sets the cursor used by the app.

    public CoreCursor PointerCursor { get; set; }public CoreCursor PointerCursor { get; set; }Public ReadWrite Property PointerCursor As CoreCursorpublic CoreCursor PointerCursor { get; set; }

    Property Value

  • PointerPosition
    PointerPosition
    PointerPosition
    PointerPosition

    Gets the client coordinates of the pointer.

    public Point PointerPosition { get; set; }public Point PointerPosition { get; set; }Public ReadWrite Property PointerPosition As Pointpublic Point PointerPosition { get; set; }

    Property Value

    • The position of the pointer in device-independent pixel (DIP).

    Remarks

    You cannot read the pointer position with this API when the lock screen is present.

  • Visible
    Visible
    Visible
    Visible

    Gets a value that indicates whether the window is visible.

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

    Property Value

    • bool
      bool
      bool

      True if the window is visible on the screen; false if it is not.

Methods

  • Activate()
    Activate()
    Activate()
    Activate()

    Activates the window. This method is called to present the window on the screen.

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

    Remarks

    The window is presented if the app is the foreground window. If the app has more than one window, the activating window is presented when the app is set to the foreground.

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

    Closes a secondary window and exits the message loop.

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

    Remarks

    This method also causes the ProcessEvents(CoreProcessEventsOption) operation to exit the event-processing loop.

  • GetAsyncKeyState(VirtualKey)
    GetAsyncKeyState(VirtualKey)
    GetAsyncKeyState(VirtualKey)
    GetAsyncKeyState(VirtualKey)

    Asynchronously retrieves the state of a virtual key.

    public CoreVirtualKeyStates GetAsyncKeyState(VirtualKey virtualKey)public CoreVirtualKeyStates GetAsyncKeyState(VirtualKey virtualKey)Public Function GetAsyncKeyState(virtualKey As VirtualKey) As CoreVirtualKeyStatespublic CoreVirtualKeyStates GetAsyncKeyState(VirtualKey virtualKey)

    Parameters

    Returns

  • GetCurrentKeyEventDeviceId()
    GetCurrentKeyEventDeviceId()
    GetCurrentKeyEventDeviceId()
    GetCurrentKeyEventDeviceId()

    Retrieves the unique ID for the input device that generated this key event.

    GetCurrentKeyEventDeviceId() is not supported for all input devices.

    public string GetCurrentKeyEventDeviceId()public string GetCurrentKeyEventDeviceId()Public Function GetCurrentKeyEventDeviceId() As stringpublic string GetCurrentKeyEventDeviceId()

    Returns

    • string
      string
      string

      A unique identifier for the input device associated with the key event, or an empty string. The same device can be assigned a different ID each time it is connected.

      After a key event is processed, this method returns an empty string.

    Remarks

    Use GetCurrentKeyEventDeviceId() to differentiate between devices that can generate key events, such as multiple Xbox controllers. The device id is useful for associating the input device with a specific user account.

    To get a valid device ID, this method must be called from your KeyUp and KeyDown event handlers.

  • GetForCurrentThread()
    GetForCurrentThread()
    GetForCurrentThread()
    GetForCurrentThread()

    Gets the CoreWindow instance for the currently active thread.

    public static CoreWindow GetForCurrentThread()public static CoreWindow GetForCurrentThread()Public Static Function GetForCurrentThread() As CoreWindowpublic static CoreWindow GetForCurrentThread()

    Returns

  • GetKeyState(VirtualKey)
    GetKeyState(VirtualKey)
    GetKeyState(VirtualKey)
    GetKeyState(VirtualKey)

    Retrieves the state of a virtual key.

    public CoreVirtualKeyStates GetKeyState(VirtualKey virtualKey)public CoreVirtualKeyStates GetKeyState(VirtualKey virtualKey)Public Function GetKeyState(virtualKey As VirtualKey) As CoreVirtualKeyStatespublic CoreVirtualKeyStates GetKeyState(VirtualKey virtualKey)

    Parameters

    Returns

  • ReleasePointerCapture()
    ReleasePointerCapture()
    ReleasePointerCapture()
    ReleasePointerCapture()

    Dissociates pointer input from the app, if previously associated through SetPointerCapture(), and restores normal pointer input processing.

    public void ReleasePointerCapture()public void ReleasePointerCapture()Public Function ReleasePointerCapture() As voidpublic void ReleasePointerCapture()
  • SetPointerCapture()
    SetPointerCapture()
    SetPointerCapture()
    SetPointerCapture()

    Associates pointer input with the app. Once a pointer is captured, all subsequent events associated with that pointer are fired by the app.

    public void SetPointerCapture()public void SetPointerCapture()Public Function SetPointerCapture() As voidpublic void SetPointerCapture()

    Remarks

    A pointer can be captured only by a single app at any time. Only the foreground window can capture the pointer. Pointer events continue even if the pointer moves outside the bounds of the app.

    A pointer can only be captured when contact is detected (mouse button pressed, touch contact down, stylus in contact), and the pointer is within the bounding rectangle of the app.

    The pointer is released on a PointerReleased or a PointerCaptureLost event, or ReleasePointerCapture() is explicitly called.

Events

  • Activated
    Activated
    Activated
    Activated

    Is fired when the window completes activation or deactivation.

    public event TypedEventHandler Activatedpublic event TypedEventHandler ActivatedPublic Event Activatedpublic event TypedEventHandler Activated
  • AutomationProviderRequested
    AutomationProviderRequested
    AutomationProviderRequested
    AutomationProviderRequested

    Is fired when a request for an automation handler is generated.

    public event TypedEventHandler AutomationProviderRequestedpublic event TypedEventHandler AutomationProviderRequestedPublic Event AutomationProviderRequestedpublic event TypedEventHandler AutomationProviderRequested
  • CharacterReceived
    CharacterReceived
    CharacterReceived
    CharacterReceived

    Is fired when a new character is received by the input queue.

    public event TypedEventHandler CharacterReceivedpublic event TypedEventHandler CharacterReceivedPublic Event CharacterReceivedpublic event TypedEventHandler CharacterReceived

    Remarks

    Apps do not receive this event when an is enabled. The Input Method Editor (IME) handles all keyboard input and sets Handled to true.

  • Closed
    Closed
    Closed
    Closed

    Is fired when the app terminates.

    public event TypedEventHandler Closedpublic event TypedEventHandler ClosedPublic Event Closedpublic event TypedEventHandler Closed

    Remarks

    Note

    Apps are typically suspended, not terminated. As a result, this event is rarely fired, if ever.

  • ClosestInteractiveBoundsRequested
    ClosestInteractiveBoundsRequested
    ClosestInteractiveBoundsRequested
    ClosestInteractiveBoundsRequested
    Note

    Not intended for general use.

    Occurs when a framework input manager requests the bounding rectangle of an interactive element within a specific bounding rectangle and closest to a specific pointer.

    public event TypedEventHandler ClosestInteractiveBoundsRequestedpublic event TypedEventHandler ClosestInteractiveBoundsRequestedPublic Event ClosestInteractiveBoundsRequestedpublic event TypedEventHandler ClosestInteractiveBoundsRequested
  • InputEnabled
    InputEnabled
    InputEnabled
    InputEnabled

    Occurs when input is enabled or disabled for the app.

    public event TypedEventHandler InputEnabledpublic event TypedEventHandler InputEnabledPublic Event InputEnabledpublic event TypedEventHandler InputEnabled
  • KeyDown
    KeyDown
    KeyDown
    KeyDown

    Is fired when a non-system key is pressed.

    public event TypedEventHandler KeyDownpublic event TypedEventHandler KeyDownPublic Event KeyDownpublic event TypedEventHandler KeyDown

    Remarks

    Apps do not receive this event when an is enabled. The Input Method Editor (IME) handles all keyboard input and sets Handled to true.

  • KeyUp
    KeyUp
    KeyUp
    KeyUp

    Is fired when a non-system key is released after a press.

    public event TypedEventHandler KeyUppublic event TypedEventHandler KeyUpPublic Event KeyUppublic event TypedEventHandler KeyUp

    Remarks

    Apps do not receive this event when an IME is enabled. The Input Method Editor (IME) handles all keyboard input and sets Handled to true.

  • PointerCaptureLost
    PointerCaptureLost
    PointerCaptureLost
    PointerCaptureLost

    Occurs when a pointer moves to another app. This event is raised after PointerExited and is the final event received by the app for this pointer.

    public event TypedEventHandler PointerCaptureLostpublic event TypedEventHandler PointerCaptureLostPublic Event PointerCaptureLostpublic event TypedEventHandler PointerCaptureLost
  • PointerEntered
    PointerEntered
    PointerEntered
    PointerEntered

    Occurs when a pointer moves into the bounding box of the app.

    public event TypedEventHandler PointerEnteredpublic event TypedEventHandler PointerEnteredPublic Event PointerEnteredpublic event TypedEventHandler PointerEntered

    Remarks

    For touch input, the app receives this event before a PointerPressed event.

  • PointerExited
    PointerExited
    PointerExited
    PointerExited

    Occurs when the pointer moves outside the bounding box of the app.

    public event TypedEventHandler PointerExitedpublic event TypedEventHandler PointerExitedPublic Event PointerExitedpublic event TypedEventHandler PointerExited

    Remarks

    For touch input, the app receives this event before a PointerPressed event.

  • PointerMoved
    PointerMoved
    PointerMoved
    PointerMoved

    Occurs when a pointer moves within the bounding box of the app.

    public event TypedEventHandler PointerMovedpublic event TypedEventHandler PointerMovedPublic Event PointerMovedpublic event TypedEventHandler PointerMoved
  • PointerPressed
    PointerPressed
    PointerPressed
    PointerPressed

    Occurs when a mouse button is clicked, or the digitizer surface has been touched by a finger or pen, within the bounding rectangle of the app.

    An interaction session starts when a single contact is detected and ends when that contact, and all subsequent contacts in the same session, are no longer detected.

    This event is fired for the first contact detected in the interaction session. Details for all other concurrent contact pointers are exposed through a PointerPointProperties object (obtained by getting the Properties property from a PointerPoint object).

    public event TypedEventHandler PointerPressedpublic event TypedEventHandler PointerPressedPublic Event PointerPressedpublic event TypedEventHandler PointerPressed
  • PointerReleased
    PointerReleased
    PointerReleased
    PointerReleased

    Occurs when a pressed mouse button is released, or a touch or pen contact is lifted from the digitizer surface, within the bounding rectangle of the app (or outside the bounding rectangle, if the pointer is captured).

    public event TypedEventHandler PointerReleasedpublic event TypedEventHandler PointerReleasedPublic Event PointerReleasedpublic event TypedEventHandler PointerReleased

    Remarks

    An interaction session starts when a single contact is detected and ends when that contact, and all subsequent contacts in the same session, are no longer detected.

    This event is fired for each contact detected in the interaction session (except for mouse, where this event is fired only when the last mouse button is released).

  • PointerRoutedAway
    PointerRoutedAway
    PointerRoutedAway
    PointerRoutedAway

    Occurs on the process receiving input when the pointer input is routed to another process.

    public event TypedEventHandler PointerRoutedAwaypublic event TypedEventHandler PointerRoutedAwayPublic Event PointerRoutedAwaypublic event TypedEventHandler PointerRoutedAway

    Remarks

    This event is not fired on a PointerReleased event.

  • PointerRoutedReleased
    PointerRoutedReleased
    PointerRoutedReleased
    PointerRoutedReleased

    Occurs on a process associated with, but not currently receiving input from, a pointer that fires a PointerReleased event on a different process.

    public event TypedEventHandler PointerRoutedReleasedpublic event TypedEventHandler PointerRoutedReleasedPublic Event PointerRoutedReleasedpublic event TypedEventHandler PointerRoutedReleased
  • PointerRoutedTo
    PointerRoutedTo
    PointerRoutedTo
    PointerRoutedTo

    Occurs on the process not currently receiving input, but designated to begin receiving input from another process.

    public event TypedEventHandler PointerRoutedTopublic event TypedEventHandler PointerRoutedToPublic Event PointerRoutedTopublic event TypedEventHandler PointerRoutedTo

    Remarks

    This event is not fired on a PointerPressed event.

  • PointerWheelChanged
    PointerWheelChanged
    PointerWheelChanged
    PointerWheelChanged

    Occurs when the wheel button is rotated.

    public event TypedEventHandler PointerWheelChangedpublic event TypedEventHandler PointerWheelChangedPublic Event PointerWheelChangedpublic event TypedEventHandler PointerWheelChanged
  • ResizeCompleted
    ResizeCompleted
    ResizeCompleted
    ResizeCompleted

    Prerelease. Occurs when a user finishes resizing the window.

    public event TypedEventHandler ResizeCompletedpublic event TypedEventHandler ResizeCompletedPublic Event ResizeCompletedpublic event TypedEventHandler ResizeCompleted
  • ResizeStarted
    ResizeStarted
    ResizeStarted
    ResizeStarted

    Prerelease. Occurs when a user starts to resize the window.

    public event TypedEventHandler ResizeStartedpublic event TypedEventHandler ResizeStartedPublic Event ResizeStartedpublic event TypedEventHandler ResizeStarted
  • SizeChanged
    SizeChanged
    SizeChanged
    SizeChanged

    Occurs when the window size is changed.

    public event TypedEventHandler SizeChangedpublic event TypedEventHandler SizeChangedPublic Event SizeChangedpublic event TypedEventHandler SizeChanged

    Remarks

    The SizeChanged event is exposed to XAML apps as the SizeChanged event and to HTML apps as the window.resize event.

    This event occurs when the window size changes or when one of the following properties changes:

  • TouchHitTesting
    TouchHitTesting
    TouchHitTesting
    TouchHitTesting

    Occurs when a touch contact area intersects the bounding rectangle (or polygon) of a window that is registered for touch hit testing.

    public event TypedEventHandler TouchHitTestingpublic event TypedEventHandler TouchHitTestingPublic Event TouchHitTestingpublic event TypedEventHandler TouchHitTesting
  • VisibilityChanged
    VisibilityChanged
    VisibilityChanged
    VisibilityChanged

    Is fired when the window visibility is changed.

    public event TypedEventHandler VisibilityChangedpublic event TypedEventHandler VisibilityChangedPublic Event VisibilityChangedpublic event TypedEventHandler VisibilityChanged

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

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

Details

Assembly

Windows.UI.Core.dll