SDK Multiplataforma en C logo

SDK Multiplataforma en C

Gui

❮ Anterior
Siguiente ❯

Funciones

voidgui_start (void)
voidgui_finish (void)
voidgui_respack (...)
voidgui_language (...)
const char_t*gui_text (...)
const Image*gui_image (...)
const byte_t*gui_file (...)
voidgui_OnThemeChanged (...)

Tipos y Constantes

enumorient_t
enumstate_t
enummouse_t
enumcursor_t
enumclose_t
enumscale_t
enumview_flag_t
enumwindow_flag_t
enumevent_t
structControl
structLabel
structButton
structPopUp
structEdit
structCombo
structListBox
structUpDown
structSlider
structProgress
structView
structTextView
structImageView
structTableView
structSplitView
structLayout
structCell
structPanel
structWindow
structMenu
structMenuItem
structEvButton
structEvSlider
structEvText
structEvTextFilter
structEvDraw
structEvMouse
structEvWheel
structEvKey
structEvPos
structEvSize
structEvWinClose
structEvMenu

La librería Gui permite crear interfaces gráficas de usuario de forma sencilla e intuitiva. Solo está disponible para aplicaciones de escritorio por razones obvias (Figura 1), al contrario que el resto de librerías que pueden utilizarse también en aplicaciones por línea de comandos.

Árbol de dependencias de la librería gui.
Figura 1: Dependencias de Gui. Ver Referencia del SDK.

Al igual que Draw2D y Osbs Gui se apoya en las APIs de cada sistema operativo (Figura 2). Además de las ventajas ya comentadas en estos dos casos, el acceso nativo a elementos de interfaz provocará que nuestros programas estén totalmente integrados en el escritorio y acordes al tema visual presente en cada máquina (Figura 3).

Dependencias de gui en función de cada sistema operativo.
Figura 2: Gui conecta con las APIs de interfaz de cada sistema operativo.
Imagen de un mismo programa corriendo en Windows, macOS y Linux.
Figura 3: Las interfaces creadas con Gui se adaptarán al estilo de cada entorno de ventanas.

1. Composición declarativa

La librería Gui se aleja del concepto de tratar las ventanas (o cuadros de diálogo) como un recurso externo del programa. Por el contrario, estas se crean directamente desde el código fuente evitando maquetarlas mediante editores visuales (Figura 4). Debemos tener en cuenta que los gestores de ventanas utilizan diferentes tipografías y temas, por lo que especificar posiciones y tamaños concretos para los elementos no será del todo portable (Figura 5). Por el contrario, en Gui los controles se ubican en una rejilla virtual denominada Layout, que los dimensionará en tiempo de ejecución en función de cada máquina concreta (Figura 6).

Captura del editor de interfaces incluido en Xcode.
Figura 4: Los editores de recursos no son buenos aliados para crear complejas interfaces dinámicas. Menos aún si queremos portarlas entre plataformas.
Controles Label y Button en Windows, macOS y Linux.
Figura 5: Utilizar medidas fijas para los controles no se adaptará bien al migrar el programa.
Controles Label y Button en Windows, macOS y Linux.
Figura 6: El Layout calcula la posición y tamaño de los componentes en tiempo de ejecución.

Además, otro hecho relevante es que las interfaces son objetos vivos sujetos a cambios constantes. Un claro ejemplo son las traducciones, que alteran la ubicación de los elementos debido a la nueva dimensión del texto (Figura 7). Gui se adaptará a estos eventos de forma automática, recalculando posiciones para mantener una maquetación coherente.

Traducción de una aplicación en tiempo de ejecución.
Figura 7: Las ventanas se adaptan automáticamente a cambios en tiempo de ejecución.

2. Anatomía de una ventana.

En (Figura 8) tenemos las partes principales de una ventana. Los controles son los elementos finales con los que interactúa el usuario para introducir datos o lanzar acciones. Las vistas son regiones rectangulares de tamaño relativamente grande donde se representa información mediante texto y gráficos, pudiendo responder a los eventos de teclado o ratón. Por último, todos estos elementos se agruparán en paneles y se maquetarán mediante layouts.

