Clase wxEvtHandler

Constructor.

Destructor.

Si el manipulador forma parte de una cadena, el destructor se desvinculará a sí mismo (véase Unlink()).

Añade un filtro de eventos cuyo método FilterEvent() será llamado para todos y cada uno de los eventos procesados por wxWidgets.

Los filtros son llamados en orden LIFO y wxApp está registrado como filtro de eventos por defecto. El puntero debe permanecer válido hasta que sea eliminado con RemoveFilter() y no sea borrado por wxEvtHandler.

Envía un evento para ser procesado más tarde.

Esta función es similar a QueueEvent() pero no puede utilizarse para enviar eventos desde hilos de trabajo para los objetos de evento con campos wxString (es decir, en la práctica la mayoría de ellos) debido a un uso inseguro del mismo objeto wxString que ocurre porque el campo wxString en el objeto de evento original y su copia hecha internamente por esta función comparten el mismo búfer de cadena internamente. Utilizar QueueEvent() para evitar esto.

La función hace una copia de event, por lo que el original puede ser borrado tan pronto como la función retorne (es común que el original sea creado en la pila). Esto requiere que el método wxEvent::Clone() sea implementado por event para que pueda ser duplicado y almacenado hasta que sea procesado.

Parámetros

Event

Evento a añadir a la cola de eventos pendientes.

Conecta la función, functor o método dado dinámicamente con el evento.

Esto ofrece básicamente la misma funcionalidad que Connect(), pero es más flexible ya que también permite utilizar funciones ordinarias y functores arbitrarios como manejadores de eventos. También es menos restrictivo que Connect() porque puede utilizar un método arbitrario como manejador de eventos, mientras que Connect()requiere un manejador derivado de wxEvtHandler.

Parámetros

eventType

El tipo de evento que se asociará a este manejador de eventos.

functor

El functor del manejador de eventos. Puede ser una función ordinaria pero también un functor arbitrario como boost::function<>.

id

El primer ID del rango de identificadores a asociar con el manejador de eventos.

lastId

El último ID del rango de identificadores a asociar con el manejador de eventos.

userData

Datos opcionales a asociar con la entrada de la tabla de eventos. wxWidgets tomará posesión de este puntero, es decir, será destruido cuando el manejador de eventos se desconecte o al finalizar el programa. Este puntero puede ser recuperado usando wxEvent::GetEventUserData() más tarde.

Ver la sobrecarga Bind<>(const EventTag&, Functor, int, int, wxObject*) para más información.

Esta sobrecarga vinculará el método dado como manejador del evento.

Parámetros

eventType

El tipo de evento a asociar con este manejador de eventos.

method

El método del manejador de eventos. Puede ser un método arbitrario (no necesita ser de una clase derivada de wxEvtHandler).

handler

Objeto cuyo método debe ser llamado. Debe especificarse siempre para que pueda comprobarse en tiempo de compilación si el método dado es un miembro real del manejador dado.

id

El primer ID del rango de identificadores a asociar con el manejador de eventos.

lastId

El último ID del rango de identificadores a asociar con el manejador de eventos.

userData

Datos opcionales a asociar con la entrada de la tabla de eventos. wxWidgets tomará posesión de este puntero, es decir, será destruido cuando el manejador de eventos se desconecte o al finalizar el programa. Este puntero puede ser recuperado usando wxEvent::GetEventUserData() más tarde.

Llama asíncronamente al functor dado.

Llamar a esta función sobre un objeto programa una llamada asíncrona al functor especificado como argumento CallAfter() en un momento (ligeramente) posterior. Esto es útil cuando se procesan algunos eventos ya que ciertas acciones típicamente no pueden realizarse dentro de sus manejadores, por ejemplo, no se debería mostrar un diálogo modal desde un manejador de evento de clic de ratón ya que esto rompería el estado de captura del ratón - pero se puede llamar a una función que muestre este diálogo de mensaje después de que el manejador de evento actual se complete.

