UI Elements. More...

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.

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.

Macro Definition Documentation

◆ ELEMENT_FLAT

#define ELEMENT_FLAT (1 << 1)

Definition at line 45 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.

◆ 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_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.

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_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 LEVENT_ACTION event.

Definition at line 23 of file element_id.h.

◆ element_t

typedef struct element element_t

Definition at line 53 of file element.h.

Function Documentation

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

References element_t::children, EINVAL, element_dispatch(), element_emit(), ERR, errno, EVENT_MAX_DATA, EVENT_MOUSE, rect_t::left, LEVENT_INIT, LEVENT_REDRAW, LIST_FOR_EACH, event_t::lRedraw, event_t::mouse, NULL, event_mouse_t::pos, element_t::proc, event_t::raw, element_t::rect, levent_redraw_t::shouldPropagate, rect_t::top, event_t::type, element_t::win, point_t::x, and point_t::y.

Referenced by element_dispatch(), element_emit(), and window_dispatch().

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

References drawable_t::buffer, window_t::buffer, drawable_t::contentRect, drawable_t::disp, window_t::disp, element_get_window_rect(), drawable_t::invalidRect, rect_t::left, NULL, element_t::rect, window_t::rect, RECT_HEIGHT, RECT_INIT, RECT_WIDTH, drawable_t::stride, rect_t::top, and element_t::win.

Referenced by button_draw(), label_procedure(), popup_procedure(), procedure(), startmenu_procedure(), taskbar_procedure(), terminal_procedure(), window_deco_redraw(), and window_deco_report().

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

References element_t::children, element_rect_to_window(), element_redraw(), drawable_t::invalidRect, LIST_FOR_EACH, NULL, element_t::rect, RECT_AREA, RECT_OVERLAP, element_t::win, and window_invalidate().

Referenced by button_draw(), label_procedure(), popup_procedure(), procedure(), startmenu_procedure(), taskbar_procedure(), terminal_procedure(), window_deco_redraw(), and window_deco_report().

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

References data, EINVAL, element_dispatch(), ERR, errno, EVENT_MAX_DATA, memcpy(), MIN, NULL, window_t::surface, event_t::target, and element_t::win.

Referenced by element_dispatch(), and taskbar_procedure().

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

References element_t::children, element_find(), element_t::id, LIST_FOR_EACH, and NULL.

Referenced by element_find(), procedure(), taskbar_procedure(), taskbar_update_clock(), and window_dispatch().

◆ element_force_action()

void element_force_action	(	element_t *	elem,
		action_type_t	action
	)

Force an action on an element.

Will push a LEVENT_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.

References levent_force_action_t::dest, window_t::disp, display_push(), element_t::id, LEVENT_FORCE_ACTION, NULL, window_t::surface, and element_t::win.

Referenced by taskbar_procedure().

◆ element_free()

void element_free ( element_t * elem )

Deinitialize and free an element and all its children.

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

Parameters

elem	The element to free.

Definition at line 113 of file element.c.

References element_free_children(), element_t::entry, free(), LEVENT_DEINIT, list_remove(), NULL, element_t::parent, element_t::proc, window_t::surface, event_t::target, element_t::text, and element_t::win.

Referenced by element_free_children(), element_new(), element_new_root(), start_menu_load_entries(), taskbar_entry_remove(), taskbar_procedure(), window_deco_init_controls(), and window_free().

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

References NULL, element_t::rect, RECT_HEIGHT, RECT_INIT_DIM, and RECT_WIDTH.

Referenced by button_draw(), button_procedure(), label_procedure(), popup_procedure(), procedure(), startmenu_procedure(), taskbar_get_clock_rect(), taskbar_procedure(), terminal_clear(), terminal_put(), terminal_scroll(), window_deco_redraw(), and window_deco_titlebar_rect().

◆ 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_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.

References ELEMENT_ID_NONE, element_t::id, and NULL.

◆ 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_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_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.

References NULL, and element_t::private.

Referenced by button_procedure(), popup_procedure(), procedure(), start_menu_close(), start_menu_get_state(), start_menu_open(), startmenu_procedure(), taskbar_procedure(), terminal_loop(), terminal_procedure(), window_deco_draw_titlebar(), window_deco_free(), window_deco_handle_dragging(), and window_deco_report().

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

References NULL, and element_t::rect.

