Tutorial: Controlar eventos

Artículo
10/07/2008

Actualización: noviembre 2007

Éste es el segundo de los dos temas que muestran cómo trabajar con eventos. En el primer tema, Tutorial: Declarar y provocar eventos, se muestra cómo declarar y provocar eventos. Esta sección utiliza el formulario y la clase del tutorial para mostrar cómo controlar eventos cuando tienen lugar.

La clase Widget de ejemplo utiliza las instrucciones de control de eventos tradicionales. Visual Basic proporciona otras técnicas para trabajar con eventos. Como ejercicio, puede modificar este ejemplo para utilizar las instrucciones AddHandler y Handles.

Coloque el código siguiente en Form1:
```
Private WithEvents mWidget As Widget
Private mblnCancel As Boolean
```
La palabra clave WithEvents especifica que se utiliza la variable mWidget para controlar los eventos de un objeto. Puede especificar el tipo de objeto proporcionando el nombre de la clase de la que se creará el objeto.

La variable mWidget se declara en Form1 porque las variables WithEvents deben ser de nivel de clase. Esto es cierto independientemente del tipo de módulo donde se coloquen.

Se utiliza la variable mblnCancel para cancelar el método LongTask.

Escritura de código para controlar eventos

Tan pronto como declara una variable utilizando WithEvents, el nombre de variable aparece en la lista desplegable izquierda del Editor de código de la clase. Cuando selecciona mWidget, aparecen los eventos de la clase Widget en la lista desplegable derecha. Al seleccionar un evento se muestra el procedimiento de evento correspondiente, con el prefijo mWidget y un carácter de subrayado. Se da a todos los procedimientos de eventos asociados a la variable WithEvents el nombre de variable como prefijo.

Para controlar un evento

Seleccione mWidget en la lista desplegable izquierda del Editor de código.

Seleccione el evento PercentDone en la lista desplegable derecha. El Editor de código abre el procedimiento de evento mWidget_PercentDone.

Nota:
El Editor de código es útil, pero no necesario, para insertar los nuevos controladores de eventos. En este tutorial, es más directo copiar simplemente los controladores de eventos en el código.

Agregue el código siguiente al controlador de eventos mWidget_PercentDone:
```
Private Sub mWidget_PercentDone( _
    ByVal Percent As Single, _
    ByRef Cancel As Boolean _
) Handles mWidget.PercentDone
    lblPercentDone.Text = CInt(100 * Percent) & "%"
    My.Application.DoEvents()
    If mblnCancel Then Cancel = True
End Sub
```
Siempre que se provoca el evento PercentDone, el procedimiento de evento muestra el porcentaje completo en un control Label. El método DoEvents permite volver a dibujar la etiqueta y también le da al usuario la oportunidad de hacer clic en el botón Cancel.

Agregue el código siguiente para el controlador de eventos Button2_Click:

Private Sub Button2_Click( _
    ByVal sender As Object, _
    ByVal e As System.EventArgs _
) Handles Button2.Click
    mblnCancel = True
End Sub

Si el usuario hace clic en el botón Cancel cuando se está ejecutando LongTask, se ejecuta el evento Button2_Click tan pronto como la instrucción DoEvents permite que se produzca el procesamiento de eventos. La variable mblnCancel de nivel de clase se establece como True y el evento mWidget_PercentDone lo comprueba luego y establece el argumento ByRef Cancel como True.

Conectar la variable WithEvents con un objeto

Form1 está ahora configurado para controlar los eventos de un objeto Widget. Sólo queda buscar un objeto Widget en alguna parte.

Cuando declara una variable WithEvents en tiempo de diseño, no se asocia ningún objeto a ésta. La variable WithEvents es como cualquier otra variable de objeto. Tendrá que crear un objeto y asignar una referencia a éste con la variable WithEvents.

Para crear un objeto y asignarlo una referencia

Seleccione (Eventos Form1) en la lista desplegable izquierda del Editor de código.
Seleccione el evento Load en la lista desplegable derecha. El Editor de código abre el procedimiento de evento Form1_Load.

Agregue el código siguiente para el procedimiento de evento Form1_Load a fin de crear el objeto Widget:

Private Sub Form1_Load( _
    ByVal sender As System.Object, _
    ByVal e As System.EventArgs _
) Handles MyBase.Load
    mWidget = New Widget
End Sub

