UI Elements. More...

Collaboration diagram for UI Elements:

Detailed Description

UI Elements.

A window is made up of a tree of elements, each element is responsible for drawing a part of the window and handling events for that part. Elements can have child elements, which are drawn on top of the parent element.

Each element will on creation, copy the current global theme as its own theme, which can then be modified on a per-element basis.

Data Structures
struct	text_props_t
	Element text properties structure. More...

struct	image_props_t
	Element image properties structure. More...

struct	element_t
	Opaque element structure. More...

Macros
#define	ELEMENT_NONE 0

#define	ELEMENT_TOGGLE (1 << 0)

#define	ELEMENT_FLAT (1 << 1)

#define	ELEMENT_NO_BEZEL (1 << 2)

#define	ELEMENT_NO_OUTLINE (1 << 3)

#define	ELEMENT_ID_NONE UINT64_MAX
	Element ID indicating no element.

Typedefs
typedef uint64_t	element_flags_t
	Element flags type.

typedef struct element	element_t

typedef uint64_t	element_id_t
	Element identifier type.

Functions
element_t *	element_new (element_t parent, element_id_t id, const rect_t rect, const char text, element_flags_t flags, procedure_t procedure, void private)
	Allocate and initialize a new element.

void	element_free (element_t *elem)
	Deinitialize and free an element and all its children.

element_t *	element_find (element_t *elem, element_id_t id)
	Find a child element by its ID.

void	element_set_private (element_t elem, void private)
	Set private data for an element.

void *	element_get_private (element_t *elem)
	Get private data for an element.

element_id_t	element_get_id (element_t *elem)
	Get the ID of an element.

void	element_move (element_t elem, const rect_t rect)
	Move an element to a new rectangle in its parent's coordinate space.

rect_t	element_get_rect (element_t *elem)
	Get the rectangle of an element in its parent's coordinate space.

rect_t	element_get_content_rect (element_t *elem)
	Get the element's rectangle in local coordinates.

rect_t	element_get_window_rect (element_t *elem)
	Get the rectangle of an element in window coordinates.

point_t	element_get_window_point (element_t *elem)
	Get the top-left point of an element in window coordinates.

rect_t	element_rect_to_window (element_t elem, const rect_t src)
	Convert a rectangle from element coordinates to window coordinates.

point_t	element_point_to_window (element_t elem, const point_t src)
	Convert a point from element coordinates to window coordinates.

rect_t	element_window_to_rect (element_t elem, const rect_t src)
	Convert a rectangle from window coordinates to element coordinates.

point_t	element_window_to_point (element_t elem, const point_t src)
	Convert a point from window coordinates to element coordinates.

element_flags_t	element_get_flags (element_t *elem)
	Get the flags of an element.

void	element_set_flags (element_t *elem, element_flags_t flags)
	Set the flags of an element.

const char *	element_get_text (element_t *elem)
	Get the text of an element.

uint64_t	element_set_text (element_t elem, const char text)
	Set the text of an element.

text_props_t *	element_get_text_props (element_t *elem)
	Get the text properties of an element.

image_t *	element_get_image (element_t *elem)
	Get the image of an element.

void	element_set_image (element_t elem, image_t image)
	Set the image of an element.

image_props_t *	element_get_image_props (element_t *elem)
	Get the image properties of an element.

theme_t *	element_get_theme (element_t *elem)
	Get the theme of an element.

void	element_draw_begin (element_t elem, drawable_t draw)
	Begin drawing to an element.

void	element_draw_end (element_t elem, drawable_t draw)
	End drawing to an element.

void	element_redraw (element_t *elem, bool shouldPropagate)
	Redraw an element.

void	element_force_action (element_t *elem, action_type_t action)
	Force an action on an element.

uint64_t	element_dispatch (element_t elem, const event_t event)
	Dispatch an event to an element.

uint64_t	element_emit (element_t elem, event_type_t type, const void data, uint64_t size)
	Emit an event to an element.

Macro Definition Documentation

◆ ELEMENT_NONE

