Cenni preliminari sugli eventi associatiAttached Events Overview

Extensible Application Markup Language (XAML)Extensible Application Markup Language (XAML) definisce un componente del linguaggio e un tipo di evento noto come evento associato. defines a language component and type of event called an attached event. Il concetto di evento associato consente di aggiungere un gestore per un determinato evento a un elemento arbitrario, anziché a un elemento che definisce o eredita effettivamente l'evento.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. In questo caso, né l'oggetto che genera potenzialmente l'evento, né l'istanza di gestione di destinazione definisce o possiede in altro modo l'evento.In this case, neither the object potentially raising the event nor the destination handling instance defines or otherwise "owns" the event.

PrerequisitiPrerequisites

Questo argomento si presuppone di aver letto Cenni preliminari sugli eventi indirizzati e Cenni preliminari su XAML (WPF).This topic assumes that you have read Routed Events Overview and XAML Overview (WPF).

Sintassi per gli eventi associatiAttached Event Syntax

Per supportare l'uso degli eventi associati, è necessario che il codice sottostante usi una sintassi XAMLXAML e un modello di codifica specifici di tali eventi.Attached events have a XAMLXAML syntax and a coding pattern that must be used by the backing code in order to support the attached event usage.

Nella sintassi XAMLXAML, l'evento associato non viene specificato solo tramite il nome dell'evento, ma con il tipo proprietario e il nome dell'evento, separati da un punto (.).In XAMLXAML 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 (.). Dato che il nome di evento è qualificato con il nome del tipo proprietario, la sintassi dell'evento associato consente l'associazione di tale evento a qualsiasi elemento di cui è possibile creare un'istanza.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.

Ad esempio, di seguito viene illustrata la sintassi XAMLXAML per collegare un gestore per un evento associato NeedsCleaning:For example, the following is the XAMLXAML syntax for attaching a handler for a custom NeedsCleaning attached event:

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

Si noti il prefisso aqua:, necessario in questo caso perché l'evento associato è un evento personalizzato tratto da un xmlns mappato personalizzato.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.

Modalità di implementazione degli eventi associati in WPFHow WPF Implements Attached Events

