Edit

Funciones

Edit*	edit_create (void)
Edit*	edit_multiline (void)
void	edit_OnFilter (...)
void	edit_OnChange (...)
void	edit_OnFocus (...)
void	edit_text (...)
void	edit_font (...)
void	edit_align (...)
void	edit_passmode (...)
void	edit_editable (...)
void	edit_autoselect (...)
void	edit_select (...)
void	edit_tooltip (...)
void	edit_color (...)
void	edit_color_focus (...)
void	edit_bgcolor (...)
void	edit_bgcolor_focus (...)
void	edit_phtext (...)
void	edit_phcolor (...)
void	edit_phstyle (...)
void	edit_vpadding (...)
const char_t*	edit_get_text (...)
real32_t	edit_get_height (...)
void	edit_copy (...)
void	edit_cut (...)
void	edit_paste (...)

1. Filtrar textos
2. Selección del texto
3. Operaciones con el portapapeles

Los EditBox son pequeñas cajas de texto con capacidades de edición. Al igual que los Label son de formato uniforme: La tipografía y colores afectarán a la totalidad del texto (Figura 1). Suelen utilizarse para editar campos en formularios, normalmente restringidos a una sola línea, aunque también pueden extenderse a varias de ellas. Para editar textos con múltiples atributos utilizar TextView. En ¡Hola Edit y UpDown! tienes un ejemplo de uso.

Utiliza edit_create para crear una caja de edición.
Utiliza edit_multiline para crear una caja de edición multilínea.
Utiliza edit_passmode para ocultar el texto del control.
Utiliza edit_phtext para establecer un placeholder.

Ventana donde aparecen varias cajas de edición, a modo de formulario. — Figura 1: Cajas de edición en diferentes plataformas.

1. Filtrar textos

Utiliza edit_OnChange para validar el texto final.
Utiliza edit_OnFilter para detectar y corregir cada pulsación del usuario.

En función del valor que estemos editando, es posible que sea necesario validar el texto introducido. Esto podemos hacerlo al terminar de editar o mientras estamos escribiendo. Para el primer caso utilizaremos el evento edit_OnChange (Listado 1) que llamará al manejador justamente antes que el control pierda el foco del teclado (Figura 2). Si el texto no fuera válido, el manejador deberá devolver FALSE, impidiendo así que el foco cambie al siguiente control, permaneciendo en el editbox y obligando al usuario a corregirlo.

static void i_OnChange(App *app, Event *e)
{
    const EvText *p = event_params(e, EvText);
    if (is_valid_text(data, p->text) == FALSE)
    {
        // Force the focus remain in editbox
        bool_t *r = event_result(e, bool_t);
        *r = FALSE;
    }
}
...
edit_OnChange(edit, listener(NULL, i_OnChange, void));

Muestra el cambio del foco del teclado entre dos cajas de edición. — Figura 2: El evento *OnChange* se llama justamente antes de que el control pierda el foco.

Por ejemplo, en ¡Hola Edit y UpDown! activando el check Field validations se mostrará una ventana modal dentro del evento OnChange permitiendo validar o rechazar el texto (Figura 3).

Muestra un formulario donde se pregunta al usuario si los datos son válidos. — Figura 3: Validación de campos de texto mediante ventanas modales.

No será posible mover el foco del teclado a otro control mientras el texto no sea válido.

En caso que queramos implementar filtros más elaborados, que corrijan el texto mientras se escribe utilizaremos el evento edit_OnFilter. Recibiremos, a través de la estructura EvText, una copia del texto actual, la posición del cursor (caret) y el número de caracteres añadidos o eliminados. A partir de aquí, el filtro podrá validar el texto, poniendo a FALSE el campo apply de EvTextFilter. Si los nuevos caracteres no fueran apropiados, devolveremos el nuevo texto y posición del cursor en los campos text y cpos de EvTextFilter, poniendo apply a TRUE. Por ejemplo, en (Listado 2) tenemos un sencillo filtro que solo permite caracteres numéricos (Figura 4).

Muestra el evento tras pulsar una tecla en una caja de edición. — Figura 4: El evento *OnFilter* se llama tras cada pulsación de tecla.

