Visão geral de eventos e eventos roteadosEvents and routed events overview

APIs importantesImportant APIs

Descrevemos o conceito de programação de eventos em um aplicativo Windows Runtime, ao C#usar, Visual Basic ou C++ as extensões deC++componente Visual (/CX) como sua linguagem de programação e XAML para sua definição de interface do usuário.We describe the programming concept of events in a Windows Runtime app, when using C#, Visual Basic or Visual C++ component extensions (C++/CX) as your programming language, and XAML for your UI definition. Você pode atribuir manipuladores de eventos como parte das declarações para elementos da interface do usuário em XAML ou pode adicionar manipuladores no código.You can assign handlers for events as part of the declarations for UI elements in XAML, or you can add the handlers in code. O Windows Runtime dá suporte a eventos roteados: determinados eventos de entrada e eventos de dados podem ser manipulados por outros objetos além do objeto que acionou o evento.Windows Runtime supports routed events: certain input events and data events can be handled by objects beyond the object that fired the event. Eventos roteados são úteis quando você define modelos de controle ou usa páginas ou contêineres de layout.Routed events are useful when you define control templates, or use pages or layout containers.

Eventos como um conceito de programaçãoEvents as a programming concept

De um modo geral, os conceitos de eventos na programação de um aplicativo do Windows Runtime são semelhantes ao modelo de evento nas linguagens de programação mais usadas.Generally speaking, event concepts when programming a Windows Runtime app are similar to the event model in most popular programming languages. Se você sabe como trabalhar com eventos do Microsoft .NET ou C++, já começa em vantagem.If you know how to work with Microsoft .NET or C++ events already, you have a head start. Você não precisa saber muito sobre os conceitos de modelo de evento para executar algumas tarefas básicas – como, por exemplo, anexar manipuladores.But you don't need to know that much about event model concepts to perform some basic tasks, such as attaching handlers.

Quando você usa C#, Visual Basic ou C++/CX como linguagem de programação, a interface do usuário é definida na marcação (XAML).When you use C#, Visual Basic or C++/CX as your programming language, the UI is defined in markup (XAML). Na sintaxe de marcação XAML, alguns dos princípios de conexão de eventos entre elementos de marcação e entidades de código em runtime são similares a outras tecnologias da Web, tais como ASP.NET ou HTML5.In XAML markup syntax, some of the principles of connecting events between markup elements and runtime code entities are similar to other Web technologies, such as ASP.NET, or HTML5.

Observe   The código que fornece a lógica de tempo de execução para uma interface do usuário definida pelo XAML geralmente é conhecido como code-behind ou o arquivo code-behind.Note  The code that provides the runtime logic for a XAML-defined UI is often referred to as code-behind or the code-behind file. Nas visualizações de soluções do Microsoft Visual Studio, essa relação é mostrada graficamente, com o arquivo code-behind sendo um arquivo dependente e aninhado em contraposição à página XAML à qual ele se refere.In the Microsoft Visual Studio solution views, this relationship is shown graphically, with the code-behind file being a dependent and nested file versus the XAML page it refers to.

Button.Click: uma introdução a eventos e XAMLButton.Click: an introduction to events and XAML

Uma das tarefas de programação mais comuns para um aplicativo do Windows Runtime é a captura de entrada do usuário na interface do usuário.One of the most common programming tasks for a Windows Runtime app is to capture user input to the UI. Por exemplo, a sua interface do usuário pode ter um botão em que o usuário deve clicar para enviar informações ou mudar o estado.For example, your UI might have a button that the user must click to submit info or to change state.

Você define a interface do usuário para o seu aplicativo do Windows Runtime gerando a XAML.You define the UI for your Windows Runtime app by generating XAML. Esse XAML é geralmente o resultado de uma superfície de design no Visual Studio.This XAML is usually the output from a design surface in Visual Studio. A XAML também pode ser escrita em um editor de texto sem formatação ou em um editor XAML de terceiros.You can also write the XAML in a plain-text editor or a third-party XAML editor. Durante a geração dessa XAML, você pode conectar manipuladores de eventos de elementos individuais da interface do usuário e, ao mesmo tempo, definir todos os demais atributos que estabelecem valores de propriedade desse elemento da interface do usuário.While generating that XAML, you can wire event handlers for individual UI elements at the same time that you define all the other XAML attributes that establish property values of that UI element.

Para conectar os eventos em XAML, você pode especificar o nome em forma de cadeia de caracteres do método do manipulador que já definiu ou vai definir posteriormente no code-behind.To wire the events in XAML, you specify the string-form name of the handler method that you've already defined or will define later in your code-behind. Por exemplo, esta XAML define um objeto Button com outras propriedades (atributo x:Name, Content) atribuídas como atributos e transfere um manipulador para o evento Click do botão referenciando um método chamado ShowUpdatesButton_Click:For example, this XAML defines a Button object with other properties (x:Name attribute, Content) assigned as attributes, and wires a handler for the button's Click event by referencing a method named ShowUpdatesButton_Click:

<Button x:Name="showUpdatesButton"
  Content="{Binding ShowUpdatesText}"
  Click="ShowUpdatesButton_Click"/>

Dica  Conexão de eventos é um termo de programação.Tip  Event wiring is a programming term. Refere-se ao processo ou código por meio do qual você indica que as ocorrências de um evento devem chamar um método do manipulador nomeado.It refers to the process or code whereby you indicate that occurrences of an event should invoke a named handler method. Na maioria dos modelos de código de procedimento, a conexão de eventos é um código "AddHandler" implícito ou explícito que nomeia ambos, o evento e o método, e geralmente envolve uma instância de objeto de destino.In most procedural code models, event wiring is implicit or explicit "AddHandler" code that names both the event and method, and usually involves a target object instance. Em XAML, o "AddHandler" é implícito, e a conexão de eventos consiste inteiramente em nomear o evento com o nome do atributo de um elemento de objeto, e nomear o manipulador com o valor desse atributo.In XAML, the "AddHandler" is implicit, and event wiring consists entirely of naming the event as the attribute name of an object element, and naming the handler as that attribute's value.