In WPFWPF, collegati sono supportati gli eventi da un RoutedEvent campo e vengono indirizzate attraverso la struttura ad albero dopo essere stati generati.In WPFWPF, attached events are backed by a RoutedEvent field and are routed through the tree after they are raised. In genere, l'origine dell'evento associato (oggetto che genera l'evento) è un'origine di sistema o servizio e l'oggetto che esegue il codice che genera l'evento non è pertanto parte diretta dell'albero degli elementi.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.

Scenari per gli eventi associatiScenarios for Attached Events

In WPFWPF, collegati gli eventi sono presenti in alcune aree di funzionalità in cui è presente astrazione del livello di servizio, ad esempio per gli eventi abilitati per il metodo statico Mouse classe o Validation classe.In WPFWPF, 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. Le classi che interagiscono con il servizio o lo usano possono usano l'evento nella sintassi dell'evento associato o scegliere di usarlo come un evento indirizzato che fa parte del modo in cui la classe integra le funzionalità del servizio.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.

Anche se in WPFWPF vengono definiti vari eventi associati, gli scenari in cui si usa o si gestisce direttamente l'evento associato sono molto limitati.Although WPFWPF defines a number of attached events, the scenarios where you will either use or handle the attached event directly are very limited. Generalmente, l'evento associato assolve uno scopo nell'architettura, ma viene inoltrato a un evento indirizzato non associato, supportato da un "wrapper" di eventi CLRCLR.Generally, the attached event serves an architecture purpose, but is then forwarded to a non-attached (backed with a CLRCLR event "wrapper") routed event.

Ad esempio, l'evento associato sottostante Mouse.MouseDown può più essere gestito facilmente in un dato UIElement utilizzando MouseDown su quel UIElement anziché utilizzare la sintassi dell'evento sia in XAMLXAML o codice.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 XAMLXAML or code. L'evento associato assolve a uno scopo nell'architettura perché consente l'espansione futura dei dispositivi di input.The attached event serves a purpose in the architecture because it allows for future expansion of input devices. Il dispositivo ipotetico solo necessario generare Mouse.MouseDown per simulare l'input del mouse e non è necessario derivare da Mouse a tale scopo.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. Questo scenario comporta tuttavia la gestione di codice degli eventi e la gestione di XAMLXAML dell'evento associato non è attinente a questo scenario.However, this scenario involves code handling of the events, and XAMLXAML handling of the attached event is not relevant to this scenario.

Gestione di un evento associato in WPFHandling an Attached Event in WPF

Il processo di gestione di un evento associato e il codice del gestore che verrà scritto è fondamentalmente lo stesso necessario per un evento indirizzato.The process for handling an attached event, and the handler code that you will write, is basically the same as for a routed event.

In genere, un evento associato WPFWPF non è molto diverso da un evento indirizzato WPFWPF.In general, a WPFWPF attached event is not very different from a WPFWPF routed event. Le differenze sono date dalla modalità di origine dell'evento e della relativa esposizione da parte di una classe come membro, operazione che ha anche effetto sulla sintassi del gestore XAMLXAML.The differences are how the event is sourced and how it is exposed by a class as a member (which also affects the XAMLXAML handler syntax).

Tuttavia, come indicato in precedenza, gli eventi associati WPFWPF esistenti non sono destinati in modo particolare alla gestione in WPFWPF.However, as noted earlier, the existing WPFWPF attached events are not particularly intended for handling in WPFWPF. Più spesso, lo scopo dell'evento è quello di consentire la segnalazione di uno stato da parte di un elemento composto a un elemento padre nella composizione, nel qual caso l'evento viene in genere generato nel codice e si basa inoltre sulla gestione della classe nella classe padre rilevante.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. Ad esempio, gli elementi all'interno di un Selector dovrà generare collegato Selected evento, che viene quindi gestito dal Selector classe e potenzialmente convertito dal Selector classe in un evento indirizzato diverso, 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. Per altre informazioni sugli eventi indirizzati e sulla gestione delle classi, vedere Contrassegno degli eventi indirizzati come gestiti e gestione delle classi.For more information on routed events and class handling, see Marking Routed Events as Handled, and Class Handling.

Definizione di eventi associati personalizzati come eventi indirizzatiDefining Your Own Attached Events as Routed Events

Se si deriva da classi di base WPFWPF comuni, è possibile implementare eventi associati personalizzati mediante l'inclusione di alcuni metodi del modello nella classe e l'uso di metodi di utilità già presenti nelle classi di base.If you are deriving from common WPFWPF 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.

Il modello è il seguente:The pattern is as follows:

  • Un metodo Add*Handler con due parametri.A method Add*Handler with two parameters. Il primo parametro deve identificare l'evento, il quale deve corrispondere ai nomi con il segno * nel nome del metodo.The first parameter must identify the event, and the identified event must match names with the * in the method name. Il secondo parametro è il gestore da aggiungere.The second parameter is the handler to add. Il metodo deve essere pubblico e statico, senza valore restituito.The method must be public and static, with no return value.

  • Un metodo Remove*Handler con due parametri.A method Remove*Handler with two parameters. Il primo parametro deve identificare l'evento, il quale deve corrispondere ai nomi con il segno * nel nome del metodo.The first parameter must identify the event, and the identified event must match names with the * in the method name. Il secondo parametro è il gestore da rimuovere.The second parameter is the handler to remove. Il metodo deve essere pubblico e statico, senza valore restituito.The method must be public and static, with no return value.

Il metodo della funzione di accesso Add*Handler facilita l'elaborazione XAMLXAML quando su un elemento vengono dichiarati attributi del gestore dell'evento associato.The Add*Handler accessor method facilitates the XAMLXAML processing when attached event handler attributes are declared on an element. I metodi Add*Handler e Remove*Handler abilitano inoltre l'accesso del codice all'archivio del gestore eventi per l'evento associato.The Add*Handler and Remove*Handler methods also enable code access to the event handler store for the attached event.

Questo modello generale non è ancora sufficientemente preciso per l'implementazione pratica in un framework, perché qualsiasi implementazione del lettore XAMLXAML specificata può avere schemi diversi per l'identificazione di eventi sottostanti nel linguaggio e nell'architettura di supporto.This general pattern is not yet precise enough for practical implementation in a framework, because any given XAMLXAML reader implementation might have different schemes for identifying underlying events in the supporting language and architecture. Si tratta di uno dei motivi che WPFWPF implementa collegato eventi come eventi indirizzati; l'identificatore da utilizzare per un evento (RoutedEvent) è già definito per il WPFWPF sistema di eventi.This is one of the reasons that WPFWPF implements attached events as routed events; the identifier to use for an event (RoutedEvent) is already defined by the WPFWPF event system. Il routing di un evento, inoltre, è una naturale estensione dell'implementazione nel concetto di evento associato al livello di linguaggio XAMLXAML.Also, routing an event is a natural implementation extension on the XAMLXAML language-level concept of an attached event.

Il Add*Handler implementazione per un WPFWPF evento costituito dalla chiamata di AddHandler con l'evento indirizzato e il gestore come argomenti.The Add*Handler implementation for a WPFWPF attached event consists of calling the AddHandler with the routed event and handler as arguments.

Questa strategia di implementazione e il sistema dell'evento indirizzato in genere limitano la gestione degli eventi associati a uno UIElement classi derivate o ContentElement classi derivate, poiché solo tali classi dispongono AddHandler implementazioni.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.

Ad esempio, il codice seguente definisce l'evento associato NeedsCleaning per la classe del proprietario Aquarium, usando la strategia WPFWPF di dichiarazione dell'evento associato come evento indirizzato.For example, the following code defines the NeedsCleaning attached event on the owner class Aquarium, using the WPFWPF 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

Si noti che il metodo utilizzato per definire il campo Identificatore dell'evento associato, RegisterRoutedEvent, in realtà lo stesso metodo utilizzato per registrare un evento indirizzato non associato.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. Gli eventi associati e gli eventi indirizzati vengono tutti registrati in un archivio interno centralizzato.Attached events and routed events all are registered to a centralized internal store. Questa implementazione dell'archivio degli eventi consente la considerazione del concetto di "eventi come interfaccia" presentata in Cenni preliminari sugli eventi indirizzati.This event store implementation enables the "events as an interface" conceptual consideration that is discussed in Routed Events Overview.

Generazione di un evento associato WPFRaising a WPF Attached Event

Non è in genere necessario generare dal codice eventi associati esistenti definiti in WPFWPF.You do not typically need to raise existing WPFWPF defined attached events from your code. Seguire il modello concettuale di "servizio" generale, questi eventi e le classi del servizio, ad esempio InputManager sono responsabili della generazione degli eventi.These events follow the general "service" conceptual model, and service classes such as InputManager are responsible for raising the events.

Tuttavia, se si definisce un evento personalizzato in base il WPFWPF modello di basare gli eventi associati nel RoutedEvent, è possibile utilizzare RaiseEvent per generare un evento associato da qualsiasi UIElement o ContentElement.However, if you are defining a custom attached event based on the WPFWPF model of basing attached events on RoutedEvent, you can use RaiseEvent to raise an attached event from any UIElement or ContentElement. Generare un evento indirizzato (associato o meno) richiede la dichiarazione di un particolare elemento nell'albero degli elementi come origine evento. tale origine viene segnalata come il RaiseEvent chiamante.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. È responsabilità del servizio determinare quale elemento viene riportato come origine nell'albero.Determining which element is reported as the source in the tree is your service's responsibility

Vedere ancheSee Also

Cenni preliminari sugli eventi indirizzatiRouted Events Overview
Descrizione dettagliata della sintassi XAMLXAML Syntax In Detail
Classi XAML e personalizzate per WPFXAML and Custom Classes for WPF