#define ELEMENT_NONE 0

Definition at line 43 of file element.h.

◆ ELEMENT_TOGGLE

#define ELEMENT_TOGGLE (1 << 0)

Definition at line 44 of file element.h.

◆ ELEMENT_FLAT

#define ELEMENT_FLAT (1 << 1)

Definition at line 45 of file element.h.

◆ ELEMENT_NO_BEZEL

#define ELEMENT_NO_BEZEL (1 << 2)

Definition at line 46 of file element.h.

◆ ELEMENT_NO_OUTLINE

#define ELEMENT_NO_OUTLINE (1 << 3)

Definition at line 47 of file element.h.

◆ ELEMENT_ID_NONE

#define ELEMENT_ID_NONE UINT64_MAX

Element ID indicating no element.

Definition at line 28 of file element_id.h.

Typedef Documentation

◆ element_flags_t

element_flags_t

Element flags type.

We make this a uint64_t instead an an enum to give us more flags for the future.

Definition at line 41 of file element.h.

◆ element_t

typedef struct element element_t

Definition at line 53 of file element.h.

◆ element_id_t

element_id_t

Element identifier type.

Used to send events to specific elements and to know which element sent an event, for example to know which button was pressed in a EVENT_LIB_ACTION event.

Definition at line 23 of file element_id.h.

Function Documentation

◆ element_new()

element_t * element_new	(	element_t *	parent,
		element_id_t	id,
		const rect_t *	rect,
		const char *	text,
		element_flags_t	flags,
		procedure_t	procedure,
		void *	private
	)

Allocate and initialize a new element.

Will send a fake EVENT_LIB_INIT event to the element after creation, followed by a real EVENT_LIB_REDRAW event.

A event being fake just means its sent by directly calling the element procedure, instead of being pushed to the display's event queue.

Parameters

parent	The parent element.
id	The element ID.
rect	The elements rectangle relative to its parent.
text	The elements text, if the element is for example a button, this will be the button label.
flags	The element flags.
procedure	The element procedure.
private	Pointer to private data for the element.

Returns: On success, a pointer to the new element. On failure, NULL and errno is set.

Definition at line 48 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_free()

void element_free ( element_t * elem )

Deinitialize and free an element and all its children.

Will send a fake EVENT_LIB_DEINIT event to the element before freeing it.

Parameters

elem	The element to free.

Definition at line 113 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_find()

element_t * element_find	(	element_t *	elem,
		element_id_t	id
	)

Find a child element by its ID.

Will search recursively through all child elements.

Parameters

elem	The element to search from.
id	The element ID to search for.

Returns: A pointer to the found element, or NULL if not found.

Definition at line 134 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_set_private()

void element_set_private	(	element_t *	elem,
		void *	private
	)

Set private data for an element.

Parameters

elem	The element.
private	Pointer to the private data.

Definition at line 163 of file element.c.

Here is the caller graph for this function:

◆ element_get_private()

void * element_get_private ( element_t * elem )

Get private data for an element.

Parameters

elem	The element.

Returns: Pointer to the private data, or NULL if none is set.

Definition at line 173 of file element.c.

Here is the caller graph for this function:

◆ element_get_id()

element_id_t element_get_id ( element_t * elem )

Get the ID of an element.

Parameters

elem	The element.

Returns: The element ID, or ELEMENT_ID_NONE if elem is NULL.

Definition at line 183 of file element.c.

◆ element_move()

void element_move	(	element_t *	elem,
		const rect_t *	rect
	)

Move an element to a new rectangle in its parent's coordinate space.

Will NOT redraw the element, call element_redraw() if needed.

Parameters

elem	The element.
rect	The new rectangle.

Definition at line 193 of file element.c.

Here is the caller graph for this function:

◆ element_get_rect()

rect_t element_get_rect ( element_t * elem )

Get the rectangle of an element in its parent's coordinate space.

Equivalent to RECT_INIT_DIM(x, y, width, height).

Parameters

elem	The element.

Returns: The element rectangle, or a zero-area rectangle if elem is NULL.

