Clase wxKeyEvent

Esta clase de eventos contiene información sobre eventos de pulsación y liberación de teclas.

Jerarquía:

La información principal de este evento es la tecla que se pulsa o suelta. Se puede acceder a ella utilizando una de las funciones GetUnicodeKey(), GetKeyCode() o GetRawKeyCode(). Para los caracteres imprimibles, debería utilizarse GetUnicodeKey() ya que funciona para cualquier tecla, incluyendo caracteres no latinos-1 que pueden introducirse cuando se utilizan distribuciones de teclado nacionales. GetKeyCode() debería usarse para manejar caracteres especiales (como las teclas de flechas del cursor o HOME o INS y así sucesivamente) que corresponden a elementos del enumerado wxKeyCode por encima de la constante WXK_START. Aunque GetKeyCode() también devuelve el código de carácter para teclas Latin-1 por compatibilidad, no funciona para caracteres Unicode en general y devolverá WXK_NONE para cualquiera que no sea Latin-1. Si tanto GetUnicodeKey() como GetKeyCode() devuelven WXK_NONE entonces la clave no tiene asignación WXK_xxx y GetRawKeyCode() puede utilizarse para distinguir entre claves, pero los códigos de clave sin procesar son específicos de la plataforma. Por estas razones, se recomienda usar siempre GetUnicodeKey() y solo volver a GetKeyCode() si GetUnicodeKey() devuelve WXK_NONE, lo que significa que el evento corresponde a una clave especial no imprimible, y entonces opcionalmente comprobar GetRawKeyCode() si GetKeyCode() también devuelve WXK_NONE o simplemente ignorar esa clave.

Aunque estas tres funciones pueden utilizarse con los eventos de tipo wxEVT_KEY_DOWN, wxEVT_KEY_UP y wxEVT_CHAR, los valores devueltos por ellas son diferentes para los dos primeros eventos y para el último. Para este último, la tecla devuelta corresponde al carácter que aparecería, por ejemplo, en una zona de texto si el usuario pulsara la tecla en ella. Como tal, su valor depende del estado actual de la tecla Mayúsculas y, para las letras, del estado del modificador Bloq Mayús. Por ejemplo, si se pulsa la tecla A sin mantener pulsada la tecla Mayúsculas, el evento wxKeyEvent de tipo wxEVT_CHAR generado para esta pulsación devolverá (ya sea desde GetKeyCode() o GetUnicodeKey() ya que sus significados coinciden para caracteres ASCII) el código de tecla 97 correspondiente al valor ASCII de a. Y si se pulsa la misma tecla pero manteniendo pulsada la tecla Mayúsculas (o estando activo el Bloqueo de Mayúsculas), entonces la tecla podría ser 65, es decir, el valor ASCII de A mayúscula.

Sin embargo, para los eventos de tecla abajo y tecla arriba, el código de tecla devuelto será A independientemente del estado de las teclas modificadoras, es decir, depende solo de la tecla física que se pulsa y no se traduce a su representación lógica utilizando el estado actual del teclado. Estos códigos de tecla no traducidos se definen como sigue:

• Para las letras, corresponden al valor en mayúsculas de la letra.
• Para las demás teclas alfanuméricas (por ejemplo, 7 o +), el código de tecla sin traducir corresponde al carácter producido por la tecla cuando se pulsa sin Mayúsculas. Por ejemplo, en la distribución de teclado estándar de EE.UU., el código sin traducir de la tecla =/+ en la esquina superior derecha del teclado es 61, que es el valor ASCII de =.
• Para el resto de las teclas (es decir, las teclas especiales no imprimibles) es el mismo que el código de tecla normal, ya que no se utiliza ninguna traducción de todos modos.

Obsérvese que la primera regla se aplica a todas las letras Unicode, no solo a las habituales Latin-1. Sin embargo, para las letras no-Latin-1 solo se puede utilizar GetUnicodeKey() para recuperar el código de la clave, ya que GetKeyCode() solo devuelve WXK_NONE en este caso.

