Palavra-chave `event` (C++/CLI e C++/CX)

Artigo
06/16/2023

A palavra-chave event declara um evento, que é uma notificação para assinantes registrados (manipuladores de eventos) de que ocorreu algo de interesse.

Todos os Runtimes

O C++/CX é compatível com a declaração de um membro de evento ou um bloco de eventos. Um membro de evento é uma forma abreviada de declarar um bloco de eventos. Por padrão, um membro de evento declara as funções add, remove e raise que são declaradas explicitamente em um bloco de eventos. Para personalizar as funções em um membro de evento, declare um bloco de eventos e, em seguida, substitua as funções necessárias.

Sintaxe

// event data member
modifier event delegate^ event_name;

// event block
modifier event delegate^ event_name
{
   modifier return_value add(delegate^ name);
   modifier void remove(delegate^ name);
   modifier void raise(parameters);
}

Parâmetros

modifier
Um modificador que pode ser usado na declaração de evento ou em um método de acessador de evento. Os valores possíveis são static e virtual.

delegate
O delegate, cuja assinatura o manipulador de eventos deve corresponder.

event_name
O nome do evento.

return_value
O valor retornado do método do acessador de eventos. Para que possa ser verificado, o tipo de retorno deve ser void.

parameters
(opcional) Parâmetros para o método raise, que correspondem à assinatura do parâmetro delegate.

Comentários

Um evento é uma associação entre um delegado e um manipulador de eventos. Um manipulador de eventos é uma função membro que responde quando o evento é disparado. Ele permite que clientes de qualquer classe registrem métodos que correspondem à assinatura e ao tipo de retorno do delegado.

Há dois tipos de declarações de eventos:

membro de dados de evento
O compilador cria automaticamente o armazenamento para o evento na forma de um membro do tipo delegado e cria funções de membro add, remove e raise internas. Um membro de dados de evento deve ser declarado dentro de uma classe. O tipo de retorno do delegado deve corresponder ao tipo de retorno do manipulador de eventos.

bloco de eventos
Um bloco de eventos permite declarar e personalizar explicitamente o comportamento dos métodos add, remove e raise.

Você pode usar operator += e operator -= para adicionar e remover um manipulador de eventos ou chamar os métodos add e removeexplicitamente.

event é uma palavra-chave contextual. Saiba mais em Palavras-chave contextuais.

Windows Runtime

Comentários

Saiba mais em Eventos (C++/CX).

Para adicionar e, posteriormente, remover um manipulador de eventos, salve a estrutura EventRegistrationToken retornada pela operação add. Em seguida, na operação remove, use a estrutura EventRegistrationToken salva para identificar o manipulador de eventos a ser removido.

Requisitos

Opção do compilador: /ZW

Common Language Runtime

A palavra-chave event possibilita declarar um evento. Um evento é uma maneira de uma classe fornecer notificações quando algo de interesse acontece.

Sintaxe

// event data member
modifier event delegate^ event_name;

// event block
modifier event delegate^ event_name
{
   modifier return_value add(delegate^ name);
   modifier void remove(delegate^ name);
   modifier void raise(parameters);
}

Parâmetros

modifier
Um modificador que pode ser usado na declaração de evento ou em um método de acessador de evento. Os valores possíveis são static e virtual.

delegate
O delegate, cuja assinatura o manipulador de eventos deve corresponder.

event_name
O nome do evento.

return_value
O valor retornado do método do acessador de eventos. Para que possa ser verificado, o tipo de retorno deve ser void.

parameters
(opcional) Parâmetros para o método raise, que correspondem à assinatura do parâmetro delegate.

Comentários

O delegado pode ter um ou mais métodos associados. Esses métodos são chamados quando o código indica que o evento ocorreu. Um evento em um programa pode ser disponibilizado para outros programas que visam o Common Language Runtime do .NET Framework.

Há dois tipos de declarações de evento:

membros de dados de evento
O compilador cria armazenamento para eventos de membros de dados como um membro do tipo delegado. Um membro de dados de evento deve ser declarado dentro de uma classe. Ele também é conhecido como evento trivial. Veja um exemplo no código de exemplo.

blocos de evento
Os blocos de eventos permitem a personalização do comportamento dos métodos add, remove e raise implementando os métodos add, remove e raise. A assinatura dos métodos add, remove e raise deve corresponder à assinatura do delegado. Eventos de blocos de eventos não são membros de dados. O uso como membro de dados gera um erro do compilador.

O tipo de retorno do manipulador de eventos deve corresponder ao tipo de retorno do delegado.

No .NET Framework, você pode tratar um membro de dados como um método (ou seja, o método Invoke do delegado correspondente). Para fazer isso, predefina o tipo de delegado para declarar um membro de dados do evento gerenciado. Por outro lado, um método de evento gerenciado definirá implicitamente o delegado gerenciado correspondente se ele ainda não estiver definido. Consulte o código de exemplo no final deste exemplo.

Ao declarar um evento gerenciado, você pode especificar os acessadores add e remove, que serão chamados quando manipuladores de eventos forem adicionados ou removidos usando os operadores += e -=. Os métodos add, remove e raise podem ser chamados explicitamente.

As seguintes etapas devem ser executadas para criar e usar eventos no Microsoft C++:

Criar ou identificar um delegado. Se você estiver definindo seu evento, também deverá garantir que haja um delegado a ser usado com a palavra-chave event. Se o evento é predefinido, no .NET Framework, por exemplo, os consumidores do evento só precisam saber o nome do delegado.
Criar uma classe que contém:
- Um evento criado a partir do delegado.
- (Opcional) Um método que verifica a existência de uma instância do delegado declarado com a palavra-chave event. Caso contrário, essa lógica deve ser colocada no código que aciona o evento.
- Métodos que chamam o evento. Esses métodos podem ser substituições de alguma funcionalidade de classe base.
Esta classe define o evento.
Definir uma ou mais classes que conectem métodos ao evento. Cada uma dessas classes associará um ou mais métodos ao evento na classe base.
Usar o evento:
- Criação de um objeto da classe que contém a declaração de evento.
- Criação de um objeto da classe que contém a definição de evento.

Para obter mais informações sobre eventos de C++/CLI, consulte Eventos em uma Interface.

Requisitos

Opção do compilador: /clr

Exemplos

O exemplo de código a seguir demonstra como declarar pares de delegados, eventos e manipuladores de eventos. Ele mostra como assinar (adicionar), invocar e, em seguida, cancelar a assinatura (remover) de manipuladores de eventos.

// mcppv2_events.cpp
// compile with: /clr
using namespace System;

// declare delegates
delegate void ClickEventHandler(int, double);
delegate void DblClickEventHandler(String^);

// class that defines events
ref class EventSource {
public:
   event ClickEventHandler^ OnClick;   // declare the event OnClick
   event DblClickEventHandler^ OnDblClick;   // declare OnDblClick

   void FireEvents() {
      // raises events
      OnClick(7, 3.14159);
      OnDblClick("Hello");
   }
};

// class that defines methods that will called when event occurs
ref class EventReceiver {
public:
   void OnMyClick(int i, double d) {
      Console::WriteLine("OnClick: {0}, {1}", i, d);
   }

   void OnMyDblClick(String^ str) {
      Console::WriteLine("OnDblClick: {0}", str);
   }
};

int main() {
   EventSource ^ MyEventSource = gcnew EventSource();
   EventReceiver^ MyEventReceiver = gcnew EventReceiver();

   // hook handler to event
   MyEventSource->OnClick += gcnew ClickEventHandler(MyEventReceiver, &EventReceiver::OnMyClick);
   MyEventSource->OnDblClick += gcnew DblClickEventHandler(MyEventReceiver, &EventReceiver::OnMyDblClick);

   // invoke events
   MyEventSource->FireEvents();

   // unhook handler to event
   MyEventSource->OnClick -= gcnew ClickEventHandler(MyEventReceiver, &EventReceiver::OnMyClick);
   MyEventSource->OnDblClick -= gcnew DblClickEventHandler(MyEventReceiver, &EventReceiver::OnMyDblClick);
}

OnClick: 7, 3.14159

OnDblClick: Hello

O exemplo de código a seguir demonstra a lógica usada para gerar o método raise de um evento trivial. Se o evento tiver um ou mais assinantes, chamar o método raise implícita ou explicitamente chama o delegado. Se o tipo de retorno do delegado não for void e se houver zero assinantes do evento, o método raise retornará o valor padrão do tipo de delegado. Se não houver nenhum assinante do evento, chamar o método raise retornará imediatamente e nenhuma exceção será gerada. Se o tipo de retorno do delegado não for void, o tipo de delegado será retornado.

// trivial_events.cpp
// compile with: /clr /c
using namespace System;
public delegate int Del();
public ref struct C {
   int i;
   event Del^ MyEvent;

   void FireEvent() {
      i = MyEvent();
   }
};

ref struct EventReceiver {
   int OnMyClick() { return 0; }
};

int main() {
   C c;
   c.i = 687;

   c.FireEvent();
   Console::WriteLine(c.i);
   c.i = 688;

   EventReceiver^ MyEventReceiver = gcnew EventReceiver();
   c.MyEvent += gcnew Del(MyEventReceiver, &EventReceiver::OnMyClick);
   Console::WriteLine(c.i);
}

0

688

Confira também

Extensões de componentes para .NET e UWP

Palavra-chave event (C++/CLI e C++/CX)

Todos os Runtimes

Sintaxe

Parâmetros

Comentários

Windows Runtime

Comentários

Requisitos

Common Language Runtime

Sintaxe

Parâmetros

Comentários

Requisitos

Exemplos

Confira também

Comentários

Comentários

Recursos adicionais

Palavra-chave `event` (C++/CLI e C++/CX)