Vue d'ensemble des événements attachésAttached Events Overview

Extensible Application Markup Language (XAML) définit un composant linguistique et un type d’événement appelé un événement ci-joint.Extensible Application Markup Language (XAML) defines a language component and type of event called an attached event. Le concept d’un événement attaché vous permet d’ajouter un gestionnaire pour un événement particulier à un élément arbitraire plutôt qu’à un élément qui définit réellement l’événement ou qui en hérite.The concept of an attached event enables you to add a handler for a particular event to an arbitrary element rather than to an element that actually defines or inherits the event. Dans ce cas, ni l’objet qui déclenche potentiellement l’événement, ni l’instance de gestion de destination ne définit ou ne « détient » l’événement.In this case, neither the object potentially raising the event nor the destination handling instance defines or otherwise "owns" the event.

Conditions préalables requisesPrerequisites

Cette rubrique suppose que vous avez lu Vue d’ensemble des événements routés et Vue d’ensemble du langage XAML (WPF).This topic assumes that you have read Routed Events Overview and XAML Overview (WPF).

Syntaxe d’un événement attachéAttached Event Syntax

Les événements ci-joints ont une syntaxe XAML et un modèle de codage qui doit être utilisé par le code de sauvegarde afin de soutenir l’utilisation de l’événement ci-joint.Attached events have a XAML syntax and a coding pattern that must be used by the backing code in order to support the attached event usage.

Dans la syntaxe XAML, l’événement ci-joint est spécifié non seulement par son nom d’événement, mais par son propre type plus le nom de l’événement, séparé par un point (.).In XAML syntax, the attached event is specified not just by its event name, but by its owning type plus the event name, separated by a dot (.). Comme le nom de l’évènement est qualifié avec le nom de son type propriétaire, la syntaxe de l’événement attaché permet à celui-ci d’être attaché à tout élément pouvant être instancié.Because the event name is qualified with the name of its owning type, the attached event syntax allows any attached event to be attached to any element that can be instantiated.

Par exemple, ce qui suit est la syntaxe XAML pour attacher un gestionnaire pour un événement sur mesure NeedsCleaning ci-joint:For example, the following is the XAML syntax for attaching a handler for a custom NeedsCleaning attached event:

<aqua:Aquarium Name="theAquarium" Height="600" Width="800" aqua:AquariumFilter.NeedsCleaning="WashMe"/>

Notez le préfixe aqua:. Ce préfixe est nécessaire dans le cas présent, car l’événement attaché est un événement personnalisé qui provient d’un fichier xmlns mappé personnalisé.Note the aqua: prefix; the prefix is necessary in this case because the attached event is a custom event that comes from a custom mapped xmlns.

Comment WPF implémente des événements attachésHow WPF Implements Attached Events

Dans WPF, les événements RoutedEvent attachés sont soutenus par un champ et sont acheminés à travers l’arbre après qu’ils sont soulevés.In WPF, attached events are backed by a RoutedEvent field and are routed through the tree after they are raised. En général, la source de l’événement attaché (l’objet qui déclenche l’événement) est une source système ou de service. L’objet qui exécute le code qui déclenche l’événement ne fait donc pas directement partie de l’arborescence d’éléments.Typically, the source of the attached event (the object that raises the event) is a system or service source, and the object that runs the code that raises the event is therefore not a direct part of the element tree.

Scénarios pour les événements attachésScenarios for Attached Events

Dans WPF, des événements ci-joints sont présents dans certains domaines caractéristiques où Mouse il Validation existe une abstraction au niveau du service, comme pour les événements activés par la classe statique ou la classe.In WPF, attached events are present in certain feature areas where there is service-level abstraction, such as for the events enabled by the static Mouse class or the Validation class. Les classes qui interagissent avec le service, ou qui l’utilisent, peuvent employer l’événement dans la syntaxe de l’événement attaché ou choisir de surfacer l’événement attaché en tant qu’événement routé faisant partie de la façon dont la classe intègre les fonctionnalités du service.Classes that interact with or use the service can either use the event in the attached event syntax, or they can choose to surface the attached event as a routed event that is part of how the class integrates the capabilities of the service.