Además, hay que tener en cuenta que los eventos wxEVT_CHAR no se generan para claves que no tienen un mapeado wxWidgets, por lo que GetRawKeyCode() nunca debería ser necesaria para este evento.

Resumiendo: se debería manejar wxEVT_CHAR si se necesita la tecla traducida y wxEVT_KEY_DOWN si solo necesita el valor de la tecla en sí, independientemente del estado actual del teclado.

Nota: No todos los eventos de pulsación de tecla pueden ser generados por el usuario. Por ejemplo, wxEVT_KEY_DOWN con código de tecla = puede ser generado usando la distribución de teclado estándar de EE.UU. pero no usando la alemana porque la tecla = corresponde a la combinación de teclas Shift-0 en esta distribución y el código de tecla para ella es 0, no =. Debido a esto se debería evitar requerir a tus usuarios que escriban eventos de tecla que podrían ser imposibles de introducir en su teclado.

Otra diferencia entre los eventos key y char es que para estos últimos se realiza otro tipo de traducción cuando se pulsa la tecla Control: los eventos char para letras ASCII en este caso llevan códigos correspondientes al valor ASCII de Ctrl-Latter, es decir, 1 para Ctrl-A, 2 para Ctrl-B y así sucesivamente hasta 26 para Ctrl-Z. Esto es conveniente para aplicaciones tipo terminal y puede ser completamente ignorado por todas las demás (si se necesita manejar Ctrl-A es probablemente una mejor idea usar el evento key en lugar del char). Hay que tener en cuenta que actualmente no se realiza ninguna traducción para las pulsaciones de las teclas [, \, ], ^ y _ que podrían ser mapeadas a valores ASCII del 27 al 31. Desde la versión 2.9.2, los valores enum WXK_CONTROL_A - WXK_CONTROL_Z pueden utilizarse en lugar de los valores constantes no descriptivos 1-26.

Por último, las teclas modificadoras solo generan eventos de tecla, pero ningún evento char. Las teclas modificadoras son WXK_SHIFT, WXK_CONTROL, WXK_ALT y varias WXK_WINDOWS_XXX del enumerado wxKeyCode.

Los eventos de teclas modificadoras son especiales en un aspecto adicional: normalmente el estado del teclado asociado a la pulsación de una tecla está bien definido, por ejemplo wxKeyboardState::ShiftDown() devuelve true solo si la tecla Shift se mantuvo pulsada cuando se pulsó la tecla que generó este evento. Sin embargo, existe una ambigüedad para los eventos de pulsación de la propia tecla Shift. Por convención, se considera que ya está pulsada cuando se pulsa y que ya está liberada cuando se libera. En otras palabras, el evento wxEVT_KEY_DOWN para la propia tecla Shift tendrá wxMOD_SHIFT en GetModifiers() y ShiftDown() devolverá true mientras que el evento wxEVT_KEY_UP para la propia Shift no tendrá wxMOD_SHIFT en sus modificadores y ShiftDown() devolverá false.

Sugerencia: Se puede descubrir los códigos de tecla y modificadores generados por todas las teclas de su sistema de forma interactiva ejecutando el ejemplo Key Event Sample wxWidgets y pulsando algunas teclas en él.

Nota: Si un evento de tecla pulsada (EVT_KEY_DOWN) es capturado y el manejador del evento no llama a event.Skip() entonces el evento char correspondiente (EVT_CHAR) no ocurrirá. Esto es por diseño y permite a los programas que manejan ambos tipos de eventos evitar procesar la misma tecla dos veces. Como consecuencia, si no se quiere suprimir los eventos wxEVT_CHAR para las teclas que se manejan, llamar siempre a event.Skip() en el manejador wxEVT_KEY_DOWN. No hacerlo también puede impedir que funcionen los aceleradores definidos utilizando esta tecla. Si una tecla se mantiene pulsada, normalmente obtendrá muchos eventos de pulsación (generados automáticamente) pero solo uno de suelta al final cuando la tecla se suelta, por lo que es erróneo asumir que hay un evento de subida correspondiente a cada evento de bajada.
Para programadores de Windows: Los eventos de tecla y char en wxWidgets son similares pero ligeramente diferentes de los eventos WM_KEYDOWN y WM_CHAR de Windows. En particular, la combinación Alt-x generará un evento char en wxWidgets (a menos que se use como acelerador) y casi todas las teclas, incluyendo las que no tienen equivalentes ASCII, generan también eventos char.

