SDK Multiplataforma en C logo

SDK Multiplataforma en C

TextView

❮ Anterior
Siguiente ❯

Cabecera

#include <gui/textview.h>


Funciones

TextView*textview_create (void)
voidtextview_OnFilter (...)
voidtextview_OnFocus (...)
voidtextview_size (...)
voidtextview_clear (...)
uint32_ttextview_printf (...)
voidtextview_writef (...)
uint32_ttextview_cpos_printf (...)
voidtextview_cpos_writef (...)
voidtextview_rtf (...)
voidtextview_units (...)
voidtextview_family (...)
voidtextview_fsize (...)
voidtextview_fstyle (...)
voidtextview_color (...)
voidtextview_bgcolor (...)
voidtextview_pgcolor (...)
voidtextview_halign (...)
voidtextview_lspacing (...)
voidtextview_bfspace (...)
voidtextview_afspace (...)
voidtextview_apply_all (...)
voidtextview_apply_select (...)
voidtextview_scroll_visible (...)
voidtextview_editable (...)
voidtextview_select (...)
voidtextview_show_select (...)
voidtextview_del_select (...)
voidtextview_scroll_caret (...)
const char_t*textview_get_text (...)
voidtextview_copy (...)
voidtextview_cut (...)
voidtextview_paste (...)
voidtextview_wrap (...)

Los TextView son vistas diseñadas para trabajar con bloques de texto enriquecido, donde pueden combinarse tipografías, tamaños y colores (Figura 1). El texto se puede editar directamente o mediante código utilizando las funciones que proporciona el SDK. En ¡Hola TextView! tienes un ejemplo de uso.


1. Formato de carácter

Una de las ventajas del texto enriquecido con respecto al texto plano, es la posibilidad de combinar diferentes formatos de carácter dentro del mismo párrafo (Figura 2).

Utiliza textview_family para establecer la tipografía.

Utiliza textview_fsize para establecer el tamaño del carácter.

Utiliza textview_fstyle para establecer el estilo.

Utiliza textview_color para establecer el color del texto.

Utiliza textview_bgcolor para establecer el color de fondo del texto.

Selección de tipografías y atributos de texto.
Figura 2: Controles típicos del formato de carácter.

2. Formato de párrafo

Se pueden establecer también atributos por párrafo (Figura 3). El carácter nueva línea '\n' se considera cierre o final del párrafo.

Utiliza textview_halign para establecer a alineación del párrafo.

Utiliza textview_lspacing para establecer la separación entre líneas (interlineado).

Utiliza textview_bfspace para indicar el espacio vertical antes del párrafo.

Utiliza textview_afspace para indicar el espacio vertical después del párrafo.

Formateo de un párrafo de texto.
Figura 3: Controles típicos del formato de párrafo.

3. Formato del documento

Por último disponemos de varios atributos que afectan a la totalidad del documento o del control.

Utiliza textview_units para establecer la unidades del texto.

Utiliza textview_pgcolor para establecer el color del fondo del control (página).


4. Aplicar formato

Las funciones de formato que acabamos de presentar no modifican, por si solas, la apariencia del texto existente en el control. Establecen las propiedades por defecto que serán aplicadas a continuación, según los siguientes criterios. En ¡Hola TextEditor! tienes un ejemplo de uso (Figura 4).

  • Utiliza textview_apply_all para aplicar los atributos a todo el texto.
  • Utiliza textview_apply_select para aplicar los atributos al texto seleccionado. Si no hay texto seleccionado, se establecerán para el nuevo texto insertado en la posición del cursor.
  • Cuando utilicemos textview_printf o textview_writef, el texto se añadirá al final del control, utilizando los atributos por defecto establecidos. De esta forma podremos componer textos de forma secuencial, alterando los atributos a aplicar a cada nueva cadena.
  • Cuando utilicemos textview_cpos_printf o textview_cpos_writef, el formato será el del carácter anterior a la posición actual del cursor (no el formato por defecto).
  • De la misma forma, cuando el usuario edita el texto directamente, el formato será el del carácter anterior a la posición actual del cursor. Excepto cuando se escribe el primer carácter, que tomará el formato del siguiente (si hay alguno) o el formato por defecto.
  • Animación que muestra como se aplica el formato del carácter dentro de un TextView.
    Figura 4: Aplicar el formato del texto.