Ventana de interfaz donde se resaltan las partes más importantes.
Figura 8: Partes destacables en una ventana de interfaz.
  • Label. Pequeños bloques de texto descriptivo.
  • Button. Botones de pulsación, casillas de verificación o botones de radio.
  • PopUp. Botón con lista desplegable.
  • Edit. Cuadro de edición de texto.
  • Combo. Cuadro de edición con lista desplegable.
  • ListBox. Cuadro de lista.
  • UpDown. Botones de incremento y decremento.
  • Slider. Barra deslizadora.
  • Progress. Barra de progreso.
  • View. Vista genérica donde se puede dibujar libremente y capturar los eventos del usuario. Útil para crear controles personalizados.
  • TextView. Vista para mostrar y editar textos, permitiendo combinar formatos.
  • ImageView. Vista para mostrar imágenes.
  • TableView. Vista a modo de tabla para mostrar información tabulada en filas y columnas.
  • SplitView. Vista dividida en dos partes que permite, mediante un deslizador, repartir el área total entre ambas zonas.
  • Layout. Rejilla virtual e invisible que divide el espacio del panel en celdas donde ubicaremos los diferentes controles y vistas.
  • Panel. Sub-ventana vinculada a la ventana principal, sin marco ni borde, donde pueden agruparse diferentes controles.
  • Window. Ventana principal con barra de título y marco.
  • Menu. Lista de opciones. Dependiendo del sistema forman parte de la ventana (Windows, Ubuntu) o se muestran directamente en el escritorio (macOS).
  • MenuItem. Cada uno de los elementos del menú.

3. Eventos GUI

Las aplicaciones de escritorio están dirigidas por eventos, lo que significa que están continuamente esperando a que el usuario realice alguna acción sobre la interfaz: Pulsar un botón, arrastrar un slider, escribir un texto, etc. Cuando esto ocurre, el gestor de ventanas detecta el evento y lo notifica a la aplicación (Figura 9), la cual debe proveer un manejador del evento con el código a ejecutar. Por ejemplo, en (Listado 1) definimos un manejador para responder a la pulsación de un botón. Evidentemente, si no hay manejador asociado, la aplicación ignorará el evento.


enum orient_t

Orientación.

enum orient_t
{
    ekHORIZONTAL,
    ekVERTICAL
};
ekHORIZONTAL

Horizontal.

ekVERTICAL

Vertical.


enum state_t

Valores de estado.

enum state_t
{
    ekOFF,
    ekON,
    ekMIXED
};
ekOFF

Apagado/desactivado.

ekON

Encendido/activado.

ekMIXED

Medio/indeterminado.


enum mouse_t

Botones del ratón.

enum mouse_t
{
    ekMLEFT,
    ekMRIGHT,
    ekMMIDDLE
};
ekMLEFT

Izquierdo.

ekMRIGHT

Derecho.

ekMMIDDLE

Centro.


enum cursor_t

Cursores. Ver window_cursor.

enum cursor_t
{
    ekCARROW,
    ekCHAND,
    ekCIBEAM,
    ekCCROSS,
    ekCSIZEWE,
    ekCSIZENS,
    ekCUSER
};
ekCARROW

Flecha (por defecto).

ekCHAND

Mano.

ekCIBEAM

Barra vertical (edición de texto).

ekCCROSS

Cruz.

ekCSIZEWE

Redimensionado horizontal (izquierda-derecha).

ekCSIZENS

Redimensionado vertical (arriba-abajo).

ekCUSER

Creado a partir de una imagen.


enum close_t

Motivo del cierre de una ventana.

enum close_t
{
    ekCLESC,
    ekCLINTRO,
    ekCLBUTTON,
    ekCLDEACT
};
ekCLESC

Se ha pulsado la tecla [ESC] (cancelar).

ekCLINTRO