Eventos que utilizan esta clase

Las siguientes macros manejadoras de eventos redirigen los eventos a manejadores de funciones miembro 'func' con prototipos como:

void handlerFuncName(wxKeyEvent& event)

Macros de eventos:

EVT_KEY_DOWN(func)

Procesa un evento wxEVT_KEY_DOWN (se ha pulsado cualquier tecla). Si este evento se procesa y no se salta, wxEVT_CHAR no se generará en absoluto para esta pulsación de tecla (pero wxEVT_KEY_UP sí).

EVT_KEY_UP(func)

Procesa un evento wxEVT_KEY_UP (cualquier tecla ha sido liberada).

EVT_CHAR(func)

Procesa un evento wxEVT_CHAR.

EVT_CHAR_HOOK(func)

Procesa un evento wxEVT_CHAR_HOOK. A diferencia del resto de eventos de teclado, este evento se propaga hacia arriba en la jerarquía de ventanas, lo que permite interceptarlo en la ventana padre de la ventana enfocada a la que se envía inicialmente (si no hay ventana enfocada, este evento se envía al objeto global wxApp). También se genera antes que cualquier otro evento de teclado y por lo tanto da a la ventana padre la oportunidad de modificar el manejo del teclado de sus hijos, por ejemplo, es utilizado internamente por wxWidgets en algunos ports para interceptar la pulsación de la tecla Esc en cualquier hijo de un diálogo para cerrar el propio diálogo cuando se pulsa. Por defecto, si se maneja este evento, es decir, si el manejador no llama a wxEvent::Skip(), no se generarán los eventos wxEVT_KEY_DOWN ni wxEVT_CHAR (aunque sí wxEVT_KEY_UP), es decir, sustituye a los eventos de tecla normales. Sin embargo, llamando al método especial DoAllowNextEvent() se puede manejar wxEVT_CHAR_HOOK y seguir permitiendo la generación de eventos normales. Esto es algo que raramente es útil pero puede ser necesario si se necesita evitar que un manejador padre wxEVT_CHAR_HOOK se ejecute sin suprimir los eventos normales de tecla. Finalmente obsérvese que este evento no se genera cuando se captura el ratón ya que se considera que la ventana que tiene la captura debe recibir también todos los eventos de teclado sin permitir que su padre wxTopLevelWindow interfiera en su procesamiento.

Funciones miembro

wxKeyEvent()

DoAllowNextEvent()

GetKeyCode()

void MyHandler::OnChar(wxKeyEvent& event)
{
    wxChar uc = event.GetUnicodeKey();
    if ( uc != WXK_NONE )
    {
        // Es un carácter "normal". Hay que tener en cuenta que esto 
        // incluye caracteres de control en el rango 1..31, por ejemplo 
        // WXK_RETURN o WXK_BACK, así que hay que comprobarlos
        // explícitamente.
        if ( uc >= 32 )
        {
            wxLogMessage("Se ha presionado '%c'", uc);
        }
        else
        {
            // Es un carácter de control
            ...
        }
    }
    else // Sin equivalente Unicode.
    {
        // Es una llave especial, tratar con todas las conocidas:
        switch ( event.GetKeyCode() )
        {
            case WXK_LEFT:
            case WXK_RIGHT:
                ... mover el cursor ...
                break;
 
            case WXK_F1:
                ... obtener ayuda ...
                break;
        }
    }
}

GetPosition()

GetPosition()

GetRawKeyCode()

GetRawKeyFlags()

GetUnicodeKey()

GetX()

GetY()

IsAutoRepeat()

IsKeyInCategory()

IsNextEventAllowed()

Métodos y datos heredados

Esta clase hereda los métodos y datos miembro públicos y protegidos de wxObject, wxEvent y wxKeyboardState.