Bien que WPF définisse un certain nombre d’événements ci-joints, les scénarios où vous utiliserez ou gérerez directement l’événement ci-joint sont très limités.Although WPF defines a number of attached events, the scenarios where you will either use or handle the attached event directly are very limited. En général, l’événement ci-joint sert un but d’architecture, mais est ensuite transmis à un événement non-attaché (soutenu par un événement CLR "wrapper") événement acheminé.Generally, the attached event serves an architecture purpose, but is then forwarded to a non-attached (backed with a CLR event "wrapper") routed event.

Par exemple, Mouse.MouseDown l’événement sous-jacent ci-joint UIElement peut MouseDown plus UIElement facilement être géré sur n’importe quel donné en utilisant sur cela plutôt que de traiter avec la syntaxe d’événement ci-joint soit dans XAML ou code.For instance, the underlying attached event Mouse.MouseDown can more easily be handled on any given UIElement by using MouseDown on that UIElement rather than dealing with attached event syntax either in XAML or code. L’événement attaché a une fonction d’architecture, car il permet l’extension future des périphériques d’entrée.The attached event serves a purpose in the architecture because it allows for future expansion of input devices. L’appareil hypothétique n’aurait qu’à soulever Mouse.MouseDown afin de simuler Mouse l’entrée de la souris, et n’aurait pas besoin de dériver de le faire.The hypothetical device would only need to raise Mouse.MouseDown in order to simulate mouse input, and would not need to derive from Mouse to do so. Toutefois, ce scénario implique le traitement du code des événements, et la gestion XAML de l’événement ci-joint n’est pas pertinente à ce scénario.However, this scenario involves code handling of the events, and XAML handling of the attached event is not relevant to this scenario.

Gestion d’un événement attaché dans WPFHandling an Attached Event in WPF

La gestion d’un événement attaché et le code du gestionnaire que vous allez écrire sont essentiellement les mêmes que pour un événement routé.The process for handling an attached event, and the handler code that you will write, is basically the same as for a routed event.

En général, un événement joint WPF n’est pas très différent d’un événement Acheminé WPF.In general, a WPF attached event is not very different from a WPF routed event. Les différences sont la façon dont l’événement est source et comment il est exposé par une classe en tant que membre (qui affecte également la syntaxe de gestionnaire XAML).The differences are how the event is sourced and how it is exposed by a class as a member (which also affects the XAML handler syntax).

Toutefois, comme nous l’avons mentionné précédemment, les événements ci-joints WPF existants ne sont pas particulièrement destinés à la manipulation dans WPF.However, as noted earlier, the existing WPF attached events are not particularly intended for handling in WPF. Le plus souvent, le but de l’événement est de permettre à un élément composé de signaler un état à un élément parent au moment de la composition. Dans ce cas, l’événement est généralement déclenché dans du code et compte également sur une gestion de classe dans la classe parente appropriée.More often, the purpose of the event is to enable a composited element to report a state to a parent element in compositing, in which case the event is usually raised in code and also relies on class handling in the relevant parent class. Par exemple, les Selector éléments dans un Selected sont censés soulever l’événement ci-joint, qui est ensuite de classe gérée par la Selector classe, puis potentiellement converti par la Selector classe en un événement acheminé différent, SelectionChanged.For instance, items within a Selector are expected to raise the attached Selected event, which is then class handled by the Selector class and then potentially converted by the Selector class into a different routed event, SelectionChanged. Pour plus d’informations sur les événements routés et la gestion de classe, consultez Marquage des événements routés comme gérés et gestion de classe.For more information on routed events and class handling, see Marking Routed Events as Handled, and Class Handling.

