語言

UIElement.CapturePointer(Pointer) 方法

定義

命名空間:
Microsoft.UI.Xaml
編輯

將指標擷取設定到 UIElement。 一旦被捕獲，只有被捕獲的元素會觸發與指標相關的事件。

public:
 virtual bool CapturePointer(Pointer ^ value) = CapturePointer;
bool CapturePointer(Pointer const& value);
public bool CapturePointer(Pointer value);
function capturePointer(value)
Public Function CapturePointer (value As Pointer) As Boolean

參數

value
Pointer

指標物件參考。

傳回

Boolean

bool

true如果物件有指標捕獲;否則，。 false

範例

這個範例顯示了基於處理 PointerPressed 的呼叫CapturePointer。 它也顯示了追蹤和計數指標參考的模式。

int _pointerCount;

public Scenario2()
{
    this.InitializeComponent();
    bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
    bEnteredExited.PointerExited += bEnteredExited_PointerExited;
    bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
    bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
    bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;

    // To code for multiple Pointers (that is, fingers), 
    // we track how many entered/exited.
    _pointerCount = 0;
}

private void bEnteredExited_PointerMoved(object sender, 
    PointerRoutedEventArgs e)
{
    Scenario2UpdateVisuals(sender as Border, "Moved");
}

private void bEnteredExited_PointerReleased(object sender, 
    PointerRoutedEventArgs e)
{
    ((Border)sender).ReleasePointerCapture(e.Pointer);
    txtCaptureStatus.Text = string.Empty;
}

//Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
private void bEnteredExited_PointerPressed(object sender, 
    PointerRoutedEventArgs e)
{
    if (tbPointerCapture.IsOn)
    {
        bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
        txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
    }
}

private void bEnteredExited_PointerExited(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount--;
    Scenario2UpdateVisuals(sender as Border, "Exited");
}

private void bEnteredExited_PointerEntered(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount++;
    Scenario2UpdateVisuals(sender as Border, "Entered");
}

private void Scenario2UpdateVisuals(Border border, 
    String eventDescription)
{
    switch (eventDescription.ToLower())
    {
        case "exited":
            if (_pointerCount <= 0)
            {
                border.Background = new SolidColorBrush(Colors.Red);
                bEnteredExitedTextBlock.Text = eventDescription;
            }
            break;
        case "moved":
            RotateTransform rt = 
                (RotateTransform)bEnteredExitedTimer.RenderTransform;
            rt.Angle += 2;
            if (rt.Angle > 360) rt.Angle -= 360;
            break;
        default:
            border.Background = new SolidColorBrush(Colors.Green);
            bEnteredExitedTextBlock.Text = eventDescription;
            break;
    }
}

private void Scenario2Reset(object sender, RoutedEventArgs e)
{
    Scenario2Reset();
}

private void Scenario2Reset()
{
    bEnteredExited.Background = new SolidColorBrush(Colors.Green);
    bEnteredExitedTextBlock.Text = string.Empty;
}

備註

只有當指標處於按下狀態（Pointer.IsInContact 應該是 true）時，才能成功擷取該指標。 實際被按下的感覺會依指標裝置類型而異（滑鼠按鍵按下、觸控點朝下、觸控筆接觸）。 如果你嘗試捕捉一個未被按下的指標，或是該指標之前被按下但現在放開的位置，CapturePointer 會返回 false。 現有的捕獲不會受到 CapturePointer 回 false傳的通話影響。

你通常會在 PointerPressed 事件處理器中擷取指標。 你從處理器的 PointerRoutedEventArgs 事件資料PointerPressed中取得的指標實例，就是你從處理器程式碼呼叫CapturePointer時應該傳遞value的參數值。

你通常會擷取指標，是因為你希望目前的指標動作能在應用程式中啟動行為。 在這種情況下，通常你不希望其他元素處理該指標動作產生的其他事件，直到你的行為完成或透過釋放指標擷取而取消。 如果指標被捕獲，只有捕獲的元素會收到該指標的輸入事件，其他元素即使指標進入其界限也不會觸發事件。 舉例來說，考慮一個有兩個相鄰元素的 UI。 通常，如果你把指標從一個元素移到另一個元素，你會先從第一個元素觸發 PointerMoved 事件，然後再從第二個元素觸發。 但如果第一個元素已經捕獲了指標，那麼即使捕獲指標離開其界限，第一個元素仍會繼續接收 PointerMoved 事件。 另外，當捕獲指標進入 PointerEntered 時，第二個元素不會觸發 PointerEntered 事件。

指標擷取狀態和產生與指標擷取相關的事件，並不完全取決於應用程式程式碼。 如果使用者放開指標，會產生 一個 PointerReleased 事件，且與該指標相關的指標擷取將遺失。 這同時也會對原始捕獲元素觸發 PointerCaptureLost 的訊號。

大多數情況下，當使用者完成一個輸入動作，釋放前一個指標捕捉時，指標擷取會自動釋放（例如舉起觸控點、放開左鍵、將觸控筆移出範圍）。 另一個可能釋放捕獲的條件是任何同時觸發 PointerCanceled 事件的動作。 你的應用程式通常可以依賴使用者輸入動作相關的擷取-釋放行為，而不必特別用 ReleasePointerCapture 或 ReleasePointerCaptures 取消指標擷取。 更多資訊請參見 滑鼠互動。

如果指標已被捕獲，方法 CapturePointer 會回傳 false 。

UIElement 可以同時擷取多個指標點。 用參數 value 來表示你想捕捉的 指標 實例。

代表手勢的輸入事件（如 Tapped 或 DoubleTapped）通常只會在指標放開後觸發，因此你不應該嘗試在事件處理程序中捕捉手勢事件的指標。 事件資料中的 指標 引用不會被允許啟動指標擷取。

Tip

不要嘗試使用 CapturePointer 指標相關輸入事件處理程式的範圍外。 除非你有一個指標 ，確定該 指標當時允許使用指標擷取，否則你的 CapturePointer 呼叫不會有任何影響。 沒有實際的方法能產生新的 Pointer 指標並用 CapturePointer 這個新指標呼叫。 你應該只使用 Pointer 系統透過指標相關輸入事件事件資料提供的參考。

適用於

另請參閱