Hay que tener en cuenta que es seguro utilizar CallAfter() desde otros hilos, no GUI, pero que el método siempre será llamado en el contexto del hilo principal, GUI.

Esta sobrecarga es particularmente útil en combinación con lambdas C++11:

wxGetApp().CallAfter([]{
    wxBell();
});

Parámetros

functor

El functor a llamar.

Nota: Este método no está disponible con Visual C++ antes de la versión 8 (Visual Studio 2005), ya que las versiones anteriores del compilador no tienen el soporte necesario para plantillas C++ para implementarlo.

Llama asíncronamente al método dado.

Llamar a esta función sobre un objeto programa una llamada asíncrona al método especificado como argumento CallAfter() en un momento (ligeramente) posterior. Esto es útil cuando se procesan algunos eventos ya que ciertas acciones típicamente no pueden ser realizadas dentro de sus manejadores, por ejemplo, no se debería mostrar un diálogo modal desde un manejador de evento de clic de ratón ya que esto rompería el estado de captura del ratón - pero se puede llamar a un método que muestre este diálogo de mensaje después de que el manejador de evento actual se complete.

El método llamado debe ser el método del objeto sobre el que se llama a CallAfter().

Hay que tener en cuenta que es seguro utilizar CallAfter() desde otros hilos, no GUI, pero que el método siempre será llamado en el contexto del hilo principal, GUI.

Ejemplo de uso:

class MyFrame : public wxFrame {
   void OnClick(wxMouseEvent& event) {
       CallAfter(&MyFrame::ShowPosition, event.GetPosition());
   }
 
   void ShowPosition(const wxPoint& pos) {
       if ( wxMessageBox(
               wxString::Format("Perform click at (%d, %d)?",
                                pos.x, pos.y), "", wxYES_NO) == wxYES )
       {
           ... do take this click into account ...
       }
   }
};

Parámetros

method

El método a llamar.

x1

El primer parámetro (opcional) que se pasa al método. Actualmente, se pueden pasar 0, 1 o 2 parámetros. Si se necesita pasar más de 2 argumentos, se puede usar la sobrecarga CallAfter<T>(const T& fn) que puede llamar a cualquier functor.

Nota: Este método no está disponible con Visual C++ antes de la versión 8 (Visual Studio 2005), ya que las versiones anteriores del compilador no tienen el soporte necesario para plantillas C++ para implementarlo.

Conecta la función dada dinámicamente con el manejador de eventos, id y tipo de evento.

Hay que tener en cuenta que Bind() proporciona una forma más flexible y segura de hacer lo mismo que Connect(), por favor, habría que utilizarlo en cualquier código nuevo - aunque Connect() no está formalmente obsoleto debido a su uso generalizado existente, no tiene ventajas en comparación con Bind() y tiene una serie de inconvenientes, incluyendo:

• Menos seguridad en tiempo de compilación.
• Orden de parámetros poco intuitivo.
• Limitado al uso con los métodos de las clases que heredan públicamente de wxEvtHandler.

Es una alternativa al uso de tablas de eventos estáticas. Es más flexible ya que permite conectar eventos generados por algún objeto a un manejador de eventos definido en un objeto diferente de una clase diferente (lo que es imposible hacer directamente con las tablas de eventos - los eventos solo pueden ser manejados en otro objeto si se propagan hacia arriba hasta él). Hay que asegurarse de especificar el eventSink correcto cuando se conecta a un evento de un objeto diferente.

Esta sobrecarga específica le permite conectar un manejador de eventos a un rango de IDs fuente. No confundir los IDs de origen con los tipos de eventos: los IDs de origen identifican los objetos generadores de eventos (típicamente objetos wxMenuItem o wxWindow) mientras que el tipo de evento identifica qué tipo de eventos deben ser manejados por la función dada (¡un objeto generador de eventos puede generar muchos tipos diferentes de eventos!).

Parámetros

id

El primer ID del rango de identificadores que se asociará a la función manejadora de eventos.

lastId

El último ID del rango de identificadores a ser asociado con la función manejadora de eventos.

eventType