Définition de vos propres événements attachés en tant qu’événements routésDefining Your Own Attached Events as Routed Events

Si vous êtes dérivé de classes de base WPF communes, vous pouvez mettre en œuvre vos propres événements attachés en incluant certaines méthodes de modèle dans votre classe et en utilisant des méthodes d’utilité qui sont déjà présents sur les classes de base.If you are deriving from common WPF base classes, you can implement your own attached events by including certain pattern methods in your class and by using utility methods that are already present on the base classes.

Le modèle est le suivant :The pattern is as follows:

  • Une méthode AjouterEventNameHandler avec deux paramètres.A method AddEventNameHandler with two parameters. Le premier paramètre est l’instance à laquelle le gestionnaire d’événements est ajouté.The first parameter is the instance to which the event handler is added. Le deuxième paramètre est le gestionnaire d’événements à ajouter.The second parameter is the event handler to add. La méthode public doit staticêtre et , sans valeur de retour.The method must be public and static, with no return value.

  • Une méthode SupprimerEventNameHandler avec deux paramètres.A method RemoveEventNameHandler with two parameters. Le premier paramètre est l’instance à partir de laquelle le gestionnaire d’événements est supprimé.The first parameter is the instance from which the event handler is removed. Le deuxième paramètre est le gestionnaire d’événements à supprimer.The second parameter is the event handler to remove. La méthode public doit staticêtre et , sans valeur de retour.The method must be public and static, with no return value.

La méthode d’accesseur AddEventNameHandler facilite le traitement XAML lorsque les attributs de gestionnaire d’événements ci-joints sont déclarés sur un élément.The AddEventNameHandler accessor method facilitates XAML processing when attached event handler attributes are declared on an element. Les méthodes AddEventNameHandler et SupprimerEventNameHandler permettent également l’accès au code du magasin de gestionnaire d’événements pour l’événement ci-joint.The AddEventNameHandler and RemoveEventNameHandler methods also enable code access to the event handler store for the attached event.

Ce modèle général n’est pas encore assez précis pour une mise en œuvre pratique dans un cadre, car toute mise en œuvre donnée de lecteur XAML pourrait avoir différents schémas pour identifier les événements sous-jacents dans le langage et l’architecture de soutien.This general pattern is not yet precise enough for practical implementation in a framework, because any given XAML reader implementation might have different schemes for identifying underlying events in the supporting language and architecture. C’est l’une des raisons pour lesquelles WPF met en œuvre des événements connexes comme des événements acheminés; l’identifiant à utiliserRoutedEventpour un événement ( ) est déjà défini par le système d’événements WPF.This is one of the reasons that WPF implements attached events as routed events; the identifier to use for an event (RoutedEvent) is already defined by the WPF event system. En outre, l’itinéraire d’un événement est une extension de mise en œuvre naturelle sur le concept de niveau linguistique XAML d’un événement ci-joint.Also, routing an event is a natural implementation extension on the XAML language-level concept of an attached event.

La mise en œuvre addEventName Handler AddHandler pour un événement joint WPF consiste à appeler l’événement acheminé et gestionnaire comme arguments.The AddEventNameHandler implementation for a WPF attached event consists of calling the AddHandler with the routed event and handler as arguments.

Cette stratégie de mise en œuvre et le UIElement système d’événements acheminés en général limitent la gestion des événements attachés aux classes dérivées ou ContentElement aux classes dérivées, parce que seules ces classes ont des AddHandler implémentations.This implementation strategy and the routed event system in general restrict handling for attached events to either UIElement derived classes or ContentElement derived classes, because only those classes have AddHandler implementations.

Par exemple, le code NeedsCleaning suivant définit l’événement ci-joint sur la classe Aquariumpropriétaire, en utilisant la stratégie de l’événement ci-joint WPF de déclarer l’événement ci-joint comme un événement acheminé.For example, the following code defines the NeedsCleaning attached event on the owner class Aquarium, using the WPF attached event strategy of declaring the attached event as a routed event.