Definition at line 203 of file element.c.

◆ element_get_content_rect()

rect_t element_get_content_rect ( element_t * elem )

Get the element's rectangle in local coordinates.

Equivalent to RECT_INIT_DIM(0, 0, width, height).

Parameters

elem	The element.

Returns: The content rectangle, or a zero-area rectangle if elem is NULL.

Definition at line 213 of file element.c.

Here is the caller graph for this function:

◆ element_get_window_rect()

rect_t element_get_window_rect ( element_t * elem )

Get the rectangle of an element in window coordinates.

Parameters

elem	The element.

Returns: The element rectangle in window coordinates, or a zero-area rectangle if elem is NULL.

Definition at line 223 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_get_window_point()

point_t element_get_window_point ( element_t * elem )

Get the top-left point of an element in window coordinates.

Parameters

elem	The element.

Returns: The top-left point in window coordinates, or (0, 0) if elem is NULL.

Definition at line 234 of file element.c.

Here is the caller graph for this function:

◆ element_rect_to_window()

rect_t element_rect_to_window	(	element_t *	elem,
		const rect_t *	src
	)

Convert a rectangle from element coordinates to window coordinates.

Parameters

elem	The element.
src	The source rectangle in element coordinates.

Returns: The rectangle in window coordinates, or a zero-area rectangle if elem or src is NULL.

Definition at line 253 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_point_to_window()

point_t element_point_to_window	(	element_t *	elem,
		const point_t *	src
	)

Convert a point from element coordinates to window coordinates.

Parameters

elem	The element.
src	The source point in element coordinates.

Returns: The point in window coordinates, or (0, 0) if elem or src is NULL.

Definition at line 269 of file element.c.

Here is the call graph for this function:

◆ element_window_to_rect()

rect_t element_window_to_rect	(	element_t *	elem,
		const rect_t *	src
	)

Convert a rectangle from window coordinates to element coordinates.

Parameters

elem	The element.
src	The source rectangle in window coordinates.

Returns: The rectangle in element coordinates, or a zero-area rectangle if elem or src is NULL.

Definition at line 283 of file element.c.

Here is the call graph for this function:

◆ element_window_to_point()

point_t element_window_to_point	(	element_t *	elem,
		const point_t *	src
	)

Convert a point from window coordinates to element coordinates.

Parameters

elem	The element.
src	The source point in window coordinates.

Returns: The point in element coordinates, or (0, 0) if elem or src is NULL.

Definition at line 299 of file element.c.

Here is the call graph for this function:

◆ element_get_flags()

element_flags_t element_get_flags ( element_t * elem )

Get the flags of an element.

Parameters

elem	The element.

Returns: The element flags, or ELEMENT_NONE if elem is NULL.

◆ element_set_flags()

void element_set_flags	(	element_t *	elem,
		element_flags_t	flags
	)

Set the flags of an element.

Parameters

elem	The element.
flags	The new element flags.

Definition at line 323 of file element.c.

◆ element_get_text()

const char * element_get_text ( element_t * elem )

Get the text of an element.

Parameters

elem	The element.

Returns: The element text, or NULL if elem is NULL.

◆ element_set_text()

uint64_t element_set_text	(	element_t *	elem,
		const char *	text
	)

Set the text of an element.

Will NOT redraw the element, call element_redraw() if needed.

Parameters

elem	The element.
text	The new text.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 343 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_get_text_props()

text_props_t * element_get_text_props ( element_t * elem )

Get the text properties of an element.

The returned pointer can be used to modify the text properties.

Parameters

elem	The element.

Returns: Pointer to the text properties, or NULL if elem is NULL.

Definition at line 361 of file element.c.

Here is the caller graph for this function:

◆ element_get_image()

image_t * element_get_image ( element_t * elem )

Get the image of an element.

Parameters

elem	The element.

Returns: Pointer to the image, or NULL if elem is NULL or has no image.

◆ element_set_image()

void element_set_image	(	element_t *	elem,
		image_t *	image
	)

Set the image of an element.