El tipo de evento a ser asociado con este manejador de eventos.

function

La función del manejador de eventos. Hay que tener en cuenta que esta función debe ser convertida explícitamente al tipo correcto, lo que puede hacerse utilizando una macro llamada wxFooEventHandler para el manejador de cualquier wxFooEvent.

userData

Datos opcionales a asociar con la entrada de la tabla de eventos. wxWidgets tomará posesión de este puntero, es decir, será destruido cuando el manejador de eventos se desconecte o al finalizar el programa. Este puntero puede ser recuperado usando wxEvent::GetEventUserData() más tarde.

eventSink

Objeto cuya función miembro debe ser llamada. Debe especificarse cuando se conecta un evento generado por un objeto a una función miembro de un objeto diferente. Si se omite, se utiliza éste.

Nota: En wxPerl esta función toma 4 argumentos: id, lastid, type, method; si method es undef, el manejador se desconecta.

Ver la sobrecarga Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) para más información.

Esta sobrecarga se puede utilizar para adjuntar un controlador de eventos a un único ID de origen:

Ejemplo:

frame->Connect( wxID_EXIT,
                wxEVT_MENU,
                wxCommandEventHandler(MyFrame::OnQuit) );

Nota: No soportado por wxPerl.

Ver la sobrecarga Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) para más información.

Esta sobrecarga conectará el manejador de eventos dado para que, independientemente del ID de la fuente del evento, el manejador sea llamado.

Nota: No soportado por wxPerl.

Borra todos los eventos en cola en este manejador de eventos usando QueueEvent() o AddPendingEvent().

Hay que utilizarlo con cuidado porque los eventos que se eliminan (obviamente) no se procesan y esto puede tener consecuencias no deseadas (por ejemplo, se perderán los eventos de acciones del usuario).

Ver la sobrecarga Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) para más información.

Esta sobrecarga toma un rango adicional de IDs de origen.

Nota: En wxPerl esta función toma 3 argumentos: id, lastid, type.

Ver la sobrecarga Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) para más información.

Esta sobrecarga toma el parámetro adicional id.

Nota: No soportada en wxPerl.

Desconecta la función dada dinámicamente del manejador de eventos, utilizando los parámetros especificados como criterios de búsqueda y devolviendo true si se ha encontrado y eliminado una función coincidente.

Este método sólo puede desconectar funciones que hayan sido añadidas utilizando el método Connect(). No hay forma de desconectar funciones conectadas usando las tablas de eventos (estáticas).

Parámetros

eventType

El tipo de evento asociado con este manejador de eventos.

function

La función del manejador de eventos.

userData

Datos asociados con la entrada de la tabla de eventos.

eventSink

Objeto cuya función miembro debe ser llamada.

Nota: No soportada en wxPerl.

Devuelve los datos del cliente proporcionados por el usuario.

Observaciones

Normalmente, cualquier dato extra que el programador desee asociar al objeto debería estar disponible derivando una nueva clase con nuevos miembros de datos.

Devuelve un puntero al objeto de datos del cliente proporcionado por el usuario.

Devuelve true si el manejador de eventos está habilitado, false en caso contrario.

Devuelve el puntero al siguiente manejador de la cadena.

Devuelve el puntero al gestor anterior de la cadena.

Devuelve true si los punteros del manejador siguiente y anterior de esta instancia de manejador de eventos son NULL.

Procesa un evento, buscando en las tablas de eventos y llamando a cero o más funciones manejadoras de eventos adecuadas.

Normalmente, una aplicación no llamaría a esta función: es llamada en la implementación de wxWidgets para enviar los eventos entrantes de la interfaz de usuario al framework (y a la aplicación).

Sin embargo, puede ser necesario llamarla si se implementa una nueva funcionalidad (como un nuevo control) donde se definen nuevos tipos de eventos, en lugar de permitir al usuario anular funciones virtuales.