Você escreve o manipulador real na linguagem de programação que está usando para todo o código do aplicativo e code-behind.You write the actual handler in the programming language that you're using for all your app's code and code-behind. Com o atributo Click="ShowUpdatesButton_Click", você criou um contrato em que, quando a marcação XAML é compilada e analisada, a etapa de compilação de IDE na ação de compilação do ambiente de desenvolvimento e a eventual análise XAML quando as cargas de aplicativo podem encontrar um método chamado ShowUpdatesButton_Click como parte do código do aplicativo.With the attribute Click="ShowUpdatesButton_Click", you have created a contract that when the XAML is markup-compiled and parsed, both the XAML markup compile step in your IDE's build action and the eventual XAML parse when the app loads can find a method named ShowUpdatesButton_Click as part of the app's code. ShowUpdatesButton_Click deve ser um método que implementa uma assinatura de método compatível (com base em um delegado) para qualquer manipulador do evento Click.ShowUpdatesButton_Click must be a method that implements a compatible method signature (based on a delegate) for any handler of the Click event. Por exemplo, este código define o manipulador ShowUpdatesButton_Click.For example, this code defines the ShowUpdatesButton_Click handler.

private void ShowUpdatesButton_Click (object sender, RoutedEventArgs e) 
{
    Button b = sender as Button;
    //more logic to do here...
}
Private Sub ShowUpdatesButton_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
    Dim b As Button = CType(sender, Button)
    '  more logic to do here...
End Sub
void winrt::MyNamespace::implementation::BlankPage::ShowUpdatesButton_Click(Windows::Foundation::IInspectable const& sender, Windows::UI::Xaml::RoutedEventArgs const& e)
{
    auto b{ sender.as<Windows::UI::Xaml::Controls::Button>() };
    // More logic to do here.
}
void MyNamespace::BlankPage::ShowUpdatesButton_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e) 
{
    Button^ b = (Button^) sender;
    //more logic to do here...
}

Neste exemplo, o método ShowUpdatesButton_Click baseia-se no delegado de RoutedEventHandler.In this example, the ShowUpdatesButton_Click method is based on the RoutedEventHandler delegate. Você saberá que este é o delegado a ser usado, pois você verá esse delegado chamado na sintaxe para o método Click .You'd know that this is the delegate to use because you'll see that delegate named in the syntax for the Click method.

A Tip   Visual Studio fornece uma maneira conveniente de nomear o manipulador de eventos e definir o método do manipulador enquanto você edita XAML.Tip  Visual Studio provides a convenient way to name the event handler and define the handler method while you're editing XAML. Ao fornecer o nome de atributo do evento no editor de texto XAML, aguarde um pouco até que uma lista do Microsoft IntelliSense seja exibida.When you provide the attribute name of the event in the XAML text editor, wait a moment until a Microsoft IntelliSense list displays. Se você clicar em <Novo Manipulador de Eventos> na lista, o Microsoft Visual Studio sugerirá um nome de método com base no x:Name do elemento (ou nome do tipo), no nome do evento e em um sufixo numérico.If you click <New Event Handler> from the list, Microsoft Visual Studio will suggest a method name based on the element's x:Name (or type name), the event name, and a numeric suffix. Você poderá então clicar com o botão direito do mouse no nome do manipulador de eventos selecionado e clicar em Navegar até Manipulador de Eventos.You can then right-click the selected event handler name and click Navigate to Event Handler. A navegação irá diretamente para a definição recém-inserida do manipulador de eventos, como visualizada na exibição do arquivo de code-behind para a página XAML.This will navigate directly to the newly inserted event handler definition, as seen in the code editor view of your code-behind file for the XAML page. O manipulador de eventos já tem a assinatura correta, incluindo o parâmetro sender e a classe de dados de evento usada pelo evento.The event handler already has the correct signature, including the sender parameter and the event data class that the event uses. Além disso, se um método de manipulador com a assinatura correta já existir no seu code-behind, o nome desse método aparecerá no menu suspenso de preenchimento automático com a opção <Novo Manipulador de Eventos> .Also, if a handler method with the correct signature already exists in your code-behind, that method's name appears in the auto-complete drop-down along with the <New Event Handler> option. Também é possível pressionar a tecla Tab como um atalho, em vez de clicar nos itens da lista do IntelliSense.You can also press the Tab key as a shortcut instead of clicking the IntelliSense list items.

Definindo um manipulador de eventosDefining an event handler

Para objetos que são elementos da interface do usuário e foram declarados em XAML, o código de manipulador de eventos é definido na classe parcial que opera como o code-behind de uma página XAML.For objects that are UI elements and declared in XAML, event handler code is defined in the partial class that serves as the code-behind for a XAML page. Manipuladores de eventos são métodos que você escreve como parte da classe parcial associada ao XAML.Event handlers are methods that you write as part of the partial class that is associated with your XAML. Esses manipuladores de eventos se baseiam nos delegados utilizados por um determinado evento.These event handlers are based on the delegates that a particular event uses. Os métodos de manipulador de eventos podem ser públicos ou particulares.Your event handler methods can be public or private. O acesso particular funciona porque o manipulador e a instância criada no XAML são finalmente unidos pela geração de código.Private access works because the handler and instance created by the XAML are ultimately joined by code generation. Em geral, recomendamos que você torne particulares os métodos de manipulador de eventos, na classe.In general, we recommend that you make your event handler methods private in the class.

Observe que os manipuladores C++ de   Event para não são definidos em classes parciais, eles são declarados no cabeçalho como um membro de classe particular.Note  Event handlers for C++ don't get defined in partial classes, they are declared in the header as a private class member. As ações de compilação para um projeto em C++ cuidam da geração do código que dá suporte ao sistema de tipos XAML e do modelo code-behind para C++.The build actions for a C++ project take care of generating code that supports the XAML type system and code-behind model for C++.

O parâmetro sender e dados do eventoThe sender parameter and event data