Listado 2: Filtro que solo permite carácteres numéricos.

static void OnFilter(void *noused, Event *e)
{
    const EvText *params = event_params(e, EvText);
    EvTextFilter *result = event_result(e, EvTextFilter);
    uint32_t i = 0, j = 0;
    while (params->text[i] != '\0')
    {
        if (params->text[i] >= '0' && params->text[i] <= '9')
        {
            result->text[j] = params->text[i];
            j += 1;
        }

        i += 1;
    }

    result->text[j] = '\0';
    result->apply = TRUE;
}
...
edit_OnFilter(edit, listener(NULL, i_OnFilter, void));

2. Selección del texto

Utiliza edit_select para seleccionar texto.
Utiliza edit_autoselect para seleccionar automáticamente todo el texto cada vez que el control recibe el foco del teclado.

Es posible mediante código cambiar la selección del texto y la posición del cursor (caret), utilizando esta lógica.

Cuadro de edición con texto seleccionado. — Figura 5: Selección de texto (2, 6).

Si start == -1 y end == 0, se deselecciona todo el texto, dejando el caret en su posición actual.
Si start == -1 y end == -1, se deselecciona todo el texto, moviendo el caret al final del texto.
Si start == 0 y end == -1 se selecciona todo el texto, moviendo el caret al final del texto.
Si start > 0 y end == -1 se selecciona hasta el final, moviendo el caret al final del texto.
Si start == end se mueve el caret a la posición, deseleccionando todo el texto.

3. Operaciones con el portapapeles

El ser componentes nativos, los controles Edit soportan las operaciones típicas del portapapeles: Copiar, Pegar, Cortar, etc, así como sus atajos de teclado. No obstante, puede ser util acceder a estas operaciones desde el código del programa permitiendo, por ejemplo, que se copie al portapapeles el texto seleccionado en el control.

Utiliza edit_copy para copiar al portapapeles el texto seleccionado.
Utiliza edit_cut para cortar el texto seleccionado, copiándolo al portapapeles.
Utiliza edit_paste para pegar el texto del portapapeles en la posición del caret.

edit_create ()

Crea un control de edición de texto.

Edit*
edit_create(void);

Retorna

El edit.

edit_multiline ()

Crea un control de edición de texto que permite múltiples líneas.

Edit*
edit_multiline(void);

Retorna

El edit.

edit_OnFilter ()

Establece un manejador para filtrar el texto mientras se edita.

void
edit_OnFilter(Edit *edit,
              Listener *listener);

edit	El edit.
listener	Función callback que se llamará tras cada pulsación de tecla. En EvTextFilter de event_result se devolverá el texto filtrado.

Observaciones

Ver Filtrar textos y Eventos GUI.

edit_OnChange ()

Establece un manejador para detectar cuando el texto ha cambiado.

void
edit_OnChange(Edit *edit,
              Listener *listener);

edit	El edit.
listener	Función callback que se llamará cuando el control pierda el foco del teclado, lo que indicará el final de la edición.

Observaciones

Ver Filtrar textos y Eventos GUI.

edit_OnFocus ()

Establece un manejador para el foco del teclado.

void
edit_OnFocus(Edit *edit,
             Listener *listener);

edit	El edit.
listener	Función callback que se llamará cuando se reciba o se pierda el foco del teclado.

Observaciones

Ver Eventos GUI.

edit_text ()

Establece el texto del control de edición.

void
edit_text(Edit *edit,
          const char_t *text);

edit	El edit.
text	Cadena C UTF8 terminada en carácter nulo `'\0'`.

edit_font ()

Establece la fuente del control edit.

void
edit_font(Edit *edit,
          const Font *font);

edit	El edit.
font	Fuente tipográfica.

edit_align ()

Establece la alineación del texto.

void
edit_align(Edit *edit,
           const align_t align);

edit	El edit.
align	La alineación.

edit_passmode ()

Activa el modo contraseña, que ocultará los caracteres tecleados.

void
edit_passmode(Edit *edit,
              const bool_t passmode);

edit	El edit.
passmode	Activa o desactiva el modo contraseña.