Hay que tener en cuenta que normalmente no es necesario invalidar ProcessEvent() para personalizar el manejo de eventos, invalidar las funciones TryBefore() y TryAfter() suele ser suficiente. Por ejemplo, wxMDIParentFrame puede sobrescribir TryBefore() para asegurar que los eventos del menú son procesados en el marco hijo activo antes de ser procesados en el propio marco padre.

El orden normal de búsqueda en la tabla de eventos es el siguiente:

1. Se llama a wxApp::FilterEvent(). Si devuelve algo distinto de -1 (por defecto) el proceso se detiene aquí.
2. Se llama a TryBefore() (aquí es donde se tiene en cuenta wxValidator para los objetos wxWindow). Si devuelve true, la función finaliza.
3. Si el objeto está deshabilitado (mediante una llamada a wxEvtHandler::SetEvtHandlerEnabled) la función salta al paso (7).
4. En la tabla de eventos dinámicos de los manejadores enlazados usando Bind<>() se busca en el orden desde el más recientemente enlazado hasta el más tempranamente enlazado. Si se encuentra un manejador, se ejecuta y la función devuelve true a menos que el manejador haya utilizado wxEvent::Skip() para indicar que no ha manejado el evento, en cuyo caso la búsqueda continúa.
5. En la tabla de eventos estáticos de los manejadores vinculados mediante macros de tabla de eventos se busca para este manejador de eventos en el orden de aparición de las macros de tabla de eventos en el código fuente. Si esto falla, se intenta en la tabla de eventos de la clase base, y así sucesivamente hasta que no existan más tablas o se haya encontrado una función apropiada. Si se encuentra un manejador, se aplica la misma lógica que en el paso anterior.

6. La búsqueda se aplica a lo largo de toda la cadena de manejadores de eventos (normalmente la cadena tiene una longitud de uno). Esta cadena se puede formar utilizando wxEvtHandler::SetNextHandler():

   

   (refiriéndonos a la imagen, si A->ProcessEvent es llamado y no maneja el evento, B->ProcessEvent será llamado y así sucesivamente...). Hay que tener en cuenta que en el caso de wxWindow puede construir una pila de manejadores de eventos (ver wxWindow::PushEventHandler() para más información). Si alguno de los manejadores de la cadena devuelve true, la función sale.

7. Se llama a TryAfter(): para el objeto wxWindow esto puede propagar el evento a la ventana padre (recursivamente). Si el evento sigue sin procesarse, se llama a ProcessEvent() en el objeto wxTheApp como último paso.

Observese que los pasos (2)-(6) se realizan en ProcessEventLocally() que es llamada por esta función.

Parámetros

event

Evento a procesar.

Valor de retrono

true si se encontró y ejecutó una función manejadora de eventos adecuada, y la función no llamó a wxEvent::Skip.

Intenta procesar el evento en este manejador y todos los encadenados a él.

Como se explica en la documentación de ProcessEvent(), los manejadores de eventos pueden estar encadenados en una lista doblemente enlazada. Esta función intenta procesar el evento en este manejador (incluyendo la realización de cualquier pre-procesamiento hecho en TryBefore(), por ejemplo aplicando validadores) y todos los que le siguen en la cadena hasta que el evento es procesado o la cadena se agota.

Esta función es llamada desde ProcessEvent() y, a su vez, llama a TryBefore() y TryAfter(). No es virtual y por lo tanto no puede ser sobrescrita pero puede, y debería, ser llamada para reenviar un evento a otro manejador en lugar de ProcessEvent() que resultaría en una llamada duplicada a TryAfter(), por ejemplo, resultando en que todos los eventos no procesados sean enviados al objeto de aplicación múltiples veces.

Parámetros

event

Evento a procesar

Valor de retorno

true si este manejador o uno de los encadenados a él procesó el evento.

Procesa los eventos pendientes previamente puestos en cola usando QueueEvent() o AddPendingEvent(); debe llamar a esta función sólo si está seguro de que hay eventos pendientes para este manejador, de lo contrario un wxCHECK fallará.

El procesamiento real todavía ocurre en ProcessEvent() que es llamada por esta función.

