InputPointerSource Class

Definition

Namespace:

Microsoft.UI.Input

Represents an object that is registered to report pointer input and provide pointer cursor and input event handling.

public ref class InputPointerSource sealed : InputObject

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.Foundation.WindowsAppSDKContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class InputPointerSource final : InputObject

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.Foundation.WindowsAppSDKContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class InputPointerSource : InputObject

Public NotInheritable Class InputPointerSource
Inherits InputObject

Inheritance

Object Platform::Object IInspectable InputObject InputPointerSource

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

The following example shows how to configure a SwapChainPanel with CreateCoreIndependentInputSource and receive low-latency pen and touch input on a background thread through a DispatcherQueueController.

void SetupBackgroundPenInput(SwapChainPanel swapChainPanel)
{
    m_dispatcherQueueController = DispatcherQueueController::CreateOnDedicatedThread();

    m_dispatcherQueueController.DispatcherQueue().TryEnqueue([this] {

        InputPointerSourceDeviceKinds deviceKind = (InputPointerSourceDeviceKinds)(
            Microsoft::UI::Input::InputPointerSourceDeviceKinds::Touch |
            Microsoft::UI::Input::InputPointerSourceDeviceKinds::Pen);
        m_coreInput = swapChainPanel().CreateCoreIndependentInputSource(deviceKind);

        m_coreInput.PointerMoved({ this, &DirectXPage::SwapChainPanel_OnPointerMoved });
        });
}


void DirectXPage::SwapChainPanel_OnPointerPressed(InputPointerSource const& sender, Microsoft::UI::Input::PointerEventArgs const& e)
{
    // When the pointer is pressed begin tracking the pointer movement.
    m_main->StartTracking();
}

This example shows how to configure the system hand cursor image to display when the cursor hovers over a SwapChainPanel:

InputPointerSourceDeviceKinds deviceKind = (InputPointerSourceDeviceKinds)(
    Microsoft::UI::Input::InputPointerSourceDeviceKinds::Touch |
    Microsoft::UI::Input::InputPointerSourceDeviceKinds::Mouse |
    Microsoft::UI::Input::InputPointerSourceDeviceKinds::Pen);
m_coreInput = swapChainPanel().CreateCoreIndependentInputSource(deviceKind);

m_coreInput.InputCursor = InputSystemCursor.Create(InputSystemCursorShape.Hand);

Remarks

The coordinate space for the pointer events is in the same coordinate space as the SwapChainPanel object.

Event order

Normal Case

The pointer events of InputPointerSource follow a guaranteed order under normal circumstances:

1. PointerEntered
2. PointerPressed
3. PointerMoved
4. PointerReleased
5. PointerExited

Where PointerMoved will only be raised if the pointer moves or the button states on the mouse change. All events have the same pointer id.

Pointer capture lost

PointerCaptureLost is raised when an in-contact pointer is routed to a different input target by the input system. When PointerCaptureLost is raised, which will only happen after PointerPressed has been received, no additional events will be raised for that pointer. Specifically, PointerReleased and PointerExited will not be raised, so you should handle PointerCaptureLost as a valid end state for a given pointer. Here is an example of a valid sequence of events that includes losing pointer capture:

1. PointerEntered
2. PointerPressed
3. PointerMoved
4. PointerCaptureLost

Routed events

Pointer routed events are raised when an in-contact pointer is routed to a different input target by the input system. Unlike PointerCaptureLost, the routed events provide the possibility of the in-contact pointer being routed back before the pointer is released.

The following shows a valid sequence of events where the in-contact pointer is routed away to a different target, routed back to the original InputPointerSource, and then released:

1. PointerEntered
2. PointerPressed
3. PointerMoved
4. PointerRoutedAway
5. PointerRoutedTo
6. PointerReleased
7. PointerExited

Here is an example of a valid sequence of events where an in-contact pointer is routed away to a different target and then released on the other target:

1. PointerEntered
2. PointerPressed
3. PointerMoved
4. PointerRoutedAway
5. PointerRoutedReleased

Note

When PointerRoutedReleased is raised, no additional events will be raised for that pointer. Specifically, PointerReleased and PointerExited will not be raised, so you should handle PointerRoutedReleased as a valid end state for a given pointer.

It is also possible to receive a brand new in-contact pointer that was routed from a different target. In this case, the PointerEntered and PointerPressed events are guaranteed to precede a PointerRoutedTo if the pointer has not been seen by the current InputPointerSource yet. The following is an example of this sequence of events:

1. PointerEntered
2. PointerPressed
3. PointerRoutedTo
4. PointerMoved
5. PointerReleased
6. PointerExited

Properties

Cursor	Gets or sets the cursor displayed when a mouse or pen pointer is over the input target, a Visual or WindowId (HWND), of this InputPointerSource.
DeviceKinds	Gets the device types supported by this InputPointerSource.
DispatcherQueue	Gets the DispatcherQueue for the InputObject. (Inherited from InputObject)

Methods

GetForIsland(ContentIsland)

Retrieves an InputPointerSource object for the specified ContentIsland.

Events

PointerCaptureLost	Occurs when an pointer in contact with this InputPointerSource moves to another input target.
PointerEntered	Occurs when a pointer moves into the bounds of this InputPointerSource.
PointerExited	Occurs when a pointer moves out of the bounds of this InputPointerSource.
PointerMoved	Occurs when a pointer moves while within the bounds of this InputPointerSource.
PointerPressed	Occurs when a mouse button is pressed, or a finger or pen initiate contact with the digitizer surface, while within the bounds of this InputPointerSource.
PointerReleased	Occurs when a pointer device that previously initiated a Press action is released (a mouse button is released, or a touch or pen contact is lifted from the digitizer surface), while within the bounds of this InputPointerSource.
PointerRoutedAway	Occurs when a pointer is redirected to another InputPointerSource (possibly in a separate process).
PointerRoutedReleased	Occurs when s pointer that was routed to a different InputPointerSource is released on that other input target.
PointerRoutedTo	Occurs when a pointer is routed to this InputPointerSource from a different input target.
PointerWheelChanged	Occurs when the mouse wheel is rotated (the wheel delta value changes).

See also

• CreateForInputPointerSource(InputPointerSource)