Cuando se ejecuta este código, Visual Basic crea un objeto Widget y conecta sus eventos a los procedimientos de evento asociados con mWidget. Desde este momento en adelante, siempre que el objeto Widget provoque el evento PercentDone, se ejecutará el procedimiento de evento mWidget_PercentDone.

Para llamar al método LongTask

Agregue el código siguiente al controlador de eventos Button1_Click:

Private Sub Button1_Click( _
    ByVal sender As Object, _
    ByVal e As System.EventArgs _
) Handles Button1.Click
    mblnCancel = False
    lblPercentDone.Text = "0%"
    lblPercentDone.Refresh()
    mWidget.LongTask(12.2, 0.33)
    If Not mblnCancel Then lblPercentDone.Text = CStr(100) & "%"
End Sub

Antes de llamar al método LongTask, la etiqueta que muestra el porcentaje completo debe inicializarse y el indicador Boolean de nivel de clase que cancela el método debe establecerse como False.

LongTask se llama con una duración de tarea de 12,2 segundos. Se provoca el evento PercentDone una vez cada tercio de segundo. Cada vez que se provoca el evento, se ejecuta el procedimiento de evento mWidget_PercentDone.

Cuando termina LongTask, se comprueba mblnCancel para ver si LongTask ha finalizado de forma normal o si se ha detenido porque mblnCancel estaba establecido como True. El porcentaje completo se actualiza sólo en el primer caso.

Para ejecutar el programa

Presione F5 para poner el proyecto en modo de ejecución.
Haga clic en el botón Iniciar tarea. Cada vez que se provoca el evento PercentDone, se actualiza la etiqueta con el porcentaje de la tarea que se ha completado.

Haga clic en el botón Cancelar para detener la tarea. Observe que la apariencia del botón Cancelar no cambia inmediatamente cuando se hace clic en él. El evento Click no puede tener lugar hasta que la instrucción My.Application.DoEvents permita el procesamiento del evento.

Nota:
El método My.Application.DoEvents no procesa los eventos exactamente de la misma manera en que lo hace el formulario. Por ejemplo, en este tutorial, debe hacer clic dos veces en el botón Cancelar. Para permitir que el formulario controle directamente los eventos, puede utilizar el subprocesamiento múltiple. Para obtener más información, vea Subprocesamiento múltiple en Visual Basic.

Puede resultarle instructivo ejecutar el programa con F11 y recorrer el código línea a línea. Puede ver claramente cómo la ejecución escribe LongTask y luego vuelve a escribir Form1 brevemente cada vez que se provoca el evento PercentDone.

¿Qué sucedería si cuando se estaba devolviendo la ejecución al código de Form1, se llamara al método LongTask de nuevo? En el peor de los casos, podría ocurrir un desbordamiento de la pila si se llamara a LongTask cada vez que se provocara el evento.

Puede hacer que la variable mWidget controle los eventos de un objeto Widget distinto asignando una referencia al nuevo Widget con mWidget. De hecho, puede hacer que el código de Button1_Click realice esto cada vez que hace clic en el botón.

Agregue la línea de código siguiente al procedimiento Button1_Click, inmediatamente antes de la línea que indica mWidget.LongTask(12.2, 0.33):
```
mWidget = New Widget
' Create a new Widget object.
```

El código anterior crea un nuevo Widget cada vez que se hace clic en el botón. Tan pronto como finaliza el método LongTask, se libera la referencia al objeto Widget y se destruye éste.

Las variables WithEvents pueden contener sólo una referencia a objeto a la vez, de modo que si asigna otro objeto Widget a mWidget, los eventos del objeto Widget anterior ya no se controlarán. Si mWidget es la única variable de objeto que contiene una referencia al objeto Widget antiguo, éste se destruirá. Si desea controlar eventos desde varios objetos Widget, utilice la instrucción AddHandler para procesar independientemente los eventos de cada objeto.

Nota:
Puede declarar todas las variables WithEvents que sean necesarias, pero no se admiten las matrices de variables WithEvents.

Vea también

Tutorial: Controlar eventos

Para controlar el evento PercentDone de la clase Widget

Escritura de código para controlar eventos

Para controlar un evento

Conectar la variable WithEvents con un objeto

Para crear un objeto y asignarlo una referencia

Para llamar al método LongTask

Para ejecutar el programa

Para controlar eventos para un Widget distinto

Vea también

Tareas

Conceptos

Referencia

Otros recursos

Recursos adicionales