A widget implementation base. More...

#include <stdlib.h>
#include <stdint.h>
#include <inttypes.h>
#include <stdbool.h>
#include <core/gp_debug.h>
#include <utils/gp_types.h>
#include <widgets/gp_common.h>
#include <widgets/gp_widget_types.h>
#include <widgets/gp_widget_disable.h>
#include <widgets/gp_widget_event.h>

Data Structures
struct	gp_widget
	A widget base. More...

Macros
#define	GP_WIDGET_PAYLOAD(self) (void*)((self)->payload_data)
	An internal macro to get widget specific data pointer.

#define	GP_WIDGET_ASSERT(self, ret)
	Asserts a non NULL widget.

#define	GP_WIDGET_CLASS_ASSERT(self, wclass, ret)
	Asserts a widget class.

#define	GP_WIDGET_TYPE_ASSERT(self, wtype, ret)
	Asserts a widget type.

Enumerations
enum	gp_widget_type { GP_WIDGET_GRID , GP_WIDGET_TABS , GP_WIDGET_BUTTON , GP_WIDGET_CHECKBOX , GP_WIDGET_LABEL , GP_WIDGET_PROGRESSBAR , GP_WIDGET_SPINNER , GP_WIDGET_SLIDER , GP_WIDGET_TBOX , GP_WIDGET_RADIOBUTTON , GP_WIDGET_SPINBUTTON , GP_WIDGET_TABLE , GP_WIDGET_PIXMAP , GP_WIDGET_STOCK , GP_WIDGET_SCROLL_AREA , GP_WIDGET_FRAME , GP_WIDGET_MARKUP , GP_WIDGET_LAYOUT_SWITCH , GP_WIDGET_OVERLAY , GP_WIDGET_LOG , GP_WIDGET_GRAPH , GP_WIDGET_SWITCH , GP_WIDGET_STOCK_SWITCH , GP_WIDGET_MAX }
	Widget types. More...

enum	gp_widget_class { GP_WIDGET_CLASS_NONE = 0 , GP_WIDGET_CLASS_BOOL , GP_WIDGET_CLASS_INT , GP_WIDGET_CLASS_CHOICE , GP_WIDGET_CLASS_MAX }
	Widget classes. More...

enum	gp_widget_alignment { GP_HCENTER = 0x01 , GP_LEFT = 0x02 , GP_RIGHT = 0x03 , GP_HFILL = 0x08 , GP_VCENTER = 0x10 , GP_TOP = 0x20 , GP_BOTTOM = 0x30 , GP_VFILL = 0x80 , GP_HALIGN_MASK = 0x0f , GP_VALIGN_MASK = 0xf0 , GP_FILL = GP_VFILL \| GP_HFILL , GP_HCENTER_WEAK = 0x00 , GP_VCENTER_WEAK = 0x00 }
	A widget alignment. More...

Functions
const char *	gp_widget_class_name (enum gp_widget_class widget_class)
	Returns widget class name.

gp_widget *	gp_widget_new (enum gp_widget_type type, enum gp_widget_class widget_class, size_t payload_size)
	Internal function to allocate a widget.

void	gp_widget_free (gp_widget *self)
	Frees widget memory.

void	gp_widget_set_parent (gp_widget self, gp_widget parent)
	Sets widget parent.

int	gp_widget_focus_set (gp_widget *self)
	Sets focus to a particular widget.

Detailed Description

A widget implementation base.

Definition in file gp_widget.h.

Macro Definition Documentation

◆ GP_WIDGET_ASSERT

#define GP_WIDGET_ASSERT	(	self,
		ret
	)

Value:

                do { \
                if (!self) {\
                        GP_BUG("NULL widget!"); \
                        return ret; \
                } \
        } while (0)

Asserts a non NULL widget.

Prints a warning and exits current function when widget is NULL.

Parameters

self	A widget.
ret	Value to be returned when assertion fails.

Definition at line 392 of file gp_widget.h.

◆ GP_WIDGET_CLASS_ASSERT

#define GP_WIDGET_CLASS_ASSERT	(	self,
		wclass,
		ret
	)

Value:

                do { \
                GP_WIDGET_ASSERT(self, ret); \
                if (self->widget_class != wclass) { \
                        GP_BUG("Invalid widget (%p) class %u != %u", \
                               self, self->widget_class, wclass); \
                        return ret; \
                } \
        } while (0)

