Manejo de UI, eventos y escenas

Estructuras de datos
struct	GUIEVT

defines
#define	CWF_BORDER   0x01
#define	CWF_RESIZE   0x02
#define	CWF_HIDDEN   0x04
#define	CWF_NOESCAPE   0x08

typedefs
typedef void(*	cbEventFunc) (GUIEVT *)

Enumeraciones
enum	EVTYPE

Funciones
bool	GUI_Init (void)
void	GUI_Deinit (void)
bool	GUI_GetDisplayResolution (int index, Rect *rect)
GUI	GUI_CreateWindow (int width, int height, const char *title, int monitor, GUI share, uint8_t flags)
bool	GUI_DeleteWindow (GUI gui)
void	GUI_SetPhysicalSize (int width_mm, int height_mm)
bool	GUI_Load (const char *filename)
Image	GUI_GetImage (const char *name)
Item	GUI_GetItem (const char *name)
const char *	GUI_GetItemName (Item item)
void	GUI_SetWindowTitle (const char *title)
void	GUI_SelectWindow (GUI gui)
GUI	GUI_GetActiveWindow (void)
void	GUI_ShowWindow (bool mode)
void	GUI_SetWindowPosition (int x, int y)
Timeline	GUI_SetAnimation (Timeline timeline, Control control)
void	GUI_EndAnimation (Timeline, bool set_final)
Scene	GUI_SetScene (const char *name)
void	GUI_SetTransition (Transition transition)
bool	GUI_Tasks (void)
	Tareas de mantenimiento interno de la ventana. Más...
void	GUI_Redraw (void)
	Fuerza repintado de la ventana activa. Más...
bool	GUI_GetEvent (GUIEVT *user)
bool	GUI_GetTouchState (void)
void	GUI_GetSize (int *width, int *height)
void *	GUI_GetHWND (void)
Scene	GUI_GetScene (void)
void	GUI_Scale (int oldw, int oldh, int neww, int newh)
void	GUI_TransformPoint (int *x, int *y)
void	GUI_AddEventListener (cbEventFunc func)
void	GUI_RemoveEventListener (cbEventFunc func)
void	GUI_SetRect (Rect *rect, int xLeft, int yTop, int xRight, int yBottom)
void	GUI_OffsetRect (Rect *rect, int dx, int dy)

Descripción detallada

Documentación de los 'defines'

CWF_BORDER

#define CWF_BORDER   0x01

flags creación de ventana para GUI_CreateWindow() la ventana tiene un borde arrastrable

CWF_RESIZE

#define CWF_RESIZE   0x02

la ventana puede redimensionarse

CWF_HIDDEN

#define CWF_HIDDEN   0x04

la ventana se crea oculta

CWF_NOESCAPE

#define CWF_NOESCAPE   0x08

la ventana no puede cerrarse al pulsar Escape

Documentación de los 'typedefs'

cbEventFunc

typedef void(* cbEventFunc) (GUIEVT *)

Prototipo para callbacks de mensaje de evento UI

Documentación de las enumeraciones

EVTYPE

enum EVTYPE

Tipos de evento de usuario, ver GUIEVT

Documentación de las funciones

GUI_Init()

bool GUI_Init

(

void

)

Inicializa biblioteca LibUIGL

GUI_Deinit()

void GUI_Deinit

(

void

)

Libera los recursos de LibUIGL y cierra biblioteca

GUI_GetDisplayResolution()

bool GUI_GetDisplayResolution	(	int	index,
		Rect *	rect
	)

Devuelve la resolucion del monitor indicado

Parámetros

index	Índice del monitor, siendo 0 el primero
rect	Puntero a estructura Rect que recibirá el tamaño

GUI_CreateWindow()

GUI GUI_CreateWindow	(	int	width,
		int	height,
		const char *	title,
		int	num_monitor,
		GUI	share,
		uint8_t	flags
	)

Crea una ventana gráfica

Parámetros