public static readonly RoutedEvent NeedsCleaningEvent = EventManager.RegisterRoutedEvent("NeedsCleaning", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(AquariumFilter));
public static void AddNeedsCleaningHandler(DependencyObject d, RoutedEventHandler handler)
{
    UIElement uie = d as UIElement;
    if (uie != null)
    {
        uie.AddHandler(AquariumFilter.NeedsCleaningEvent, handler);
    }
}
public static void RemoveNeedsCleaningHandler(DependencyObject d, RoutedEventHandler handler)
{
    UIElement uie = d as UIElement;
    if (uie != null)
    {
        uie.RemoveHandler(AquariumFilter.NeedsCleaningEvent, handler);
    }
}
Public Shared ReadOnly NeedsCleaningEvent As RoutedEvent = EventManager.RegisterRoutedEvent("NeedsCleaning", RoutingStrategy.Bubble, GetType(RoutedEventHandler), GetType(AquariumFilter))
Public Shared Sub AddNeedsCleaningHandler(ByVal d As DependencyObject, ByVal handler As RoutedEventHandler)
    Dim uie As UIElement = TryCast(d, UIElement)
    If uie IsNot Nothing Then
        uie.AddHandler(AquariumFilter.NeedsCleaningEvent, handler)
    End If
End Sub
Public Shared Sub RemoveNeedsCleaningHandler(ByVal d As DependencyObject, ByVal handler As RoutedEventHandler)
    Dim uie As UIElement = TryCast(d, UIElement)
    If uie IsNot Nothing Then
        uie.RemoveHandler(AquariumFilter.NeedsCleaningEvent, handler)
    End If
End Sub

Notez que la méthode utilisée pour RegisterRoutedEventétablir le champ d’identification d’événement ci-joint, , est en fait la même méthode qui est utilisée pour enregistrer un événement acheminé non-attaché.Note that the method used to establish the attached event identifier field, RegisterRoutedEvent, is actually the same method that is used to register a non-attached routed event. Les événements attachés et les événements routés sont tous inscrits dans un magasin interne centralisé.Attached events and routed events all are registered to a centralized internal store. Cette implémentation du magasin d’événements rend possible la considération conceptuelle des « événements en tant qu’interface » traitée dans Vue d’ensemble des événements routés.This event store implementation enables the "events as an interface" conceptual consideration that is discussed in Routed Events Overview.

Déclenchement d’un événement attaché WPFRaising a WPF Attached Event

Vous n’avez généralement pas besoin de soulever les événements ci-joints définis par le WPF existants à partir de votre code.You do not typically need to raise existing WPF-defined attached events from your code. Ces événements suivent le modèle conceptuel général de InputManager « service », et les classes de service telles que sont responsables de soulever les événements.These events follow the general "service" conceptual model, and service classes such as InputManager are responsible for raising the events.

Toutefois, si vous définissez un événement personnalisé ci-joint basé RoutedEventsur le RaiseEvent modèle WPF de UIElement baser les événements ci-joints sur , vous pouvez utiliser pour soulever un événement attaché de n’importe quel ou ContentElement.However, if you are defining a custom attached event based on the WPF model of basing attached events on RoutedEvent, you can use RaiseEvent to raise an attached event from any UIElement or ContentElement. L’élévation d’un événement acheminé (attaché ou non) exige que vous déclarez un élément particulier dans l’arbre d’élément comme source d’événement ; cette source est RaiseEvent signalée comme l’appelant.Raising a routed event (attached or not) requires that you declare a particular element in the element tree as the event source; that source is reported as the RaiseEvent caller. Votre service est chargé de déterminer quel est l’élément signalé en tant que source dans l’arborescenceDetermining which element is reported as the source in the tree is your service's responsibility

Voir aussiSee also