O manipulador que você escreve para o evento pode acessar dois valores que ficam disponíveis como entrada para cada caso em que o seu manipulador é invocado.The handler you write for the event can access two values that are available as input for each case where your handler is invoked. O primeiro desses valores é sender, que é uma referência ao objeto ao qual o manipulador está conectado.The first such value is sender, which is a reference to the object where the handler is attached. O parâmetro sender é digitado como o tipo Object de base.The sender parameter is typed as the base Object type. Uma técnica comum consiste em converter sender em um tipo mais preciso.A common technique is to cast sender to a more precise type. Essa técnica é útil se você pretende verificar ou alterar o estado no próprio objeto sender.This technique is useful if you expect to check or change state on the sender object itself. Com base no design do seu aplicativo, você geralmente espera um tipo que seja seguro para converter sender, baseado no local onde o manipulador foi anexado ou em outras especificidades do design.Based on your own app design, you usually know a type that is safe to cast sender to, based on where the handler is attached or other design specifics.

O segundo valor são dados de evento. Esse valor geralmente aparece em definições de sintaxe como o parâmetro e.The second value is event data, which generally appears in syntax definitions as the e parameter. Você pode descobrir quais propriedades estão disponíveis para os dados do evento verificando o parâmetro e do delegado atribuído ao evento específico que você está manipulando e usando o IntelliSense ou o Pesquisador de Objetos no Visual Studio.You can discover which properties for event data are available by looking at the e parameter of the delegate that is assigned for the specific event you are handling, and then using IntelliSense or Object Browser in Visual Studio. Se preferir, use a documentação de referência do Windows Runtime.Or you can use the Windows Runtime reference documentation.

Para alguns eventos, os valores de propriedade específicos dos dados de evento são tão importantes quanto saber que o evento ocorreu.For some events, the event data's specific property values are as important as knowing that the event occurred. Isso é especialmente verdadeiro para os eventos de entrada.This is especially true of the input events. Para os eventos de ponteiro, a posição do ponteiro quando ocorreu o evento pode ser importante.For pointer events, the position of the pointer when the event occurred might be important. Para eventos de teclado, todas as teclas possíveis acionam um evento KeyDown e um evento KeyUp.For keyboard events, all possible key presses fire a KeyDown and KeyUp event. Para determinar a tecla que foi pressionada pelo usuário, acesse os KeyRoutedEventArgs disponíveis para o manipulador de eventos.To determine which key a user pressed, you must access the KeyRoutedEventArgs that is available to the event handler. Para saber mais sobre como manipular eventos de entrada, consulte Interações de teclado e Identificar entrada do ponteiro.For more info about handling input events, see Keyboard interactions and Handle pointer input. Eventos de entrada e cenários de entrada costumam incluir considerações adicionais e não são abordados neste tópico; por exemplo, captura de ponteiro para eventos de ponteiro e teclas modificadoras e códigos de teclas da plataforma para eventos de teclado.Input events and input scenarios often have additional considerations that are not covered in this topic, such as pointer capture for pointer events, and modifier keys and platform key codes for keyboard events.

Manipuladores de eventos que usam o padrão asyncEvent handlers that use the async pattern

Em alguns casos, você desejará usar APIs que usam um padrão async em um manipulador de eventos.In some cases you'll want to use APIs that use an async pattern within an event handler. Por exemplo, talvez você use Button em AppBar para exibir um seletor de arquivos e interagir com ele.For example, you might use a Button in an AppBar to display a file picker and interact with it. No entanto, muitas das APIs de seletor de arquivos são assíncronas.However, many of the file picker APIs are asynchronous. Elas precisam ser chamadas dentro de um escopo async/awaitable, e o compilador fará essa imposição.They have to be called within an async/awaitable scope, and the compiler will enforce this. O que você pode fazer é adicionar a palavra-chave Async ao manipulador de eventos, de modo que o manipulador agora é Async void.So what you can do is add the async keyword to your event handler such that the handler is now async void. Agora, o seu manipulador de eventos pode fazer chamadas async/awaitable.Now your event handler is permitted to make async/awaitable calls.