width	Anchura en píxeles
height	Altura en píxeles
title	Título de la ventana
num_monitor	Nº de monitor empezando por 0 donde se generará la pantalla completa. Si es -1, se crea una ventana en el escritorio
share	Puntero a objeto GUI si se quieren compartir recursos entre evntanas, o NULL si es la primera ventana o no se comparten recursos
flags	Indica máscara de flags para creación (si se quiere un borde para arrastrar, o false para crear ventana si marco)

Devuelve

Objeto GUI para posterior manejo de la ventana, o NULL si no se ha podido crear

// crea una ventana de 640x480 píxeles, con título "Mi ventana", en el monitor primario, 
// sin compartir recursos con otra ventana y con un borde arrastrable:
GUI gui = GUI_CreateWindow(640, 480, "Mi ventana", -1, NULL, CWF_BORDER);

GUI_DeleteWindow()

bool GUI_DeleteWindow

(

GUI

gui

)

Destruye una ventana previamente creada

Parámetros

gui	Puntero al objeto GUI con la ventana a destruir

GUI_SetPhysicalSize()

void GUI_SetPhysicalSize	(	int	width_mm,
		int	height_mm
	)

Establece tamaño físico

Parámetros

width_mm	Ancho en milímetros
height_mm	Alto en milímetros

GUI_Load()

bool GUI_Load

(

const char *

filename

)

Carga archivo de definición de escenas y recursos

Parámetros

filename

Nombre del archivo xml con la descripción

GUI_GetImage()

Image GUI_GetImage

(

const char *

name

)

Devuelve el objeto Image con nombre xml o de archivo indicado

Parámetros

name	Puede ser el nombre xml de un elemento <image> predefinido, o un nombre de archivo .png

GUI_GetItem()

Item GUI_GetItem

(

const char *

name

)

Devuelve el elemento con nombre xml indicado

Comentarios

Item es la base abstracta de cualquier elemento UI definido en archivos xml de escena

Parámetros

name	Nombre del elemento a obtener

GUI_GetItemName()

const char* GUI_GetItemName

(

Item

item

)

Devuelve el nombre xml de un determinado elemento

Parámetros

item	Objeto de la interfaz a consultar

Ver también

GUI_GetItem()

Devuelve

Cadena de texto con el nombre, o NULL si no es un objeto válido

GUI_SetWindowTitle()

void GUI_SetWindowTitle

(

const char *

title

)

Establece título de la ventana activa

Parámetros

title

Título a establecer

GUI_SelectWindow()

void GUI_SelectWindow

(

GUI

gui

)

Establece la ventana activa sobre la que operan el resto de comandos GUI_xxx

Parámetros

gui	Objeto GUI de la ventana aestablecer como activa

GUI_GetActiveWindow()

GUI GUI_GetActiveWindow

(

void

)

Devuelve el objeto GUI de la ventana activa actual

GUI_ShowWindow()

void GUI_ShowWindow

(

bool

mode

)

Muestra u oculta la ventana activa

Parámetros

mode	true para mostrar, false para ocultar

GUI_SetWindowPosition()

void GUI_SetWindowPosition	(	int	x,
		int	y
	)

Establece la posición de la ventana activa

Parámetros

x	Coordenada horizontal
y	Coordenada vertical

GUI_SetAnimation()

Timeline GUI_SetAnimation	(	Timeline	timeline,
		Control	control
	)

Inicia animación sobre un control

Parámetros

timeline	Objeto Timeline a iniciar
control	Objeto Control sobre el que ejecutar la animación

Devuelve

manejador de la animación generada

GUI_EndAnimation()

void GUI_EndAnimation	(	Timeline	timeline,
		bool	set_final
	)

Finaliza animación previamente obtenida con GUI_SetAnimation()

Parámetros

timeline	Manejador de animación a finalizar
set_final	Indica si establece esl estado del último fotograma al objeto

GUI_SetScene()

Scene GUI_SetScene

(

const char *

name

)

Establece la escena indicada en la ventana activa

Parámetros

name	Nombre xml de la escena a establecer

Devuelve

Objeto Scene con la escena establecida, o NULL si no se ha encontrado/establecido

