UIElement.CapturePointer(Pointer) Méthode

  • Référence

Définition

Espace de noms:
Microsoft.UI.Xaml
Modifier

Définit la capture de pointeur sur un UIElement. Une fois capturé, seul l’élément qui a la capture déclenche des événements liés au pointeur.

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

Paramètres

value
Pointer

Référence de l’objet pointeur.

Retours

Boolean

bool

true si l’objet a une capture de pointeur ; sinon, false.

Exemples

Cet exemple montre comment appeler CapturePointer en fonction de la gestion de PointerPressed. Il affiche également un modèle pour le suivi et le comptage des références de pointeur.

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;
}

Remarques

Vous ne pouvez capturer correctement le pointeur que si ce pointeur est à l’état enfoncé (Pointer.IsInContact doit être true). Ce qui constitue physiquement le fait d’être appuyé varie en fonction du type d’appareil du pointeur (bouton de la souris appuyé, point tactile vers le bas, stylet en contact). Si vous tentez de capturer un pointeur qui n’est pas enfoncé, ou si le pointeur a été précédemment appuyé mais est maintenant libéré, CapturePointer retourne false. Les captures existantes ne sont pas affectées par un CapturePointer appel qui a retourné false.

Vous capturez généralement le pointeur dans un gestionnaire d’événements PointerPressed . Le pointeur instance que vous obtenez à partir des données d’événement PointerRoutedEventArgs de votre PointerPressed gestionnaire est la valeur que vous devez passer pour le value paramètre lorsque vous appelez CapturePointer à partir du code de votre gestionnaire.

Vous capturez généralement le pointeur, car vous souhaitez que l’action actuelle du pointeur initie un comportement dans votre application. Dans ce cas, vous ne souhaitez généralement pas que d’autres éléments gèrent d’autres événements provenant des actions de ce pointeur, jusqu’à ce que votre comportement soit terminé ou annulé en libérant la capture de pointeur. Si un pointeur est capturé, seul l’élément qui a la capture obtient les événements d’entrée du pointeur, et les autres éléments ne déclenchent pas d’événements même si le pointeur se déplace dans leurs limites. Par exemple, considérez une interface utilisateur qui a deux éléments adjacents. Normalement, si vous avez déplacé le pointeur d’un élément à l’autre, vous obtenez d’abord les événements PointerMoved à partir du premier élément, puis du deuxième élément. Mais si le premier élément a capturé le pointeur, le premier élément continue de recevoir PointerMoved des événements même si le pointeur capturé quitte ses limites. En outre, le deuxième élément ne déclenche pas d’événements PointerEntered pour un pointeur capturé lorsque le pointeur capturé y entre.

L’état de capture du pointeur et la génération des événements liés à la capture de pointeur ne dépendent pas entièrement du code d’application. Si l’utilisateur libère le pointeur, cela génère un événement PointerReleased et les captures de pointeur associées à ce pointeur sont perdues. Cela déclenche également PointerCaptureLost sur l’élément de capture d’origine.

Dans la plupart des cas, la capture de pointeur est relâchée automatiquement lorsque l’utilisateur termine une action d’entrée qui libère la capture précédente du pointeur (levée d’un point tactile, relâchement du bouton gauche de la souris, sortie du stylet). Une autre condition susceptible de libérer la capture est toute action qui déclenche également un événement PointerCanceled . Votre application peut généralement s’appuyer sur le comportement de capture-release associé aux actions d’entrée utilisateur, sans avoir à annuler spécifiquement une capture de pointeur avec ReleasePointerCapture ou ReleasePointerCaptures. Pour plus d’informations, voir Interactions avec la souris.

La CapturePointer méthode retourne false si le pointeur a déjà été capturé.

Un UIElement peut capturer plusieurs points de pointeur à la fois. Utilisez le value paramètre pour indiquer le pointeur instance que vous souhaitez capturer.

Les événements d’entrée qui représentent des mouvements (tels que Tappped ou DoubleTapped) sont généralement déclenchés uniquement après la libération d’un pointeur. Vous ne devez donc pas tenter de capturer un pointeur dans les gestionnaires d’événements de mouvement. La référence pointeur dans les données d’événement pour les événements de mouvement ne sera pas autorisée à lancer une capture de pointeur.

Conseil

N’essayez pas d’utiliser CapturePointer en dehors de l’étendue des gestionnaires d’événements d’entrée pertinents pour le pointeur. Sauf si vous avez un pointeur que vous êtes sûr d’être associé à un pointeur qui est autorisé à avoir la capture de pointeur à ce moment-là, votre appel CapturePointer n’aura aucun effet. Il n’existe aucun moyen pratique de générer un nouvel Pointer appel CapturePointer et à l’aide de ce nouveau pointeur. Vous devez uniquement utiliser les Pointer références que le système vous fournit via les données d’événement des événements d’entrée liés au pointeur.

S’applique à

Voir aussi