Para conhecer um exemplo de manipulação de eventos de interação do usuário usando o padrão async, consulte Acesso a arquivos e seletores (parte da série Criar seu primeiro aplicativo do Windows Runtime em C# ou Visual Basic).For an example of user-interaction event handling using the async pattern, see File access and pickers (part of theCreate your first Windows Runtime app using C# or Visual Basic series). Veja também [Chamar APIs assíncronas em C).See also [Call asynchronous APIs in C).

Adicionando manipuladores de eventos em códigoAdding event handlers in code

A XAML não é a única forma de atribui um manipulador de eventos a um objeto.XAML is not the only way to assign an event handler to an object. Para adicionar manipuladores de eventos a qualquer objeto em código, inclusive objetos não utilizáveis em XAML, você pode usar a sintaxe específica a uma linguagem para adicionar manipuladores de eventos.To add event handlers to any given object in code, including to objects that are not usable in XAML, you can use the language-specific syntax for adding event handlers.

Em C#, a sintaxe é usar o operador +=.In C#, the syntax is to use the += operator. Você registra o manipulador fazendo referência ao nome do método manipulador de eventos no lado direito do operador.You register the handler by referencing the event handler method name on the right side of the operator.

Se você está usando código para adicionar manipuladores de eventos a objetos que aparecem na interface do usuário em tempo de execução, uma prática comum é adicionar esses manipuladores em resposta a um evento de ciclo de vida do objeto ou de retorno de chamada – como, por exemplo, Loaded ou OnApplyTemplate, de maneira que os manipuladores de eventos no objeto relevante estejam prontos para eventos iniciados pelo usuário no tempo de execução.If you use code to add event handlers to objects that appear in the run-time UI, a common practice is to add such handlers in response to an object lifetime event or callback, such as Loaded or OnApplyTemplate, so that the event handlers on the relevant object are ready for user-initiated events at run time. Este exemplo mostra uma estrutura de tópicos XAML da estrutura da página e, em seguida, fornece a sintaxe da linguagem C# para adicionar um manipulador de eventos a um objeto.This example shows a XAML outline of the page structure and then provides the C# language syntax for adding an event handler to an object.

<Grid x:Name="LayoutRoot" Loaded="LayoutRoot_Loaded">
  <StackPanel>
    <TextBlock Name="textBlock1">Put the pointer over this text</TextBlock>
...
  </StackPanel>
</Grid>
void LayoutRoot_Loaded(object sender, RoutedEventArgs e)
{
    textBlock1.PointerEntered += textBlock1_PointerEntered;
    textBlock1.PointerExited += textBlock1_PointerExited;
}

Observe   A existe uma sintaxe mais detalhada.Note  A more verbose syntax exists. Em 2005, a linguagem C# adicionou um recurso chamado inferência de delegado, o qual permite que um compilador infira a nova instância do delegado e habilita a sintaxe anterior, mais simples.In 2005, C# added a feature called delegate inference, which enables a compiler to infer the new delegate instance and enables the previous, simpler syntax. A sintaxe detalhada é funcionalmente idêntica ao exemplo anterior, mas cria explicitamente uma nova instância do delegado antes de registrá-la, assim, não tirando proveito da inferência do delegado.The verbose syntax is functionally identical to the previous example, but explicitly creates a new delegate instance before registering it, thus not taking advantage of delegate inference. Essa sintaxe explícita é menos comum, mas você ainda pode vê-la em alguns exemplos de código.This explicit syntax is less common, but you might still see it in some code examples.

void LayoutRoot_Loaded(object sender, RoutedEventArgs e)
{
    textBlock1.PointerEntered += new PointerEventHandler(textBlock1_PointerEntered);
    textBlock1.PointerExited += new MouseEventHandler(textBlock1_PointerExited);
}

Há duas possibilidades para sintaxe do Visual Basic.There are two possibilities for Visual Basic syntax. Uma é paralela à sintaxe de C# e anexa manipuladores diretamente a instâncias.One is to parallel the C# syntax and attach handlers directly to instances. Isso exige a palavra-chave AddHandler e também o operador AddressOf que desfaz a referência ao nome do método manipulador.This requires the AddHandler keyword and also the AddressOf operator that dereferences the handler method name.

A outra opção para sintaxe do Visual Basic consiste em usar a palavra-chave Handles em manipuladores de eventos.The other option for Visual Basic syntax is to use the Handles keyword on event handlers. Essa técnica é adequada em casos nos quais espera-se que manipuladores existam em objetos desde o carregamento e persistam ao longo do ciclo de vida do objeto.This technique is appropriate for cases where handlers are expected to exist on objects at load time and persist throughout the object lifetime. O uso de Handles em um objeto definido em XAML requer que você forneça um Name / x:Name.Using Handles on an object that is defined in XAML requires that you provide a Name / x:Name. Esse nome se torna o qualificador de instâncias necessário para a parte Instance.Event da sintaxe Handles.This name becomes the instance qualifier that is needed for the Instance.Event part of the Handles syntax. Nesse caso, você não precisa de um manipulador de eventos baseado no ciclo de vida do objeto; as conexões Handles são criadas quando você compila sua página XAML.In this case you don't need an object lifetime-based event handler to initiate attaching the other event handlers; the Handles connections are created when you compile your XAML page.

Private Sub textBlock1_PointerEntered(ByVal sender As Object, ByVal e As PointerRoutedEventArgs) Handles textBlock1.PointerEntered
' ...
End Sub

Observe   Visual Studio e sua superfície de design XAML geralmente promovem a técnica de manipulação de instância em vez da palavra-chave Handles .Note  Visual Studio and its XAML design surface generally promote the instance-handling technique instead of the Handles keyword. Isso é porque estabelecer as ligações dos manipuladores de eventos em XAML é parte do típico fluxo de trabalho entre designer e desenvolvedor, e a técnica da palavra-chave Handles é incompatível com o estabelecimento de ligações com os manipuladores de eventos em XAML.This is because establishing the event handler wiring in XAML is part of typical designer-developer workflow, and the Handles keyword technique is incompatible with wiring the event handlers in XAML.

Em C++/CX, você também usa a sintaxe += , mas há diferenças no formato básico C# :In C++/CX, you also use the += syntax, but there are differences from the basic C# form:

  • Não há inferência de delegado, portanto, você deve usar ref new para a instância do delegado.No delegate inference exists, so you must use ref new for the delegate instance.
  • O construtor do delegado possui dois parâmetros e requer o objeto de destino como o primeiro parâmetro.The delegate constructor has two parameters, and requires the target object as the first parameter. Tipicamente, você especifica this.Typically you specify this.
  • O construtor delegate requer o endereço do método como o segundo parâmetro, de maneira que o operador de referência & preceda o nome do método.The delegate constructor requires the method address as the second parameter, so the & reference operator precedes the method name.
textBlock1().PointerEntered({this, &MainPage::TextBlock1_PointerEntered });
textBlock1->PointerEntered += 
ref new PointerEventHandler(this, &BlankPage::textBlock1_PointerEntered);

Removendo manipuladores de eventos em códigoRemoving event handlers in code

Normalmente não é necessário remover manipuladores de eventos em código, mesmo se você adicioná-los em código.It's not usually necessary to remove event handlers in code, even if you added them in code. O comportamento de vida útil do objeto para a maioria dos objetos do Windows Runtime como páginas e controles destruirá os objetos quando forem desconectados da Janela principal e de sua árvore visual, e todas as referências a delegados serão destruídas também.The object lifetime behavior for most Windows Runtime objects such as pages and controls will destroy the objects when they are disconnected from the main Window and its visual tree, and any delegate references are destroyed too. O .NET faz isso através de coleta de lixo, e o Windows Runtime com C++/CX usa referências fracas por padrão..NET does this through garbage collection and Windows Runtime with C++/CX uses weak references by default.

Há alguns casos em que você quer remover manipuladores de eventos explicitamente.There are some rare cases where you do want to remove event handlers explicitly. São elas:These include:

  • Manipuladores adicionados para eventos estáticos, que não podem sofrer a coleta de lixo de maneira convencional.Handlers you added for static events, which can't get garbage-collected in a conventional way. Exemplos de eventos estáticos na API do Windows Runtime são os eventos das classes CompositionTarget e Clipboard.Examples of static events in the Windows Runtime API are the events of the CompositionTarget and Clipboard classes.
  • Teste o código quando quiser que o tempo da remoção dos manipuladores seja imediato ou quando quiser trocar antigos/novos manipuladores de eventos para um evento em tempo de execução.Test code where you want the timing of handler removal to be immediate, or code where you what to swap old/new event handlers for an event at run time.
  • A implementação de um acessador remove personalizado.The implementation of a custom remove accessor.
  • Eventos estáticos personalizados.Custom static events.
  • Manipuladores para navegações de página.Handlers for page navigations.

FrameworkElement. Unloaded ou Page. NavigatedFrom são possíveis gatilhos de eventos que têm posições apropriadas no gerenciamento de estado e no tempo de vida do objeto, de modo que você pode usá-los para remover manipuladores de outros eventos.FrameworkElement.Unloaded or Page.NavigatedFrom are possible event triggers that have appropriate positions in state management and object lifetime such that you can use them for removing handlers for other events.

Por exemplo, você pode remover um manipulador de eventos chamado textBlock1 _PointerEntered do objeto de destino textBlock1 usando este código.For example, you can remove an event handler named textBlock1_PointerEntered from the target object textBlock1 using this code.

textBlock1.PointerEntered -= textBlock1_PointerEntered;
RemoveHandler textBlock1.PointerEntered, AddressOf textBlock1_PointerEntered

Você também pode remover manipuladores para os casos em que o evento foi adicionado através de um atributo XAML, o que significa que o manipulador foi adicionado em código gerado.You can also remove handlers for cases where the event was added through a XAML attribute, which means that the handler was added in generated code. Isso é mais fácil de fazer se você fornecer um valor Name para o elemento em que o manipulador foi anexado, porque isso proporciona uma referência de objeto para o código posteriormente; entretanto, você também pode percorrer a árvore do objeto para encontrar a referência de objeto necessária em casos em que o objeto não tem Name.This is easier to do if you provided a Name value for the element where the handler was attached, because that provides an object reference for code later; however, you could also walk the object tree in order to find the necessary object reference in cases where the object has no Name.

Se você precisar remover um manipulador de eventos em C++/CX, precisará de um token de registro, que deveria ter recebido do valor de retorno do registro de manipulador de eventos +=.If you need to remove an event handler in C++/CX, you'll need a registration token, which you should've received from the return value of the += event handler registration. Isso ocorre porque o valor usado para o lado direito do cancelamento de registro de -= na sintaxe C++/CX é o token, e não o nome do método.That's because the value you use for the right side of the -= deregistration in the C++/CX syntax is the token, not the method name. Para C++/CX, você não pode remover os manipuladores que foram adicionados como um atributo XAML porque o código gerado C++/CX não salva um token.For C++/CX, you can't remove handlers that were added as a XAML attribute because the C++/CX generated code doesn't save a token.

Eventos roteadosRouted events

O Windows Runtime com C#, Microsoft Visual Basic ou C++/CX aceita o conceito de um evento roteado para um conjunto de eventos presentes na maioria dos elementos da interface do usuário.The Windows Runtime with C#, Microsoft Visual Basic or C++/CX supports the concept of a routed event for a set of events that are present on most UI elements. Esses eventos são para cenários de entrada e interação do usuário e são implementados na classe base UIElement.These events are for input and user interaction scenarios, and they are implemented on the UIElement base class. Veja a seguir uma lista de eventos de entrada que são eventos roteados:Here's a list of input events that are routed events:

Um evento roteado é um evento que é potencialmente passado adiante (roteado) de um objeto filho para cada um dos seus sucessivos objetos pais em uma árvore de objetos.A routed event is an event that is potentially passed on (routed) from a child object to each of its successive parent objects in an object tree. A estrutura XAML da interface do usuário se aproxima dessa árvore, sendo que a raiz da árvore é o elemento raiz do XAML.The XAML structure of your UI approximates this tree, with the root of that tree being the root element in XAML. A verdadeira árvore de objetos pode variar um pouco do aninhamento de elementos XAML porque a árvore de objetos não inclui recursos da linguagem XAML – como marcas de elementos de propriedades.The true object tree might vary somewhat from the XAML element nesting, because the object tree doesn't include XAML language features such as property element tags. Você pode conceber o evento roteado como decorrente de qualquer elemento filho de elemento de objeto XAML que aciona o evento em direção ao elemento de objeto pai que o contém.You can conceive of the routed event as bubbling from any XAML object element child element that fires the event, toward the parent object element that contains it. O evento e seus dados podem ser manipulados em vários objetos ao longo da rota de evento.The event and its event data can be handled on multiple objects along the event route. Se nenhum elemento tiver manipuladores, a rota se mantém potencialmente em movimento até que o elemento raiz seja alcançado.If no element has handlers, the route potentially keeps going until the root element is reached.

Se conhecer tecnologias da Web, como DHTML (HTML Dinâmico) ou HTML5, talvez você já esteja familiarizado com o conceito de evento propagação.If you know Web technologies such as Dynamic HTML (DHTML) or HTML5, you might already be familiar with the bubbling event concept.

Quando um evento roteado se propaga pela rota de evento, todos os manipuladores de eventos anexados acessam uma instância compartilhada de dados de evento.When a routed event bubbles through its event route, any attached event handlers all access a shared instance of event data. Portanto, se houver dados de evento que possam ser gravados por um manipulador, todas as alterações feitas nos dados de evento serão passadas para o próximo manipulador e poderão não representar mais os dados de evento originais do evento.Therefore, if any of the event data is writeable by a handler, any changes made to event data will be passed on to the next handler, and may no longer represent the original event data from the event. Quando um evento apresenta um comportamento de evento roteado, a documentação de referência inclui comentários e outras anotações sobre o comportamento roteado.When an event has a routed event behavior, the reference documentation will include remarks or other notations about the routed behavior.

A propriedade OriginalSource de RoutedEventArgsThe OriginalSource property of RoutedEventArgs

Quando um evento se propaga uma rota de eventos acima, sender não é mais o mesmo objeto que ergueu o evento.When an event bubbles up an event route, sender is no longer the same object as the event-raising object. Em vez disso, sender é o objeto no qual o manipulador que está sendo invocado está conectado.Instead, sender is the object where the handler that is being invoked is attached.

Em alguns casos, sender não é o objeto de interesse e, em vez disso, você está interessado em informações como, por exemplo, em quais dos possíveis objetos filho o ponteiro está focalizado quando um evento de ponteiro é disparado ou qual objeto em uma interface do usuário maior tinha o foco quando um usuário pressionou uma tecla do teclado.In some cases, sender is not interesting, and you are instead interested in info such as which of the possible child objects the pointer is over when a pointer event fired, or which object in a larger UI held focus when a user pressed a keyboard key. Nesses casos, você pode usar o valor da propriedade OriginalSource.For these cases, you can use the value of the OriginalSource property. Em todos os pontos da rota, a OriginalSource relata o objeto original que acionou o evento, e não o local onde o manipulador foi conectado.At all points on the route, OriginalSource reports the original object that fired the event, instead of the object where the handler is attached. Contudo, para eventos de entrada de UIElement, esse objeto original costuma ser um objeto não imediatamente visível na XAML de definição de interface do usuário em nível de página.However, for UIElement input events, that original object is often an object that is not immediately visible in the page-level UI definition XAML. Em vez disso, o objeto original pode ser uma parte modelo de um controle.Instead, that original source object might be a templated part of a control. Por exemplo, se o usuário passa com o ponteiro sobre a borda de um Button, para a maioria dos eventos de ponteiro, OriginalSource é uma parte modelo Border em Template, e não o Button propriamente dito.For example, if the user hovers the pointer over the very edge of a Button, for most pointer events the OriginalSource is a Border template part in the Template, not the Button itself.

A dica   Input a bolha de evento é especialmente útil se você estiver criando um controle modelo.Tip  Input event bubbling is especially useful if you are creating a templated control. Qualquer controle que tenha um modelo pode ter um novo modelo aplicado pelo seu consumidor.Any control that has a template can have a new template applied by its consumer. O consumidor que está tentando recriar um modelo de trabalho pode eliminar inadvertidamente uma parte da manipulação de eventos declarada no modelo padrão.The consumer that's trying to recreate a working template might unintentionally eliminate some event handling declared in the default template. Você ainda pode fornecer manipulação de eventos em nível de controle anexando manipuladores como parte da substituição de OnApplyTemplate na definição de classe.You can still provide control-level event handling by attaching handlers as part of the OnApplyTemplate override in the class definition. Em seguida, pode apanhar os eventos de entrada propagados rumo à raiz do controle na instanciação.Then you can catch the input events that bubble up to the control's root on instantiation.

A propriedade HandledThe Handled property

Várias classes de dados de eventos para eventos roteados específicos contêm uma propriedade chamada Handled.Several event data classes for specific routed events contain a property named Handled. Para ver exemplos, confira PointerRoutedEventArgs.Handled, KeyRoutedEventArgs.Handled e DragEventArgs.Handled.For examples, see PointerRoutedEventArgs.Handled, KeyRoutedEventArgs.Handled, DragEventArgs.Handled. Em todos os casos, Handled é uma propriedade booliana configurável.In all cases Handled is a settable Boolean property.

A definição da propriedade Handled como true influencia o comportamento do sistema de eventos.Setting the Handled property to true influences the event system behavior. Quando Handled é true, o roteamento é interrompido na maioria dos manipuladores de eventos; o evento não prossegue na rota para notificar outros manipuladores anexados sobre esse caso de evento específico.When Handled is true, the routing stops for most event handlers; the event doesn't continue along the route to notify other attached handlers of that particular event case. Cabe a você decidir sobre o significado de "manipulado" no contexto do evento e como o seu aplicativo responde a ele.What "handled" means in the context of the event and how your app responds to it is up to you. Basicamente, Handled é um protocolo simples que permite que o código do aplicativo afirme que uma ocorrência de um evento não precisa se propagar para nenhum contêiner: a lógica do seu aplicativo se encarregou do que precisa ser feito.Basically, Handled is a simple protocol that enables app code to state that an occurrence of an event doesn't need to bubble to any containers, your app logic has taken care of what needs done. Por outro lado, você precisa tomar cuidado para não manipular eventos que provavelmente devem propagados para que comportamentos internos do sistema ou de controle possam agir. Por exemplo, a manipulação de eventos de baixo nível em partes ou itens de um controle de seleção pode ser prejudicial.Conversely though, you do have to be careful that you aren't handling events that probably should bubble so that built-in system or control behaviors can act. For example, handling low-level events within the parts or items of a selection control can be detrimental. O controle de seleção pode estar à procura de eventos de entrada para saber que a seleção deve mudar.The selection control might be looking for input events to know that the selection should change.

Nem todos os eventos roteados podem cancelar um rota dessa maneira, e você pode deduzir isso porque eles não terão uma propriedade Handled.Not all of the routed events can cancel a route in this way, and you can tell that because they won't have a Handled property. Por exemplo, GotFocus e LostFocus são propagados, mas isso sempre acontece em direção à raiz, e suas classes de dados de eventos não têm uma propriedade Handled capaz de influenciar esse comportamento.For example, GotFocus and LostFocus do bubble, but they always bubble all the way to the root, and their event data classes don't have a Handled property that can influence that behavior.

Manipuladores de eventos de entrada em controlesInput event handlers in controls

Às vezes, controles específicos do Windows Runtime usam o conceito Handled internamente para eventos de entrada.Specific Windows Runtime controls sometimes use the Handled concept for input events internally. Isso pode dar a impressão de que um evento de entrada nunca ocorre, pois o código do usuário não pode manipulá-lo.This can make it seem like an input event never occurs, because your user code can't handle it. Por exemplo, a classe Button inclui lógica que manipula deliberadamente o evento de entrada geral PointerPressed.For example, the Button class includes logic that deliberately handles the general input event PointerPressed. Isso ocorre porque botões acionam um evento Click que é iniciado por entrada do ponteiro pressionado, assim como por outros modos de entrada como teclas de manipulação, tais como a tecla Enter, que podem invocar o botão quando são focadas.It does so because buttons fire a Click event that is initiated by pointer-pressed input, as well as by other input modes such as handling keys like the Enter key that can invoke the button when it's focused. Para os objetivos do design de classe Button, o evento de dados brutos é manipulado conceitualmente. Os consumidores da classe, como seu código de usuário, podem, em vez disso, interagir com o evento relevante de controle Click.For purposes of the class design of Button, the raw input event is conceptually handled, and class consumers such as your user code can instead interact with the control-relevant Click event. Tópicos para classes de controle específicas da API do Windows Runtime costumam registrar o comportamento de manipulação de eventos implementado pela classe.Topics for specific control classes in the Windows Runtime API reference often note the event handling behavior that the class implements. Em alguns casos, é possível alterar o comportamento por meio da substituição dos métodos OnEvent.In some cases, you can change the behavior by overriding OnEvent methods. Por exemplo, você pode alterar como a sua classe derivada TextBox reage à entrada de tecla substituindo Control.OnKeyDown.For example, you can change how your TextBox derived class reacts to key input by overriding Control.OnKeyDown.

Registrando manipuladores para eventos roteados já manipuladosRegistering handlers for already-handled routed events

Nós explicamos antes que a definição de Handled como true impede a chamada da maioria dos manipuladores.Earlier we said that setting Handled to true prevents most handlers from being called. Mas o método AddHandler oferece uma técnica para você anexar um manipulador que seja sempre invocado para a rota, mesmo que algum outro manipulador já tenha definido Handled como true nos dados compartilhados do evento.But the AddHandler method provides a technique where you can attach a handler that is always invoked for the route, even if some other handler earlier in the route has set Handled to true in the shared event data. Essa técnica é útil quando você usa um controle que manipulou o evento na sua composição interna ou para a lógica específica do controle,This technique is useful if a control you are using has handled the event in its internal compositing or for control-specific logic. mas você ainda quer responder a ele em uma instância de controle ou na interface do usuário do seu aplicativo.but you still want to respond to it from a control instance, or your app UI. Porém, essa técnica deve ser usada com cuidado, pois pode opor-se ao propósito de Handled e possivelmente violar as interações pretendidas de um controle.But use this technique with caution, because it can contradict the purpose of Handled and possibly break a control's intended interactions.

Apenas os eventos roteados que têm um identificador de evento roteado correspondente podem usar a técnica de manipulação de eventos AddHandler, pois o identificador é uma entrada obrigatória do método AddHandler.Only the routed events that have a corresponding routed event identifier can use the AddHandler event handling technique, because the identifier is a required input of the AddHandler method. Veja a documentação de referência de AddHandler para obter uma lista de eventos que têm identificadores de eventos roteados disponíveis.See the reference documentation for AddHandler for a list of events that have routed event identifiers available. Para a maior parte, essa é a mesma lista dos eventos roteados que mostramos anteriormente.For the most part this is the same list of routed events we showed you earlier. A exceção é que os dois últimos na lista, GotFocus e LostFocus, não têm um identificador de eventos roteados, por isso você não pode usar AddHandler para eles.The exception is that the last two in the list: GotFocus and LostFocus don't have a routed event identifier, so you can't use AddHandler for those.

Eventos roteados fora da árvore de objetosRouted events outside the visual tree

Certos objetos participam de uma relação com a árvore visual primária que é conceitualmente semelhante a possuir uma sobreposição sobre os elementos visuais principais.Certain objects participate in a relationship with the primary visual tree that is conceptually like having an overlay over the main visuals. Esses objetos não são parte das relações entre pai e filho comuns que conectam todos os três elementos à raiz visual.These objects are not part of the usual parent-child relationships that connect all tree elements to the visual root. Esse é o caso para qualquer Popup ou ToolTip exibido.This is the case for any displayed Popup or ToolTip. Se quiser manipular eventos roteados em um Popup ou em uma ToolTip, posicione os manipuladores sobre elementos específicos da interface do usuário que estão no Popup ou na ToolTip, e não nos elementos Popup ou ToolTip.If you want to handle routed events from a Popup or ToolTip, place the handlers on specific UI elements that are within the Popup or ToolTip and not the Popup or ToolTip elements themselves. Não dependa do roteamento dentro de qualquer composição executada para o conteúdo do Popup ou da ToolTip.Don't rely on routing inside any compositing that is performed for Popup or ToolTip content. Isso porque o roteamento de eventos para eventos roteados funciona apenas ao longo da árvore visual principal.This is because event routing for routed events works only along the main visual tree. Um Popup ou uma ToolTip não é considerado um pai de elementos subsidiários da interface do usuário e nunca recebe o evento roteado, mesmo que esteja tentando usar algo como a tela de fundo padrão de Popup como a área de captura de eventos de entrada.A Popup or ToolTip is not considered a parent of subsidiary UI elements and never receives the routed event, even if it is trying to use something like the Popup default background as the capture area for input events.

Teste de clique e eventos de entradaHit testing and input events

Determinar se um elemento está visível para a entrada por mouse, toque e de caneta é chamado de teste de clique.Determining whether and where in UI an element is visible to mouse, touch, and stylus input is called hit testing. Para ações de toque e também para eventos específicos de interação ou de manipulação resultantes de uma ação de toque, é preciso que o elemento esteja visível para teste de clique, para ser a origem do evento e acionar o evento associado à ação.For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. Caso contrário, a ação passa pelo elemento em direção a qualquer elemento subjacente ou aos elementos pai na árvore visual que interage com essa entrada.Otherwise, the action passes through the element to any underlying elements or parent elements in the visual tree that could interact with that input. Há vários fatores que influenciam o teste de clique, mas é possível determinar se um determinado elemento pode acionar eventos de entrada verificando sua propriedade IsHitTestVisible.There are several factors that affect hit testing, but you can determine whether a given element can fire input events by checking its IsHitTestVisible property. Esta propriedade retorna true apenas quando o elemento segue estes critérios:This property returns true only if the element meets these criteria:

  • O valor de propriedade Visibility do elemento é Visible.The element's Visibility property value is Visible.
  • O valor da propriedade Background ou Fill do elemento não é null.The element's Background or Fill property value is not null. Um valor de pincel nulo resulta em transparência e invisibilidade de teste de clique.A null Brush value results in transparency and hit test invisibility. (Para tornar um elemento transparente, mas também visível para teste de clique, use um pincel Transparent em vez de null.)(To make an element transparent but also hit testable, use a Transparent brush instead of null.)

Observação  Background e Fill não são definidos por UIElement e, em vez disso, são definidos por diferentes classes derivadas, como Control e Shape.Note  Background and Fill aren't defined by UIElement, and are instead defined by different derived classes such as Control and Shape. As implicações dos pincéis usados para as propriedades primeiro plano e tela de fundo são as mesmas para teste de clique e eventos de entrada, independentemente da subclasse que implementa as propriedades.But the implications of brushes you use for foreground and background properties are the same for hit testing and input events, no matter which subclass implements the properties.

  • Se o elemento for um controle, o valor da sua propriedade IsEnabled deverá ser true.If the element is a control, its IsEnabled property value must be true.
  • É preciso que o elemento tenha dimensões reais em layout.The element must have actual dimensions in layout. Um elemento em que ActualHeight e ActualWidth são iguais a 0 não acionará eventos.An element where either ActualHeight and ActualWidth are 0 won't fire input events.

Alguns controles têm regras especiais para teste de hit.Some controls have special rules for hit testing. Por exemplo, o TextBlock não tem uma propriedade Background, mas ainda pode executar o teste de clique em toda a região de suas dimensões.For example, TextBlock has no Background property, but is still hit testable within the entire region of its dimensions. Os controles Image e MediaElement são pressionados com o pressionamento de suas dimensões de retângulo definidas, independentemente do conteúdo transparente, como o canal alfa, no arquivo de origem de mídia que está sendo exibido.Image and MediaElement controls are hit testable over their defined rectangle dimensions, regardless of transparent content such as alpha channel in the media source file being displayed. Os controles WebView têm comportamento de teste de clique especial porque a entrada pode ser tratada pelos eventos HTML hospedado e acionar script.WebView controls have special hit testing behavior because the input can be handled by the hosted HTML and fire script events.

A maioria das classes Panel e Border não executa teste de clique na tela de fundo, mas essas classes ainda podem manipular os eventos de entrada do usuário que são roteados dos elementos que os contêm.Most Panel classes and Border are not hit-testable in their own background, but can still handle the user input events that are routed from the elements that they contain.

Você pode determinar quais elementos estão localizados na mesma posição de um evento de entrada do usuário, independentemente de se os elementos são passíveis de teste de hit.You can determine which elements are located at the same position as a user input event, regardless of whether the elements are hit-testable. Para fazer isso, chame o método FindElementsInHostCoordinates.To do this, call the FindElementsInHostCoordinates method. Como o nome sugere, esse método localiza os elementos em um local em relação a um elemento host especificado.As the name implies, this method finds the elements at a location relative to a specified host element. Entretanto, transformações aplicadas e mudanças de layout podem ajustar o sistema de coordenadas relativas de um elemento e, portanto, influenciar quais elementos são encontrados em um determinado local.However, applied transforms and layout changes can adjust the relative coordinate system of an element, and therefore affect which elements are found at a given location.

Execução de comandosCommanding

Um pequeno número de elementos da interface do usuário dão suporte a comandos.A small number of UI elements support commanding. Comandos usam eventos roteados relacionados a entrada na sua implementação subjacente e permite o processamento de entrada relacionada da interface do usuário (uma determinada ação do ponteiro, uma tecla de aceleração específica) invocando um único manipulador de comandos.Commanding uses input-related routed events in its underlying implementation and enables processing of related UI input (a certain pointer action, a specific accelerator key) by invoking a single command handler. Se comandos estiverem disponíveis para um elemento da interface do usuário, considere usar as respectivas APIs de comando em vez de qualquer evento de entrada à parte.If commanding is available for a UI element, consider using its commanding APIs instead of any discrete input events. Em geral, você usa uma referência Binding em propriedades de uma classe que define o modelo de exibição para dados.You typically use a Binding reference into properties of a class that defines the view model for data. As propriedades mantêm comandos nomeados que implementam o padrão de comandos ICommand específico de cada linguagem.The properties hold named commands that implement the language-specific ICommand commanding pattern. Para obter mais informações, consulte ButtonBase.Command.For more info, see ButtonBase.Command.

Eventos personalizados no Windows RuntimeCustom events in the Windows Runtime

Para fins de definir eventos personalizados, o modo de adicionar o evento e o que isso significa para seu design de classe dependem bastante da linguagem de programação sendo usada.For purposes of defining custom events, how you add the event and what that means for your class design is highly dependent on which programming language you are using.

  • Para C# e Visual Basic, você está definindo um evento de CLR.For C# and Visual Basic, you are defining a CLR event. Você pode usar o padrão de evento .NET, desde que não esteja usando acessadores personalizados(add/remove).You can use the standard .NET event pattern, so long as you aren't using custom accessors (add/remove). Outras dicas:Additional tips:
  • Para C++/CX, veja Eventos (C++/CX).For C++/CX, see Events (C++/CX).
    • Use referências nomeadas mesmo para seus próprios usos de eventos personalizados.Use named references even for your own usages of custom events. Não use lambda para eventos personalizados, pois ele pode criar uma referência circular.Don't use lambda for custom events, it can create a circular reference.

Você não pode declarar um evento roteado personalizado para o Windows Runtime; eventos roteados são limitados ao conjunto proveniente do Windows Runtime.You can't declare a custom routed event for Windows Runtime; routed events are limited to the set that comes from the Windows Runtime.

A definição de um evento personalizado normalmente é feita como parte do exercício de definir um controle personalizado.Defining a custom event is usually done as part of the exercise of defining a custom control. É um padrão comum ter uma propriedade de dependência que tem um retorno de chamada de propriedades alteradas, e também definir um evento personalizado que é acionado pelo retorno de chamada de propriedades de dependência em alguns ou todos os casos.It's a common pattern to have a dependency property that has a property-changed callback, and to also define a custom event that's fired by the dependency property callback in some or all cases. Os consumidores do seu controle não têm acesso ao retorno de chamada de propriedades alteradas que você definiu, mas ter um evento de notificação disponível é o próximo passo interessante.Consumers of your control don't have access to the property-changed callback you defined, but having a notification event available is the next best thing. Para saber mais, consulte Propriedades de dependência personalizada.For more info, see Custom dependency properties.