// establece una escena xml llamada "escena1" y devuelve manejador:
Scene scene = GUI_SetScene("escena1");

GUI_SetTransition()

void GUI_SetTransition

(

Transition

transition

)

Establece la transición global en la ventana activa

Parámetros

transition

Objeto Transition a mostrar cada vez que se cargue una nueva escena con GUI_SetScene()

GUI_Tasks()

bool GUI_Tasks

(

void

)

Tareas de mantenimiento interno de la ventana.

Debe llamarse esta función de forma regular desde el bucle principal, para ir obteniendo los eventos y mantener la ventana activa. Si no se llama a esta función tras haber creado una ventana, la aplicación dejará de responder

Devuelve

Devuelve true si la ventana está activa, o false si el usuario ha solicitado cerrarla ('X', Alt + F4, etc)

GUI_Redraw()

void GUI_Redraw

(

void

)

Fuerza repintado de la ventana activa.

Para minimizar el uso de la GPU, la ventana sólo se actualiza cuando hay algún evento que lo requiera (animaciones, interacción de usuario...). A veces puede ser necesario forzar una actualización desde la aplicación

GUI_GetEvent()

bool GUI_GetEvent

(

GUIEVT *

evt

)

Devuelve el siguiente evento de la cola de eventos (si hay)

Parámetros

evt	Puntero a estructura GUIEVENT que recibirá los datos del evento devuelto

Devuelve

true si había evento en cola y los valores obtenidos en GUIEVT son válidos, o false si no había evento

Comentarios

el uso de listeners con GUI_AddEventListener() introducido en v3.15 invalida esta función

GUI_GetTouchState()

bool GUI_GetTouchState

(

void

)

Devuelve si la pantalla táctil activa está pulsada (true) o no (false)

GUI_GetSize()

void GUI_GetSize	(	int *	width,
		int *	height
	)

Devuelve el tamaño real de la ventana activa

Parámetros

width	Puntero a entero con la anchura en píxeles
height	Puntero a entero con la altura en píxeles

GUI_GetHWND()

void* GUI_GetHWND

(

void

)

Devuelve el manejador de Windows de la ventana activa (sólo en Windows)

GUI_GetScene()

Scene GUI_GetScene

(

void

)

Devuelve el objeto de la escena actual en la ventana activa

Ver también

GUI_SetScene()

GUI_Scale()

void GUI_Scale	(	int	oldw,
		int	oldh,
		int	neww,
		int	newh
	)

Establece escalado en la ventana activa sobre las coordenadas del archivo xml

Parámetros

oldw	Anchura original canvas
oldh	Altura original canvas
neww	Nueva anchura ventana
newh	Nueva altura ventana

GUI_TransformPoint()

void GUI_TransformPoint	(	int *	x,
		int *	y
	)

Transforma un punto del espacio de coordenadas origen al de pantalla escalada

Parámetros

x	puntero a coordenada horizontal
y	puntero a coordenada vertical

GUI_AddEventListener()

void GUI_AddEventListener

(

cbEventFunc

func

)

Añade función de usuario para ser llamada cuando se produce un evento

Parámetros

func	Puntero a la función de usuario, contextual a la ventana activa

GUI_RemoveEventListener()

void GUI_RemoveEventListener

(

cbEventFunc

func

)

Elimina función de usuario de la lista

Parámetros

func	Puntero de la función a eliminar

GUI_SetRect()

void GUI_SetRect	(	Rect *	rect,
		int	xLeft,
		int	yTop,
		int	xRight,
		int	yBottom
	)

Establece un objeto Rect

Parámetros

rect	Objeto Rect a establecer (x1,y1) -> (x2,y2)
xLeft	x1
yTop	y1
xRight	x2
yBottom	y2

GUI_OffsetRect()

void GUI_OffsetRect	(	Rect *	rect,
		int	dx,
		int	dy
	)

Aplica un offset (desplaza) el objeto Rect indicado

Parámetros

rect	Objeto Rect a desplazar
dx	Desplazamiento horizontal en píxeles
dy	Desplazamiento vertical en píxeles