Se ha pulsado la tecla [INTRO] (aceptar).

ekCLBUTTON

Se ha pulsado el botón de cerrar [X] en la barra de título.

ekCLDEACT

Se ha ocultado la ventana padre.


enum scale_t

Formas de escalado.

enum scale_t
{
    ekAUTO,
    ekSNONE,
    ekASPECT,
    ekASPECTDW
};
ekAUTO

Escalado automático, la proporción puede cambiar.

ekSNONE

Sin escalado.

ekASPECT

Escalado automático, pero manteniendo la proporción (aspect ratio).

ekASPECTDW

Igual que el anterior, pero no aumenta el tamaño original, solo lo reduce si procede.


enum view_flag_t

Atributos de creación de una vista personalizada.

enum view_flag_t
{
    ekHSCROLL,
    ekVSCROLL
};
ekHSCROLL

Barra de scroll horizontal.

ekVSCROLL

Barra de scroll vertical.


enum window_flag_t

Atributos de creación de una ventana.

enum window_flag_t
{
    ekWNFLAG,
    ekWNEDGE,
    ekWNTITLE,
    ekWNMAX,
    ekWNMIN,
    ekWNCLOSE,
    ekWNRES,
    ekWNSTD,
    ekWNSRES
};
ekWNFLAG

Atributos por defecto.

ekWNEDGE

La ventana dibuja un borde exterior.

ekWNTITLE

La ventana tiene barra de título.

ekWNMAX

La ventana muestra el botón de maximizar.

ekWNMIN

La ventana muestra el botón de minimizar.

ekWNCLOSE

La ventana muestra el botón de cerrar.

ekWNRES

La ventana tiene bordes redimensionables.

ekWNSTD

Combinación ekWNTITLE | ekWNMIN | ekWNCLOSE.

ekWNSRES

Combinación ekWNSTD | ekWNMAX | ekWNRES.


enum event_t

Tipo de evento. Ver Eventos GUI.

enum event_t
{
    ekEVLABEL,
    ekEVBUTTON,
    ekEVPOPUP,
    ekEVLISTBOX,
    ekEVSLIDER,
    ekEVUPDOWN,
    ekEVTXTFILTER,
    ekEVTXTCHANGE,
    ekEVFOCUS,
    ekEVMENU,
    ekEVDRAW,
    ekEVRESIZE,
    ekEVENTER,
    ekEVEXIT,
    ekEVMOVED,
    ekEVDOWN,
    ekEVUP,
    ekEVCLICK,
    ekEVDRAG,
    ekEVWHEEL,
    ekEVKEYDOWN,
    ekEVKEYUP,
    ekEVWNDMOVED,
    ekEVWNDSIZING,
    ekEVWNDSIZE,
    ekEVWNDCLOSE,
    ekEVCOLOR,
    ekEVTHEME
};
ekEVLABEL

Se ha hecho clic sobre un control Label.

ekEVBUTTON

Se ha hecho clic sobre un control Button.

ekEVPOPUP

Se ha cambiado la selección de un control PopUp.

ekEVLISTBOX

Se ha cambiado la selección de un control ListBox.

ekEVSLIDER

Se está deslizando un control Slider.

ekEVUPDOWN

Se ha hecho clic sobre un control UpDown.

ekEVTXTFILTER

Se está editando el texto de un control Edit o Combo.

ekEVTXTCHANGE

Se ha terminado de editar el texto de un control Edit o Combo.

ekEVFOCUS

Un control ha recibido el foco del teclado.

ekEVMENU

Se ha hecho clic sobre un menú.

ekEVDRAW

Hay que volver a dibujar el contenido de la vista.

ekEVRESIZE

Ha cambiado el tamaño de una vista.

ekEVENTER

El ratón ha entrado en el área de la vista.

ekEVEXIT

El ratón ha salido del área de la vista.

ekEVMOVED

El ratón se está moviendo sobre la superficie de la vista.

ekEVDOWN

Se ha pulsado un botón del ratón.