Hay que tener en cuenta que esta función necesita un objeto de aplicación válido (ver wxAppConsole::GetInstance()) porque wxApp contiene la lista de los manejadores de eventos con eventos pendientes y esta función manipula esa lista.

Pone en cola un evento para procesarlo más tarde.

Este método es similar a ProcessEvent() pero mientras que este último es síncrono, es decir, el evento es procesado inmediatamente, antes de que la función retorne, éste es asíncrono y retorna inmediatamente mientras que el evento será procesado en algún momento posterior (normalmente durante la siguiente iteración del bucle de eventos).

Otra diferencia importante es que este método se apropia del parámetro del evento, es decir, lo borrará él mismo. Esto implica que el evento debe ser asignado en el heap y que el puntero no puede ser usado más después de que la función retorne (ya que puede ser borrado en cualquier momento).

QueueEvent() puede usarse para la comunicación entre hilos desde los hilos trabajadores al hilo principal, es seguro en el sentido de que usa el bloqueo internamente y evita el problema mencionado en la documentación de AddPendingEvent() asegurando que el objeto evento no es usado más por el hilo llamante. Aún así, hay que tener cuidado para evitar que algunos campos de este objeto sean utilizados por él, en particular cualquier miembro wxString del objeto evento no debe ser una copia superficial de otro objeto wxString ya que esto resultaría en que siguieran utilizando el mismo buffer de cadena entre bastidores.

Por ejemplo:

void FunctionInAWorkerThread(const wxString& str)
{
    wxCommandEvent* evt = new wxCommandEvent;
 
    // NOT evt->SetString(str) as this would be a shallow copy
    evt->SetString(str.c_str()); // make a deep copy
 
    wxTheApp->QueueEvent( evt );
}

Hay que tener en cuenta que se puede utilizar wxThreadEvent en lugar de wxCommandEvent para evitar este problema:

void FunctionInAWorkerThread(const wxString& str)
{
    wxThreadEvent evt;
    evt.SetString(str);
 
    // wxThreadEvent::Clone() makes sure that the internal wxString
    // member is not shared by other wxString instances:
    wxTheApp->QueueEvent( evt.Clone() );
}

Finalmente nótese que este método despierta automáticamente el bucle de eventos si está actualmente inactivo llamando a wxWakeUpIdle() por lo que no hay necesidad de hacerlo manualmente cuando se usa.

Parámetros

event

Un evento heap-allocated para ser puesto en cola, QueueEvent() toma posesión de él. Este parámetro no debe ser NULL.

Reimplementado en wxWindow.

Elimina un filtro previamente instalado con AddFilter().

Es un error eliminar un filtro que no se había añadido previamente o que ya se había eliminado.

Procesa un evento llamando a ProcessEvent() y maneja cualquier excepción que ocurra en el proceso.

Si se lanza una excepción en el manejador de eventos, se llama a wxApp::OnExceptionInMainLoop.

Parámetros

event

Evento a procesar.

Valor de retorno

true si el evento fue procesado, false si no se encontró ningún manejador o se lanzó una excepción.

Establece los datos del cliente proporcionados por el usuario.

Parámetros

data

Datos a asociar con el manejador de eventos.

Observaciones

Normalmente, cualquier dato extra que el programador desee asociar al objeto debería estar disponible derivando una nueva clase con nuevos miembros de datos. No se debe llamar a este método y a SetClientObject en la misma clase - sólo a uno de ellos.

Establece el objeto de datos del cliente.

Se eliminará cualquier objeto anterior.

Activa o desactiva el manejador de eventos.

Parámetros

enabled

true si se quiere habilitar el manejador de eventos, false si se quiere deshabilitar.

Observaciones

Se puede utilizar esta función para evitar tener que eliminar el manejador de eventos de la cadena, por ejemplo al implementar un editor de diálogos y cambiar del modo edición al modo prueba.

Establece el puntero al siguiente manejador.

Observaciones

Ver ProcessEvent() para más información sobre cómo se utilizan internamente las cadenas de manejadores de eventos. Recordar también que wxEvtHandler utiliza listas doblemente enlazadas y por tanto si se utiliza esta función, se debería llamar también a SetPreviousHandler() sobre el argumento pasado a esta función:

handlerA->SetNextHandler(handlerB);
handlerB->SetPreviousHandler(handlerA);

Parámetros

handler

El manejador de eventos que se establecerá como siguiente manejador. No puede ser NULL.

Establece el puntero al manejador anterior.

Todas las observaciones sobre SetNextHandler() se aplican también a esta función.

Parámetros

handler

El manejador de eventos que se establecerá como manejador anterior. No puede ser NULL.

Método llamado por ProcessEvent() como último recurso.

Este método puede ser sobrescrito para implementar el post-procesamiento de los eventos que no fueron procesados en ningún otro lugar.

La versión de la clase base se encarga de reenviar los eventos no procesados a wxApp a nivel de wxEvtHandler y propagarlos hacia arriba por la cadena de ventanas hijo-padre a nivel de wxWindow, por lo que normalmente se debería llamar cuando se sobrescribe este método:

class MyClass : public BaseClass // inheriting from wxEvtHandler
{
...
protected:
    virtual bool TryAfter(wxEvent& event)
    {
        if ( BaseClass::TryAfter(event) )
            return true;
 
        return MyPostProcess(event);
    }
};

Método llamado por ProcessEvent() antes de examinar las tablas de eventos de este objeto.

Este método puede ser sobrescrito para engancharse a la lógica de procesamiento de eventos tan pronto como sea posible. Normalmente debería llamar a la versión de la clase base cuando sobrescriba este método, incluso si wxEvtHandler no hace nada aquí, algunas clases derivadas utilizan este método, p.e. wxWindow implementa soporte para wxValidator en ella.

Ejemplo:

class MyClass : public BaseClass // inheriting from wxEvtHandler
{
...
protected:
    virtual bool TryBefore(wxEvent& event)
    {
        if ( MyPreProcess(event) )
            return true;
 
        return BaseClass::TryBefore(event);
    }
};

Desvincula dinámicamente del manejador de eventos la función, functor o método dado, utilizando los parámetros especificados como criterios de búsqueda y devolviendo true si se ha encontrado y eliminado una función coincidente.

Este método solo puede desvincular funciones, funtores o métodos que hayan sido añadidos usando el método Bind<>(). No hay forma de desvincular funciones vinculadas usando las tablas de eventos (estáticas).

Nota: Actualmente los functores se comparan por su dirección lo que, desafortunadamente, no funciona correctamente si la misma dirección se reutiliza para dos objetos functor diferentes. Debido a esto, no se recomienda usar Unbind() si hay múltiples functores usando el mismo eventType e id y lastId ya que uno incorrecto podría ser desvinculado.

Parámetros

eventType

El tipo de evento asociado con este manejador de eventos.

functor

El functor del manejador de eventos. Puede ser una función ordinaria pero también un functor arbitrario como boost::function<>.

id

El primer ID del rango de identificadores asociado con el manejador de eventos.

lastId

El último ID del rango de identificadores asociado con el manejador de eventos.

userData

Datos asociados con la entrada de la tabla de eventos.

Ver la sobrecarga Unbind<>(const EventTag&, Functor, int, int, wxObject*) para más información.

Esta sobrecarga desvincula el método dado del evento.

Parámetros

eventType

El tipo de evento asociado con este manejador de eventos.

method

El método del manejador de eventos asociado con este evento.

handler

Objeto cuyo método fue llamado.

id

El primer ID del rango de identificadores asociado con el manejador de eventos.

lastId

El último ID del rango de identificadores asociado con el manejador de eventos.

userData

Datos asociados con la entrada de la tabla de eventos.

Desvincula este manejador de eventos de la cadena de la que forma parte (si existe); luego vincula el manejador de eventos "anterior" con el "siguiente" (para que la cadena no se interrumpa).

Por ejemplo, si antes de llamar a Unlink() se tiene la siguiente cadena:

entonces después de llamar a B->Unlink() se tendrá: