event (Extensiones de componentes de C++)

La palabra clave event declara un evento, que es una notificación a los suscriptores registrados (controladores de eventos) de que se ha producido algo de interés.

Todos los runtimes

C++/CX admite declarar un miembro de evento o un bloque de evento. Un miembro de evento es una versión abreviada para declarar un bloque de evento. De forma predeterminada, un miembro de evento declara las funciones add(), remove() y raise() que se declaran explícitamente en un bloque de evento. Para personalizar las funciones en un miembro de evento, declare un bloque de evento en su lugar y después reemplace las funciones que necesite.

Sintaxis

// 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
  Un modificador que se puede utilizar en la declaración de evento o un método de descriptor de acceso event. Los valores posibles son static y virtual.

• delegate
  El delegado, cuya signatura debe coincidir con el controlador de eventos.

• event_name
  Nombre del evento.

• return_value
  El tipo del valor devuelto del método del descriptor de acceso de evento. Para que se pueda comprobar, el tipo de valor devuelto debe ser void.

• parameters
  parámetros (opcional) para el método de raise , que coinciden con la firma de parámetro de delegate .

Comentarios

Un evento es una asociación entre un delegado y una función de miembro (controlador de eventos) que responde al desencadenamiento del evento y permite que los clientes de cualquier clase puedan registrar métodos que cumplen con la signatura y el tipo de valor devuelto del delegado subyacente.

Hay dos tipos de declaraciones de eventos:

• miembro de datos de eventos
  El compilador crea automáticamente el almacenamiento para el evento en forma de miembro de tipo de delegado y crea funciones miembro add(), remove() y raise() internas. Un miembro de datos de eventos debe declararse dentro de una clase. El tipo del valor devuelto del delegado debe coincidir con el del controlador de eventos.

• bloque de evento
  Un bloque event le permite declarar y personalizar de forma explícita el comportamiento de los métodos add(), remove() y raise() .

Puede usar operators+= y operator-= para agregar y quitar un controlador de eventos, o llamar a los métodos add() y remove() explícitamente.

event es una palabra clave contextual; vea Palabras clave contextuales (Extensiones de componentes de C++) para obtener más información.

Windows en tiempo de ejecución

Comentarios

Para obtener más información, vea Eventos (C++/CX).

Si piensa agregar y después quitar un controlador de eventos, debe guardar la estructura de EventRegistrationToken devuelta por la operación add. A continuación en la operación de quitar, debe usar la estructura guardada de EventRegistrationToken para identificar el controlador de eventos que se quitará.

Requisitos

Opción del compilador: /ZW

Common Language Runtime

La palabra clave event permite declarar un evento. Un evento es una manera de que una clase proporcione notificaciones cuando ocurre algo de interés.

Sintaxis

// 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
  Un modificador que se puede utilizar en la declaración de evento o un método de descriptor de acceso event. Los valores posibles son static y virtual.

• delegate
  El delegado, cuya signatura debe coincidir con el controlador de eventos.

• event_name
  Nombre del evento.

• return_value
  El tipo del valor devuelto del método del descriptor de acceso de evento. Para que se pueda comprobar, el tipo de valor devuelto debe ser void.

• parameters
  parámetros (opcional) para el método de raise , que coinciden con la firma de parámetro de delegate .

Comentarios

Un evento es una asociación entre un delegado y una función de miembro (controlador de eventos) que responde al desencadenamiento del evento y permite que los clientes de cualquier clase puedan registrar métodos que cumplen con la signatura y el tipo de valor devuelto del delegado subyacente.

El delegado puede tener uno o más métodos asociados a los que se llama cuando el código indica que el evento se ha producido. Un evento en un programa se puede hacer que esté disponible para otros programas orientados a Common Language Runtime de .NET Framework. Vea Generar un evento definido en otro ensamblado para obtener un ejemplo.

Hay dos tipos de declaraciones de eventos:

• miembros de datos de eventos
  El compilador de los eventos del miembro de datos crea el almacenamiento para el evento, en forma de miembro del tipo de delegado. Un miembro de datos de eventos debe declararse dentro de una clase. Esto también se conoce como evento trivial (vea el ejemplo de código siguiente).

• bloques de evento
  Los bloques de evento permiten personalizar el comportamiento de los métodos para agregar, quitar y generar implementando los métodos add, remove y raise. La signatura de los métodos para agregar, quitar y generar debe coincidir con la del delegado. Los eventos del bloque de evento no son miembros de datos y cualquier uso como miembro de datos generará un error del compilador. Vea Definición de métodos de descriptor de acceso a eventos para obtener un ejemplo.

El tipo de valor devuelto del controlador de eventos debe coincidir con el del delegado.

En .NET Framework, puede tratar un miembro de datos como si se tratara de un método en sí mismo (es decir, el método Invoke de su delegado correspondiente). Debe predefinir el tipo de delegado para declarar un miembro de datos de evento administrado. En cambio, un método de evento administrado define implícitamente el delegado administrado correspondiente si todavía no se ha definido. Vea un ejemplo de código al final de este tema para obtener un ejemplo.

Al declarar un evento administrado, puede especificar que se agreguen y quiten los descriptores de acceso a los que se llamará cuando se agreguen o quiten los controladores de eventos mediante los operadores += y -=. Los métodos add, remove y raise se pueden invocar explícitamente.

Los pasos siguientes deben realizarse por orden para crear y usar eventos en Visual C++:

1. Cree o identifique un delegado. Si desea definir su propio evento, debe asegurarse también de que haya un delegado para utilizar con la palabra clave event . Si el evento está predefinido, por ejemplo en .NET Framework, los consumidores del evento necesitan conocer únicamente el nombre del delegado.

2. Cree una clase que contiene:

   • Un evento creado a partir del delegado.

   • (opcional) Un método que comprueba que existe una instancia del delegado declarada con la palabra clave event. De lo contrario, esta lógica se debe colocar en el código que desencadena el evento.

   • Métodos que llaman el evento. Estos métodos pueden ser invalidaciones de alguna funcionalidad de la clase base.

   Esta clase define el evento.

3. Defina una o más clases que conectan los métodos al evento. Cada una de estas clases asociará uno o más métodos con el evento en la clase base.

4. Usar el evento:

   • Cree un objeto de clase que contiene la declaración de evento.

   • Cree un objeto de clase que contiene la definición de evento.

Para obtener más información acerca de los eventos C++/CLI, vea

• Eventos en una interfaz

• Invalidar el acceso predeterminado de los métodos add, remove y raise

• Varios controladores para un evento

• Eventos virtuales administrados

• Métodos de descriptor de acceso de eventos

• Eventos estáticos

• Generar un evento definido en otro ensamblado

• Eventos abstractos

Requisitos

Opción del compilador: /clr

Ejemplos

Ejemplo

En el ejemplo de código siguiente se muestra cómo declarar los pares de delegados, eventos y controladores de eventos; suscribirse (agregarse) a los controladores de eventos; invocar controladores de eventos; y después cancelar la suscripción a los controladores de eventos (quitarlos).

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

Resultados

Ejemplo

En el ejemplo de código siguiente se muestra la lógica usada para generar el método raise de un evento trivial: Si el evento tiene uno o más suscriptores, la llamada al método raise llama al delegado de forma implícita o explícita. Si el tipo devuelto del delegado no es void y si hay suscriptores cero de eventos, el método de raise devuelve el valor predeterminado para el tipo de delegado. Si no hay suscriptores de eventos, llamando al método raise simplemente se devuelve pero no se inicia ninguna excepción. Si el tipo devuelto del delegado no es void, se devuelve el tipo de delegado.

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

Resultados

0

Vea también

Conceptos

Extensiones de componentes para plataformas de tiempo de ejecución