ekEVUP

Se ha liberado un botón del ratón.

ekEVCLICK

Se ha hecho clic sobre una vista.

ekEVDRAG

Se está realizando dragging dentro de la vista.

ekEVWHEEL

Se ha movido la rueda del ratón.

ekEVKEYDOWN

Se ha pulsado una tecla.

ekEVKEYUP

Se ha liberado una tecla.

ekEVWNDMOVED

Se está moviendo la ventana por el escritorio.

ekEVWNDSIZING

Se está re-dimensionando la ventana.

ekEVWNDSIZE

Se ha re-dimensionando la ventana.

ekEVWNDCLOSE

Se ha cerrado la ventana.

ekEVCOLOR

Se está actualizando un color de comwin_color.

ekEVTHEME

Ha cambiado el tema del escritorio.


struct Control

Control de interfaz (abstracto).

struct Control;

struct Label

Control de interfaz que contiene un texto estático, normalmente limitado a una sola línea. Label.

struct Label;

struct Button

Control de interfaz que representa un botón. Button.

struct Button;

struct PopUp

Control botón con lista desplegable. PopUp.

struct PopUp;

struct Edit

Control de edición de texto Edit.

struct Edit;

struct Combo

Control que combina un cuadro de edición con una lista desplegable. Combo.

struct Combo;

struct ListBox

Control de lista. ListBox.

struct ListBox;

struct UpDown

Control que muestra dos pequeños botones de incremento y decremento. UpDown.

struct UpDown;

struct Slider

Control que muestra una barra con un deslizador. Slider.

struct Slider;

struct Progress

Barra de progreso. Progress.

struct Progress;

struct View

Vista personalizada. Permite crear nuestro propios controles, dibujando lo que queramos. View

struct View;

struct TextView

Vista de texto con varios párrafos y diferentes atributos. TextView.

struct TextView;

struct ImageView

Visor de imágenes. ImageView.

struct ImageView;

struct TableView

Vista de tabla con varias filas y columnas. TableView.

struct TableView;

struct SplitView

Vista partida redimensionable en horizontal o vertical. SplitView.

struct SplitView;

struct Layout

Rejilla invisible donde se organizan los controles de un Panel. Layout.

struct Layout;

struct Cell

Cada una de las celdas que forman un Layout. Cell.

struct Cell;

struct Panel

Área interna de una ventana, que permite agrupar diferentes controles. Panel.

struct Panel;

struct Window

Ventana de interfaz. Window.

struct Window;

struct Menu

Menu o submenu. Menu.

struct Menu;

struct MenuItem

Elemento dentro de un menú. MenuItem.

struct MenuItem;

struct EvButton

Parámetros del evento OnClick de un botón o OnSelect de un popup.

struct EvButton
{
    uint32_t index;
    state_t state;
    const char_t* text;
};
index

Índice del botón o del elemento.

state

Estado.

text

Texto.


struct EvSlider

Parámetros del evento OnMoved de un slider.

struct EvSlider
{
    real32_t pos;
    real32_t incr;
    uint32_t step;
};
pos

Posición normalizada del slider (0, 1).

incr

Incremento con respecto a la posición anterior.

step

Índice del intervalo (solo para rangos discretos).


struct EvText

Parámetros del evento OnChange de los cuadros de texto.

struct EvText
{
    const char_t* text;
    uint32_t cpos;
};
text

Texto.

cpos

Posición del cursor (caret).


struct EvTextFilter

Resultado del evento OnFilter de los cuadros de texto.

struct EvTextFilter
{
    bool_t apply;
    char_t* text;
    uint32_t cpos;
};
apply

TRUE si se debe cambiar el texto original del control.

text

Nuevo texto del control, que es una revisión (filtro) del texto original.

cpos

Posición del cursor (caret).


struct EvDraw

Parámetros del evento OnDraw.

struct EvDraw
{
    DCtx* ctx;
    real32_t x;
    real32_t y;
    real32_t width;
    real32_t height;
};
ctx