◆ 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_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.

References NULL, and element_t::textProps.

Referenced by numpad_button_create(), and procedure().

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

References NULL, and element_t::theme.

Referenced by block_draw(), button_draw(), field_edge_draw(), label_procedure(), popup_procedure(), procedure(), side_panel_draw(), start_menu_open(), start_press_space_draw(), startmenu_procedure(), taskbar_get_clock_rect(), taskbar_get_left_separator_rect(), taskbar_get_right_separator_rect(), taskbar_get_start_rect(), taskbar_get_task_button_rect(), taskbar_procedure(), terminal_char_pos(), terminal_clear(), terminal_procedure(), terminal_scroll(), ternminal_execute_ansi(), window_deco_button_rect(), window_deco_draw_titlebar(), window_deco_init_controls(), window_deco_redraw(), and window_deco_titlebar_rect().

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

References rect_t::left, NULL, element_t::parent, element_t::rect, rect_t::top, point_t::x, and point_t::y.

Referenced by element_get_window_rect(), element_point_to_window(), element_rect_to_window(), element_window_to_point(), and element_window_to_rect().

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

References element_get_window_point(), NULL, element_t::rect, RECT_HEIGHT, RECT_INIT_DIM, RECT_WIDTH, point_t::x, and point_t::y.

Referenced by element_draw_begin().

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

References NULL, and element_t::rect.

Referenced by taskbar_reposition_task_buttons().

◆ 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 LEVENT_INIT event to the element after creation, followed by a real LEVENT_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.

References element_t::children, EINVAL, element_free(), element_new_raw(), element_send_init(), ENOMEM, element_t::entry, ERR, errno, list_push(), NULL, element_t::parent, procedure(), and element_t::win.

Referenced by button_new(), label_new(), and window_new().

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

References element_get_window_point(), NULL, point_t::x, and point_t::y.

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

References rect_t::bottom, element_get_window_point(), rect_t::left, NULL, rect_t::right, rect_t::top, point_t::x, and point_t::y.

Referenced by element_draw_end().

◆ element_redraw()

void element_redraw	(	element_t *	elem,
		bool	shouldPropagate
	)

Redraw an element.

Will push a LEVENT_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.

References window_t::disp, display_push(), levent_redraw_t::id, element_t::id, LEVENT_REDRAW, NULL, window_t::surface, and element_t::win.

Referenced by element_draw_end(), element_send_init(), procedure(), taskbar_entry_add(), taskbar_entry_remove(), and taskbar_update_clock().

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

References element_t::flags, and NULL.

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

References element_t::image, image, and NULL.

Referenced by window_deco_init_controls().

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

References NULL, and element_t::private.

Referenced by button_procedure(), procedure(), startmenu_procedure(), taskbar_procedure(), terminal_procedure(), and window_deco_init().

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

References ERR, free(), NULL, strdup(), and element_t::text.

Referenced by procedure(), and taskbar_update_clock().

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

References element_get_window_point(), NULL, point_t::x, and point_t::y.

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

References rect_t::bottom, element_get_window_point(), rect_t::left, NULL, rect_t::right, rect_t::top, point_t::x, and point_t::y.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ELEMENT_FLAT

◆ ELEMENT_ID_NONE

◆ ELEMENT_NO_BEZEL

◆ ELEMENT_NO_OUTLINE

◆ ELEMENT_NONE

◆ ELEMENT_TOGGLE

Typedef Documentation

◆ element_flags_t

◆ element_id_t

◆ element_t

Function Documentation

◆ element_dispatch()

◆ element_draw_begin()

◆ element_draw_end()

◆ element_emit()

◆ element_find()

◆ element_force_action()

◆ element_free()

◆ element_get_content_rect()

◆ element_get_flags()

◆ element_get_id()

◆ element_get_image()

◆ element_get_image_props()

◆ element_get_private()

◆ element_get_rect()

◆ element_get_text()

◆ element_get_text_props()

◆ element_get_theme()

◆ element_get_window_point()

◆ element_get_window_rect()

◆ element_move()

◆ element_new()

◆ element_point_to_window()

◆ element_rect_to_window()

◆ element_redraw()

◆ element_set_flags()

◆ element_set_image()

◆ element_set_private()

◆ element_set_text()

◆ element_window_to_point()

◆ element_window_to_rect()