5. Filtrar texto insertado

Cada vez que el usuario inserte nuevo texto en el control, mediante pulsaciones u operaciones del portapapeles, se enviará un evento que podemos capturar si es necesario. En ¡Hola TextSel y Clipboard! tienes un ejemplo. Recibiremos, a través de la estructura EvText, una copia del texto insertado (EvText::text), la posición del cursor (EvText::cpos) y el número de caracteres añadidos (EvText::len). A partir de aquí, si el texto debe modificarse, debemos obtener la estructura resultado EvTextFilter, poniendo a TRUE su campo apply. En EvTextFilter::text deberemos copiar el nuevo texto y, en EvTextFilter::cpos, la nueva posición del cursor.


6. Seleccionar texto

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

  • 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.

7. Portapapeles

  • Utiliza textview_copy para copiar al portapapeles el texto seleccionado.
  • Utiliza textview_cut para cortar el texto seleccionado, copiándolo al portapapeles.
  • Utiliza textview_paste para pegar el texto del portapapeles en la posición del caret.

8. Ajuste del texto

  • Utiliza textview_wrap para activar/desactivar el ajuste del texto.

Por defecto, el control ajusta automáticamente la anchura del texto, cortando las líneas cuando sea necesario. Esto se puede evitar pasando wrap=FALSE, donde cada línea ocupará su ancho natural y aparecerá una barra de scroll horizontal para poder desplazar el texto (Figura 5).

Control TextView activando y desactivando el ajuste del texto.
Figura 5: Ajuste del texto. Animación en https://nappgui.com/img/gui/textview_wrap.gif.
❮ Anterior
Siguiente ❯

textview_create ()

Crea una vista de texto.

TextView*
textview_create(void);

Retorna

La vista de texto.


textview_OnFilter ()

Establece un manejador para filtrar el texto mientras se edita.

void
textview_OnFilter(TextView *view,
                  Listener *listener);
view

La vista.

listener

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

Observaciones

Funciona de la misma forma que en controles Edit. Ver Filtrar texto insertado y Eventos GUI.


textview_OnFocus ()

Establece un manejador para el foco del teclado.

void
textview_OnFocus(TextView *view,
                 Listener *listener);
view

La vista.

listener

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

Observaciones

Ver Eventos GUI.


textview_size ()

Establece el tamaño por defecto de la vista.

void
textview_size(TextView *view,
              const S2Df size);
view

La vista.

size

El tamaño.

Observaciones

Corresponde al Dimensionado natural del control. Por defecto 245x144.


textview_clear ()

Borra todo el contenido de la vista.

void
textview_clear(TextView *view);
view

La vista.


textview_printf ()

Añade texto al final utilizando el formato del printf.

uint32_t
textview_printf(TextView *view,
                const char_t *format,
                ...);