Contexto de dibujo 2D.

x

Coordenada x del area de dibujo (viewport).

y

Coordenada y del area de dibujo.

width

Ancho del área de dibujo.

height

Alto del área de dibujo.


struct EvMouse

Parámetros de eventos de ratón.

struct EvMouse
{
    real32_t x;
    real32_t y;
    mouse_t button;
    uint32_t count;
};
x

Coordenada x del puntero.

y

Coordenada y del puntero.

button

Botón activo.

count

Número de clics.


struct EvWheel

Parámetros del evento OnWheel.

struct EvWheel
{
    real32_t x;
    real32_t y;
    real32_t dx;
    real32_t dy;
    real32_t dz;
};
x

Coordenada x del puntero.

y

Coordenada y del puntero.

dx

Incremento en x de la rueda o trackpad.

dy

Incremento en y de la rueda o trackpad.

dz

Incremento en z de la rueda o trackpad.


struct EvKey

Parámetros de eventos de teclado.

struct EvKey
{
    vkey_t key;
};
key

Tecla pulsada o liberada.


struct EvPos

Parámetros de eventos de cambio de posición.

struct EvPos
{
    real32_t x;
    real32_t y;
};
x

Coordenada x.

y

Coordenada y.


struct EvSize

Parámetros de eventos de cambio de tamaño.

struct EvSize
{
    real32_t width;
    real32_t height;
};
width

Anchura (tamaño en x).

height

Altura (tamaño en y).


struct EvWinClose

Parámetros de evento de cierre de ventana.

struct EvWinClose
{
    close_t origin;
};
origin

Origen del cierre.


struct EvMenu

Parámetros de evento de menú.

struct EvMenu
{
    uint32_t index;
    state_t state;
    const char_t* str;
};
index

Índice del item pulsado.

state

Estado del item pulsado.

str

Texto del item pulsado.


gui_start ()

Inicia la librería Gui, reservando espacio para las estructuras internas globales. Internamente llama a draw2d_start. Es llamada automáticamente por osmain.

void
gui_start(void);

gui_finish ()

Finaliza la librería Gui, liberando el espacio de las estructuras internas globales. Internamente llama a draw2d_finish. Es llamada automáticamente por osmain.

void
gui_finish(void);

gui_respack ()

Registra un paquete de recursos.

void
gui_respack(FPtr_respack func_respack);
func_respack

Constructor de recursos.

Observaciones

Ver Recursos.


gui_language ()

Establece el idioma de los recursos registrados con gui_respack.

void
gui_language(const char_t *lang);
lang

El idioma.

Observaciones

Ver Recursos.


gui_text ()

Obtiene una cadena de texto a través de su identificador de recurso.

const char_t*
gui_text(const ResId id);
id

Identificador del recurso.

Retorna

La cadena de texto o NULL si no se encuentra.

Observaciones

El recurso debe pertenecer a un paquete registrado con gui_respack.


gui_image ()

Obtiene una imagen a través de su identificador de recurso.

const Image*
gui_image(const ResId id);
id

Identificador del recurso.

Retorna

La imagen o NULL si no se encuentra.

Observaciones

El recurso debe pertenecer a un paquete registrado con gui_respack. No hay que destruir la imagen ya que está gestionada por Gui.


gui_file ()

Obtiene el contenido de un archivo a través de su identificador de recurso.

const byte_t*
gui_file(const ResId id,
         uint32_t *size);
id

Identificador del recurso.

size

Tamaño en bytes del búfer.

Retorna

Los datos del archivo o NULL si no se encuentra.

Observaciones

El recurso debe pertenecer a un paquete registrado con gui_respack. Los datos están gestionados por Gui, por lo que no hay que liberar memoria.


gui_OnThemeChanged ()

Establece un manejador para detectar el cambio del tema visual del entorno de ventanas.

void
gui_OnThemeChanged(Listener *listener);
listener

El manejador del evento.

❮ Anterior
Siguiente ❯