GFXprim

Label widget

Label widget is a piece of text.

A label widget

Label widget

The struct gp_widget_label can be accessed as widget->label.

Label widget constructors

gp_widget *gp_widget_label_new(const char *text, gp_widget_tattr tattr, unsigned int width);

gp_widget *gp_widget_label_printf_new(gp_widget_tattr tattr, const char *fmt, ...);

The gp_widget_attr parameter sets the text attributes such as bold, etc.

The width parameter, if non-zero, causes the widget to be be able to fit width characters in size, in other words the widget size is set into a stone and will not change. However keep in mind that it will fit exactly width characters only for monospace fonts.

If width parameter is set to zero the widget width is variable, but by default will not shrink.

The printf-like constructor sets the width to a zero internally.

Functions to set label text

void gp_widget_label_set(gp_widget *self, const char *text);

int gp_widget_label_printf(gp_widget *self, const char *fmt, ...);

void gp_widget_label_vprintf(gp_widget *self, const char *fmt, va_list ap);

If widget was created with variable width, it does not shrink, by default, when its text is changed. If this wasn’t the case layout size that periodically changes a label value would jump up and down, since it would be resized regulary. This can be disabled either by clearing the widget no_shrink attribute or by calling gp_widget_resize() after label text has been changed.

Functions to manipulate text attributes

void gp_widget_label_tattr_set(gp_widget *self, gp_widget_tattr tattr);

Since widget label size will not shrink (see above) you should call gp_widget_resize() after changing the text attributes that change font.

Sets a label text attributes.

Table 1. Label JSON attributes
Attribute	Type	Default	Description
`text`	string		Label text
`tattr`	tattr	NULL	Text attributes e.g. bold
`width`	int	0	Label text size
`frame`	bool	false	Draw frame around label, implies min padd = 1
`padd`	int	0	Padd inside label on left and right
`bg_color`	string	"bg"	Background color
`text_color`	string	"text"	Text color
`reverse_colors`	bool	false	Reverse background and text color

Notes on widget size

Unless widget size is set the widget grows its size to fit the content without any limitations, which is only useful for cases where the label is static and its size does not change.

If you have a label whose text is outside of your control, e.g. the value is a result of some system call, RPC call, etc, it’s important to set the label size so that the label will not grow undefinitelly. The most useful combination is to set both label size along with hfill alignment in which case the label will fill all available horizontal space and the size will function as a minimal widget size. The text inside of the label widget can be aligned with text attribute.