Will NOT redraw the element, call element_redraw() if needed.

Parameters

elem	The element.
image	Pointer to the new image or `NULL` to remove the image.

Definition at line 381 of file element.c.

Here is the caller graph for this function:

◆ element_get_image_props()

image_props_t * element_get_image_props ( element_t * elem )

Get the image properties of an element.

The returned pointer can be used to modify the image properties.

Parameters

elem	The element.

Returns: Pointer to the image properties, or NULL if elem is NULL.

◆ element_get_theme()

theme_t * element_get_theme ( element_t * elem )

Get the theme of an element.

Parameters

elem	The element.

Returns: Pointer to the theme, or NULL if elem is NULL.

Definition at line 401 of file element.c.

Here is the caller graph for this function:

◆ element_draw_begin()

void element_draw_begin	(	element_t *	elem,
		drawable_t *	draw
	)

Begin drawing to an element.

Note that since this will fill the drawable structure with the element's content rectangle, if the element is for example moved or resized the drawable will be invalid.

Parameters

elem	The element to draw to.
draw	Pointer to the drawable structure to initialize.

Definition at line 411 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_draw_end()

void element_draw_end	(	element_t *	elem,
		drawable_t *	draw
	)

End drawing to an element.

This will invalidate the area of the element that was drawn to and send redraw events to any child elements that overlap the invalid area.

Parameters

elem	The element that was drawn to.
draw	Pointer to the drawable structure that was used for drawing.

Definition at line 427 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_redraw()

void element_redraw	(	element_t *	elem,
		bool	shouldPropagate
	)

Redraw an element.

Will push a EVENT_LIB_REDRAW event to the display event queue for the element, meaning the redraw event is not processed immediately.

Parameters

elem	The element to redraw.
shouldPropagate	Whether the redraw event should propagate to child elements.

Definition at line 450 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_force_action()

void element_force_action	(	element_t *	elem,
		action_type_t	action
	)

Force an action on an element.

Will push a EVENT_LIB_FORCE_ACTION event to the display event queue for the element, meaning the action event is not processed immediately.

Parameters

elem	The element.
action	The action to force.

Definition at line 463 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_dispatch()

uint64_t element_dispatch	(	element_t *	elem,
		const event_t *	event
	)

Dispatch an event to an element.

This will call the element's procedure with the given event after some preprocessing.

Most events will also be propagated to child elements by the element's procedure.

Parameters

elem	The element.
event	The event to dispatch.

Returns: The return value of the element's procedure.

Definition at line 476 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ element_emit()

uint64_t element_emit	(	element_t *	elem,
		event_type_t	type,
		const void *	data,
		uint64_t	size
	)

Emit an event to an element.

This function will construct an event and dispatch it to the element.

Parameters

elem	The element.
type	The event type.
data	Pointer to the event data, can be `NULL` if `size` is `0`.
size	The size of the event data.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 555 of file element.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ ELEMENT_NONE

◆ ELEMENT_TOGGLE

◆ ELEMENT_FLAT

◆ ELEMENT_NO_BEZEL

◆ ELEMENT_NO_OUTLINE

◆ ELEMENT_ID_NONE

Typedef Documentation

◆ element_flags_t

◆ element_t

◆ element_id_t

Function Documentation

◆ element_new()

◆ element_free()

◆ element_find()

◆ element_set_private()

◆ element_get_private()

◆ element_get_id()

◆ element_move()

◆ element_get_rect()

◆ element_get_content_rect()

◆ element_get_window_rect()

◆ element_get_window_point()

◆ element_rect_to_window()

◆ element_point_to_window()

◆ element_window_to_rect()

◆ element_window_to_point()

◆ element_get_flags()

◆ element_set_flags()

◆ element_get_text()

◆ element_set_text()

◆ element_get_text_props()

◆ element_get_image()

◆ element_set_image()

◆ element_get_image_props()

◆ element_get_theme()

◆ element_draw_begin()

◆ element_draw_end()

◆ element_redraw()

◆ element_force_action()

◆ element_dispatch()

◆ element_emit()