Asserts a widget class.

Prints a warning and exits current function when widget class does not match expected class.

Parameters

self	A widget.
wclass	A widget class, enum gp_widget_class.
ret	Value to be returned when assertion fails.

Definition at line 409 of file gp_widget.h.

◆ GP_WIDGET_PAYLOAD

#define GP_WIDGET_PAYLOAD ( self ) (void*)((self)->payload_data)

An internal macro to get widget specific data pointer.

Warning: This is internal API do not use in applications!

Definition at line 169 of file gp_widget.h.

◆ GP_WIDGET_TYPE_ASSERT

#define GP_WIDGET_TYPE_ASSERT	(	self,
		wtype,
		ret
	)

Value:

                do { \
                GP_WIDGET_ASSERT(self, ret); \
                if (self->type != wtype) {\
                        GP_BUG("Invalid widget type %s != %s", \
                                gp_widget_type_id(self), gp_widget_type_name(wtype)); \
                        return ret; \
                } \
        } while (0)

Asserts a widget type.

Prints a warning and exits current function when widget type does not match expected type.

Parameters

self	A widget.
wtype	A widget type, enum gp_widget_type.
ret	Value to be returned when assertion fails.

Definition at line 428 of file gp_widget.h.

Enumeration Type Documentation

◆ gp_widget_alignment

enum gp_widget_alignment

A widget alignment.

Defines a widget alignment in the parent container, the bottom half of the byte defines horizontal alignment, the top half vertical alignment.

The widgets are organized in a two dimensional tree where each widget/layer is an rectangle in a plane. The rectanles on a given tree layer are distinct and the rectanle on an upper layer contains all rectangles on lower layer.

The widget layout is computed in two steps, first minimal size is computed recursively from the top level widget down to the leaf widgets, then if the window is bigger than the minimal needed size, the leftover space is being distributed between the widgets.

In order for a widget to take more space than the minimal size, i.e. be resizable the horizontal and/or vertical alignment has to be set to fill. Which especially means that layout can be resized only and only if the top level layout widget is resizable. Apart from fill each widget can be set to be positioned top/center/bottom vertically as well as left/center/right horizontally.

Examples

Grid horizontal and vertical alignment set to fill button to center

Widget layout in JSON:

{
 "info": {"version": 1, "license": "GPL-2.0-or-later"},
 "layout": {
  "align": "fill",
  "widgets": [
   {"type": "button", "label": "Button", "align": "center"}
  ]
 }
}

Horizontal and vertical alignment set to fill for both

Widget layout in JSON:

{
 "info": {"version": 1, "license": "GPL-2.0-or-later"},
 "layout": {
  "align": "fill",
  "widgets": [
   {"type": "button", "label": "Button", "align": "fill"}
  ]
 }
}

Horizontal and vertical alignment set to center for grid

The button alignment does not matter in this case, since it exaclty fits its assigned space.

Widget layout in JSON:

{
 "info": {"version": 1, "license": "GPL-2.0-or-later"},
 "layout": {
  "align": "center",
  "widgets": [
   {"type": "button", "label": "Button"}
  ]
 }
}

Enumerator
GP_HCENTER	Center horizontally.
GP_LEFT	Align to the left.
GP_RIGHT	Align to the right.
GP_HFILL	Fill available horizontal space, will strech the widget.
GP_VCENTER	Center vertically.
GP_TOP	Align to the top.
GP_BOTTOM	Align to the bottom.
GP_VFILL	Fill available vertical space, will strech the widget.
GP_HALIGN_MASK	Horizontal alignment mask.
GP_VALIGN_MASK	Vertical alignment mask.
GP_FILL	Shortcut for setting both hfill and vfill.

Definition at line 341 of file gp_widget.h.

◆ gp_widget_class

enum gp_widget_class

Widget classes.

Class widgets are operated on by a class functions rather than widget specific functions.

Enumerator
GP_WIDGET_CLASS_NONE	Widget has no class, most common case.
GP_WIDGET_CLASS_BOOL	Boolean class. The widget has two values, e.g. checkbox. See gp_widget_class_bool.h for the list of functions.
GP_WIDGET_CLASS_INT	An integer widget with minimum and maximun. See gp_widget_class_int.h for the list of functions.
GP_WIDGET_CLASS_CHOICE	A widget to choose a single element from a set. See gp_widget_class_choice.h for the list of functions.

