Eventos

Funciones

Listener*	listener (...)
void	listen (void)
void	listener_destroy (...)
void	listener_update (...)
void	listener_event (...)
void	listener_pass_event (...)
uint32_t	event_type (...)
type*	event_sender (...)
type*	event_params (...)
type*	event_result (...)

Un evento es una acción que ocurre durante la ejecución del programa, normalmente de forma asíncrona o impredecible y sobre la que un determinado objeto debe ser notificado. En aplicaciones con interfaz gráfica multitud de eventos están ocurriendo constantemente cuando el usuario interactúa con los diferentes controles. No obstante, también pueden ocurrir en aplicaciones de consola, por ejemplo, al terminar de escribir un archivo en disco o al descargar una página de Internet. En un sistema de eventos intervienen dos actores: El emisor (sender), que tiene constancia cuando ocurre la acción y el receptor (receiver) al que se notifica que dicha acción ha ocurrido. Para conectar ambos extremos debemos realizar estos sencillos pasos (Listado 1) (Figura 1):

Crear un listener indicando el objeto receptor y la función callback a la que debe llamar el emisor.
Se asigna dicho listener al emisor mediante el método apropiado. Por ejemplo, el tipo Button provee el método button_OnClick para notificar de una pulsación.
Cuando se produce el evento, el emisor llama a la función callback, indicando el objeto receptor (parámetro de listener) e información detallada sobre el evento recogida en el objeto Event.

Listado 1: Función callback y evento de pulsación de un botón.

static void OnClick(AppCtrl *ctrl, Event *event)
{
    // TODO: Response to click
}

...

void CreateButton(AppCtrl *ctrl)
{
    Button *button = button_push();
    button_text(button, "Ok");
    button_OnClick(button, listener(ctrl, OnClick, AppCtrl));
}

Esquema que muestra los diferentes pasos en la gestión de eventos. — Figura 1: Evento `OnClick`.

Los eventos se utilizan de forma masiva en aplicaciones con interfaz gráfica, pero también pueden ser útiles en aplicaciones por línea de comandos. Ver, por ejemplo hfile_dir_loop en Operaciones con archivos.

listener ()

Crea un listener. Esta función vinculará un emisor de eventos con el receptor, normalmente el controlador de la aplicación. El objeto emisor (sender) es el responsable de destruir el listener.

Listener*
listener(type *obj,
         FPtr_event_handler func_event_handler,
         type);

obj	Objeto receptor que será pasado como primer parámetro a `func_event_handler`.
func_event_handler	Función callback que será llamada cuando se produzca el evento. También conocida como event handler.
type	El tipo de objeto receptor.

Retorna

Objeto listener.

listen ()

Igual que listener, pero utilizado en C++ para definir callbacks de clase. Uso de C++.

void
listen(void);

listener_destroy ()

Destruye un listener.

void
listener_destroy(Listener **listener);

listener

Listener. Será puesto a NULL tras la destrucción.

Observaciones

El emisor es el responsable de destruir el listener.

listener_update ()

Actualiza el receptor y manejador del evento. Es equivalente a destruirlo crearlo de nuevo.

void
listener_update(Listener **listener,
                Listener *new_listener);

listener	El listener actual.
new_listener	El nuevo listener.

Observaciones

Este método debe ser utilizado dentro del emisor.

listener_event ()

Lanza un evento desde el emisor (sender) hacia el receptor.

void
listener_event(Listener *listener,
               const uint32_t type,
               sender_type *sender,
               params_type *params,
               result_type *result,
               sender_type,
               params_type,
               result_type);

listener	Listener a través del cual se enviará el evento.
type	Código del evento.
sender	Generador del evento (sender).
params	Parámetros del evento, o `NULL` si no tiene.
result	Resultado del evento, o `NULL` si no se espera.
sender_type	Tipo de objeto sender.
params_type	Tipo de objeto params, o `void` si no tiene.
result_type	Tipo de objeto result, o `void` si no tiene.

Observaciones

Este método debe ser invocado dentro del emisor del evento.

listener_pass_event ()

Pasa el evento recibido a otro objeto, cambiando solo el emisor (sender). Útil para no generar un nuevo objeto Event.

void
listener_pass_event(Listener *list,
                    Event *event,
                    sender_type *sender,
                    sender_type);

list	Listener a través del cual se re-enviará el evento.
event	Evento entrante.
sender	El nuevo generador del evento.
sender_type	El tipo de objeto.

Observaciones

Este método debe ser invocado dentro del emisor del evento.

event_type ()

Obtiene el tipo de evento.

uint32_t
event_type(const Event *event);

event

Evento.

Retorna

El tipo de evento. Normalmente asociado a un enum. Ejemplos en core_event_t, gui_event_t.

event_sender ()

Obtiene el emisor del evento (sender).

type*
event_sender(Event *event,
             type);

event	Evento.
type	El tipo del emisor.

Retorna

Sender.

event_params ()

Obtiene los parámetros del evento, encapsulados en una estructura, que será diferente en función del tipo de evento.

type*
event_params(Event *event,
             type);

event	Evento.
type	El tipo de parámetros.

Retorna

Parámetros del evento.

event_result ()

Obtiene un objeto para escribir los resultados del evento. Algunos eventos requieren la devolución de datos por parte del receptor. El tipo de objeto resultado dependerá del tipo de evento.

type*
event_result(Event *event,
             type);

event	Evento.
type	El tipo de resultado.

Retorna

Resultados del evento.