1
textview_printf(view, Code: %-10s Price %5.2f\n", code, price);
view

La vista.

format

Cadena con el formato tipo-printf con un número variable de parámetros.

...

Argumentos o variables del printf.

Retorna

El número de bytes escritos.

Observaciones

El nuevo texto se añadirá al final del control. Si hay texto seleccionado, se deseleccionará, pero no se borrará. El cursor quedará al final del texto.


textview_writef ()

Añade texto al final.

void
textview_writef(TextView *view,
                const char_t *str);
view

La vista.

str

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

Observaciones

El nuevo texto se añadirá al final del control. Si hay texto seleccionado, se deseleccionará, pero no se borrará. El cursor quedará al final del texto.


textview_cpos_printf ()

Inserta texto en la posición del cursor utilizando el formato del printf.

uint32_t
textview_cpos_printf(TextView *view,
                     const char_t *format,
                     ...);
1
textview_cpos_printf(view, Code: %-10s Price %5.2f\n", code, price);
view

La vista.

format

Cadena con el formato tipo-printf con un número variable de parámetros.

...

Argumentos o variables del printf.

Retorna

El número de bytes escritos.

Observaciones

El nuevo texto se insertará en la posición actual del cursor. Si hay texto seleccionado, será eliminado (reemplazado) por el nuevo. El cursor quedará justamente después del texto insertado.


textview_cpos_writef ()

Inserta texto en la posición del cursor.

void
textview_cpos_writef(TextView *view,
                     const char_t *str);
view

La vista.

str

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

Observaciones

El nuevo texto se insertará en la posición actual del cursor. Si hay texto seleccionado, será eliminado (reemplazado) por el nuevo. El cursor quedará justamente después del texto insertado.


textview_rtf ()

Inserta texto en el formato RTF de Microsoft.

void
textview_rtf(TextView *view,
             Stream *rtf_in);
view

La vista.

rtf_in

Stream de lectura con el contenido RTF.


textview_units ()

Establece las unidades del texto.

void
textview_units(TextView *view,
               const uint32_t units);
view

La vista.

units

Unidades ekFPIXELS ó ekFPOINTS.

Observaciones

ekFPOINTS es el valor por defecto y el utilizado normalmente por los procesadores de texto. Ver Tamaño en puntos y Formato del documento.


textview_family ()

Establece la familia tipográfica del texto ("Arial", "Times New Roman", "Helvetica", etc).

void
textview_family(TextView *view,
                const char_t *family);
view

La vista.

family

La familia tipográfica.

Observaciones

No todas las familias estarán presentes en todas las plataformas. Utiliza font_exists_family o font_installed_families para comprobarlo. Ver Formato de carácter.


textview_fsize ()

Establece el tamaño del texto.

void
textview_fsize(TextView *view,
               const real32_t size);
view

La vista.

size

El tamaño.

Observaciones

El valor está condicionado a las unidades establecidas en textview_units. Ver Formato de carácter.


textview_fstyle ()

Establece el estilo del texto.

void
textview_fstyle(TextView *view,
                const uint32_t fstyle);
view

La vista.

fstyle

Combinación de ekFBOLD, ekFITALIC, ekFSTRIKEOUT, ekFUNDERLINE ekFSUBSCRIPT, ekFSUPSCRIPT. Para anular cualquier estilo previo utiliza ekFNORMAL.

Observaciones

Ver Formato de carácter.


textview_color ()

Establece el color del texto.

void
textview_color(TextView *view,
               const color_t color);
view

La vista.

color

El color. Utiliza kCOLOR_DEFAULT para restablecer el color por defecto.

Observaciones

Ver Formato de carácter.


textview_bgcolor ()

Establece el color de fondo del texto.

void
textview_bgcolor(TextView *view,
                 const color_t color);
view

La vista.

color

El color. Utiliza kCOLOR_DEFAULT para restablecer el color por defecto.

Observaciones

Ver Formato de carácter.


textview_pgcolor ()

Establece el color de fondo del control.

void
textview_pgcolor(TextView *view,
                 const color_t color);
view

La vista.

color

El color. Utiliza kCOLOR_DEFAULT para restablecer el color por defecto.

Observaciones

Ver Formato del documento.


textview_halign ()

Establece la alineación del texto en un párrafo.

void
textview_halign(TextView *view,
                const align_t align);
view

La vista.

align

La alineación. Por defecto ekLEFT.

Observaciones

Ver Formato de párrafo.


textview_lspacing ()

Establece el espaciado inter-lineal del párrafo.

void
textview_lspacing(TextView *view,
                  const real32_t scale);
view

La vista.

scale

Factor de escala en la altura de la fuente. 1 es el valor por defecto, 2 el doble de dicha altura, 3 el triple, etc. Valores intermedios también son válidos (pe. 1.25).

Observaciones

Ver Formato de párrafo.


textview_bfspace ()

Establece un espacio vertical antes del párrafo.

void
textview_bfspace(TextView *view,
                 const real32_t space);
view

La vista.

space

El espacio en las unidades preestablecidas.

Observaciones

Ver Formato de párrafo.


textview_afspace ()

Establece un espacio vertical después del párrafo.

void
textview_afspace(TextView *view,
                 const real32_t space);
view

La vista.

space

El espacio en las unidades preestablecidas.

Observaciones

Ver Formato de párrafo.


textview_apply_all ()

Aplica los atributos de carácter y párrafo a todo el texto del control. En caso de no existir texto, se tomarán como los atributos por defecto del texto que se añada mediante el teclado.

void
textview_apply_all(TextView *view);
1
2
3
4
5
textview_family(view, "Arial");
textview_fsize(view, 16);
textview_color(view, kCOLOR_RED);
// Arial:16:Red to all text or default
textview_apply_all(view);
view

La vista.

Observaciones

Ver Aplicar formato.


textview_apply_select ()

Aplica los atributos de carácter y párrafo al texto seleccionado.

void
textview_apply_select(TextView *view);
view

La vista.

Observaciones

Ver Aplicar formato.


textview_scroll_visible ()

Muestra u oculta las barras de scroll.

void
textview_scroll_visible(TextView *view,
                        const bool_t horizontal,
                        const bool_t vertical);
view

La vista.

horizontal

Barra horizontal.

vertical

Barra vertical.


textview_editable ()

Establece si el texto del control es o no editable.

void
textview_editable(TextView *view,
                  const bool_t is_editable);
view

La vista.

is_editable

TRUE permitirá editar el texto. Por defecto FALSE.


textview_select ()

Selecciona texto.

void
textview_select(TextView *view,
                const int32_t start,
                const int32_t end);
view

La vista.

start

Posición del carácter inicial.

end

Posición del carácter final.

Observaciones

Ver Seleccionar texto.


textview_show_select ()

Establece si se muestra u oculta la selección del texto al perder el foco del teclado.

void
textview_show_select(TextView *view,
                     const bool_t show);
view

La vista.

show

Muestra u oculta. Por defecto FALSE.

Observaciones

Al perder el foco del teclado, el control mantendrá la selección del texto. Esta función solo afecta a la visibilidad de la selección.


textview_del_select ()

Elimina el texto seleccionado.

void
textview_del_select(TextView *view);
view

La vista.

Observaciones

Tiene un efecto similar a textview_cut, pero sin copiar el texto eliminado en el portapapeles. Ver Seleccionar texto.


textview_scroll_caret ()

En textos que exceden la parte visible, realiza un scroll hasta la posición del caret.

void
textview_scroll_caret(TextView *view);
view

La vista.


textview_get_text ()

Obtiene el texto del control.

const char_t*
textview_get_text(const TextView *view);
view

La vista.

Retorna

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


textview_copy ()

Copia al portapapeles el texto seleccionado.

void
textview_copy(const TextView *view);
view

La vista.

Observaciones

Funciona de la misma forma que en controles Edit. Ver Portapapeles.


textview_cut ()

Corta el texto seleccionado, copiándolo al portapapeles.

void
textview_cut(TextView *view);
view

La vista.

Observaciones

Funciona de la misma forma que en controles Edit. Ver Portapapeles.


textview_paste ()

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

void
textview_paste(TextView *view);
view

La vista.

Observaciones

Funciona de la misma forma que en controles Edit. Ver Portapapeles.


textview_wrap ()

Activa o desactiva el ajuste automático del texto.

void
textview_wrap(TextView *view,
              const bool_t wrap);
view

La vista.

wrap

Activa o desactiva. Por defecto TRUE.

Observaciones

Ver Ajuste del texto.

❮ Anterior
Siguiente ❯