Definition at line 228 of file gp_widget.h.

◆ gp_widget_type

enum gp_widget_type

Widget types.

Enumerator
GP_WIDGET_GRID	A container widget to create layout.
GP_WIDGET_TABS	A tabs widget.
GP_WIDGET_BUTTON	A button widget.
GP_WIDGET_CHECKBOX	A checkbox widget.
GP_WIDGET_LABEL	A label widget.
GP_WIDGET_PROGRESSBAR	A progress bar widget.
GP_WIDGET_SPINNER	A spinner widget.
GP_WIDGET_SLIDER	A slider widget.
GP_WIDGET_TBOX	A textbox widget.
GP_WIDGET_RADIOBUTTON	A radiobutton widget.
GP_WIDGET_SPINBUTTON	A spinnbutton widget.
GP_WIDGET_TABLE	A table widget.
GP_WIDGET_PIXMAP	A pixmap widget.
GP_WIDGET_STOCK	A stock image widget.
GP_WIDGET_SCROLL_AREA	A scroll area widget.
GP_WIDGET_FRAME	A frame widget.
GP_WIDGET_MARKUP	A markup widget.
GP_WIDGET_LAYOUT_SWITCH	A layout switch widget.
GP_WIDGET_OVERLAY	An overlay widget.
GP_WIDGET_LOG	A widget log widget.
GP_WIDGET_GRAPH	A graph widget.
GP_WIDGET_SWITCH	A switch widget.
GP_WIDGET_STOCK_SWITCH	A stock switch widget.
GP_WIDGET_MAX	A numeber of widgets.

Definition at line 172 of file gp_widget.h.

Function Documentation

◆ gp_widget_class_name()

const char * gp_widget_class_name ( enum gp_widget_class widget_class )

Returns widget class name.

Parameters

widget_class A widget class.

Returns: A widget class name.

◆ gp_widget_focus_set()

int gp_widget_focus_set ( gp_widget * self )

Sets focus to a particular widget.

Traverses the widget layout tree to the top and sets the focus accordingly.

Parameters

self	A widget to be focused.

Returns: Zero if focus couldn't be changed, non-zero otherwise.

◆ gp_widget_free()

void gp_widget_free ( gp_widget * self )

Frees widget memory.

Following actions are done when widget is being freed:

if widget has gp_widget::on_event() event handler set, GP_WIDGET_EVENT_FREE event is send
if widget has children gp_widget_free() is called recursively for all children widgets
if widget type defines gp_widget_ops::free() it's called
widget memory is finally freed

Example user widget free event handling

static int event_handler(gp_widget_event *ev)
{
     if (ev->type == GP_WIDGET_FREE) {
        free(ev->self->priv);
        return 0;
     }
 
     ...
}
 
int main(void)
{
     ...
 
     void *data = malloc(...);
 
     ...
 
     gp_widget_on_event_set(widget, event_handler, data);
 
     ...
 
     // the event handler calls free on data from this function
     gp_widget_free(widget);
 
     ...
}

Parameters

self A widget.

Referenced by gp_widget_grid_del(), gp_widget_tabs_tab_del(), and gp_widget_tabs_tab_del_by_child().

◆ gp_widget_new()

gp_widget * gp_widget_new	(	enum gp_widget_type	type,
		enum gp_widget_class	widget_class,
		size_t	payload_size
	)

Internal function to allocate a widget.

Parameters

type	A widget type.
widget_class	A widget class.
payload_size	A widet payload size.

Returns: Newly allocated and initialized widget.

◆ gp_widget_set_parent()

void gp_widget_set_parent	(	gp_widget *	self,
		gp_widget *	parent
	)

Sets widget parent.

The function is no-op for NULL self widget.

Parameters

self	A widget.
parent	A parent widget.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ GP_WIDGET_ASSERT

◆ GP_WIDGET_CLASS_ASSERT

◆ GP_WIDGET_PAYLOAD

◆ GP_WIDGET_TYPE_ASSERT

Enumeration Type Documentation

◆ gp_widget_alignment

Examples

◆ gp_widget_class

◆ gp_widget_type

Function Documentation

◆ gp_widget_class_name()

◆ gp_widget_focus_set()

◆ gp_widget_free()

Example user widget free event handling

◆ gp_widget_new()

◆ gp_widget_set_parent()