Label widget
------------

Label widget is a piece of text.

.A label widget
image:label.png[Label widget]

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

.Label widget constructors
[source,c]
-------------------------------------------------------------------------------
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 link:widgets_tattr.html[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
[source,c]
-------------------------------------------------------------------------------
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
[source,c]
-------------------------------------------------------------------------------
void gp_widget_label_tattr_set(gp_widget *self, gp_widget_tattr tattr);
-------------------------------------------------------------------------------

NOTE: 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 link:widgets_tattr.html[text attributes].

.Label JSON attributes
[cols=",,,3",options="header"]
|==============================================================================
|    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 link:widgets_colors.html[color]
|   +text_color+   | string | "text"  | Text link:widgets_colors.html[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 link:widgets_tattr.html[text attribute].