edit_editable ()

Activa o desactiva la edición en el control.

void
edit_editable(Edit *edit,
              const bool_t is_editable);

edit	El edit.
is_editable	`TRUE` permitirá editar el texto (por defecto).

edit_autoselect ()

Activa o desactiva la autoselección del texto.

void
edit_autoselect(Edit *edit,
                const bool_t autoselect);

edit	El edit.
autoselect	`TRUE` el texto del control será totalmente seleccionado cuando reciba el foco. Por defecto es `FALSE`.

Observaciones

Ver Selección del texto.

edit_select ()

Selecciona texto.

void
edit_select(Edit *edit,
            const int32_t start,
            const int32_t end);

edit	El edit.
start	Posición del carácter inicial.
end	Posición del carácter final.

Observaciones

Ver Selección del texto.

edit_tooltip ()

Asigna un tooltip al control edit.

void
edit_tooltip(Edit *edit,
             const char_t *text);

edit	El edit.
text	Cadena C UTF8 terminada en carácter nulo `'\0'`.

edit_color ()

Establece el color del texto.

void
edit_color(Edit *edit,
           const color_t color);

edit	El edit.
color	El color del texto.

Observaciones

Los valores RGB puede que no sean del todo portables. Ver Colores.

edit_color_focus ()

Establece el color del texto, cuando el control tiene el foco del teclado.

void
edit_color_focus(Edit *edit,
                 const color_t color);

edit	El edit.
color	El color del texto.

Observaciones

Los valores RGB puede que no sean del todo portables. Ver Colores.

edit_bgcolor ()

Establece el color de fondo.

void
edit_bgcolor(Edit *edit,
             const color_t color);

edit	El edit.
color	El color de fondo.

Observaciones

Los valores RGB puede que no sean del todo portables. Ver Colores.

edit_bgcolor_focus ()

Establece el color de fondo, cuando el control tiene el foco del teclado.

void
edit_bgcolor_focus(Edit *edit,
                   const color_t color);

edit	El edit.
color	El color de fondo.

Observaciones

Los valores RGB puede que no sean del todo portables. Ver Colores.

edit_phtext ()

Establece un texto explicativo para cuando el control está en blanco (placeholder).

void
edit_phtext(Edit *edit,
            const char_t *text);

edit	El edit.
text	Cadena C UTF8 terminada en carácter nulo `'\0'`.

edit_phcolor ()

Establece el color del texto placeholder.

void
edit_phcolor(Edit *edit,
             const color_t color);

edit	El edit.
color	El color del texto.

Observaciones

Los valores RGB puede que no sean del todo portables. Ver Colores.

edit_phstyle ()

Establece el estilo de la fuente para el placeholder.

void
edit_phstyle(Edit *edit,
             const uint32_t fstyle);

edit	El edit.
fstyle	Combinación de valores de fstyle_t.

edit_vpadding ()

Establece el margen vertical interior.

void
edit_vpadding(Edit *edit,
              const real32_t padding);

edit	El edit.
padding	Si `0` no habrá margen entre el texto y el borde del control. Si `<0` se establecerá el margen por defecto.

edit_get_text ()

Obtiene el texto del control.

const char_t*
edit_get_text(const Edit *edit);

edit

El edit.

Retorna

Cadena C UTF8 terminada en carácter nulo '\0'.

edit_get_height ()

Obtiene la altura actual del control.

real32_t
edit_get_height(const Edit *edit);

edit

El edit.

Retorna

La altura del control, que cambiará en función del tamaño de letra y el vpadding.

edit_copy ()

Copia al portapapeles el texto seleccionado.

void
edit_copy(const Edit *edit);

edit

El edit.

Observaciones

Ver Operaciones con el portapapeles.

edit_cut ()

Corta el texto seleccionado, copiándolo al portapapeles.

void
edit_cut(Edit *edit);

edit

El edit.

Observaciones

Ver Operaciones con el portapapeles.

edit_paste ()

Pega el texto del portapapeles en la posición del caret.

void
edit_paste(Edit *edit);

edit

El edit.

Observaciones

Ver Operaciones con el portapapeles.