AG_LABEL(3)

NAME
AG_Label - agar label widget

SYNOPSIS

    #include <agar/core.h>
    #include <agar/gui.h>

DESCRIPTION
The AG_Label widget displays single-line or multi-line text. In the case of ‘polled’ labels, the text can contain elements which are going to be dereferenced on rendering.

INHERITANCE HIERARCHY
AG_Object(3) -> AG_Widget(3) -> AG_Label.

INITIALIZATION
AG_Label * AG_LabelNew(AG_Widget *parent, Uint flags, const char *fmt, ...)

AG_Label * AG_LabelNewS(AG_Widget *parent, Uint flags, const char *text)

AG_Label * AG_LabelNewPolled(AG_Widget *parent, Uint flags, const char *fmt, ...)

AG_Label * AG_LabelNewPolledMT(AG_Widget *parent, Uint flags, AG_Mutex *mutex, const char *fmt, ...)

void AG_LabelText(AG_Label *label, const char *format, ...)

void AG_LabelTextS(AG_Label *label, const char *s)

void AG_LabelSetFont(AG_Label *label, AG_Font *font)

void AG_LabelSetColor(AG_Label *label, AG_Color C)

void AG_LabelSetColorBG(AG_Label *label, AG_Color C)

void AG_LabelSetPadding(AG_Label *label, int left, int right, int top, int bottom)

void AG_LabelJustify(AG_Label *label, enum ag_text_justify justify)

void AG_LabelValign(AG_Label *label, enum ag_text_valign valign)

void AG_LabelSizeHint(AG_Label *label, Uint nlines, const char *text)

The AG_LabelNew() function allocates, initializes and attaches a AG_Label widget initially displaying the given text.

The AG_LabelNewPolled() function creates a new AG_Label widget displaying a string of text which contains references to variables. The AG_LabelNewPolledMT() variant accepts a pointer to a mutex that will be automatically acquired and release as the widget accesses the referenced data. See the POLLED LABELS section for more details.

See LABEL FLAGS section for a the accepted flags values for AG_LabelNew() and AG_LabelNewPolled().

The AG_LabelText() function changes the current label text.

The AG_LabelSetFont() function configures an alternate font which will be used to display the label. The font argument is not duplicated (i.e., the referenced font should remain valid as long as the widget exists). To set the font of a label back to the default Agar font, NULL can be passed. See AG_FetchFont(3) for details on Agar fonts.

AG_LabelSetColor() and AG_LabelSetColorBG() configure an alternate text and background color for the label (see AG_Color(3)).

AG_LabelSetPadding() sets the label padding parameters in pixels. If a parameter is -1, its current value is preserved.

The AG_LabelJustify() function sets the text justification:

    enum ag_text_justify {
    	AG_TEXT_LEFT,
    	AG_TEXT_CENTER,
    	AG_TEXT_RIGHT
    };

AG_LabelValign() sets the vertical text alignment:

    enum ag_text_valign {
    	AG_TEXT_TOP,
    	AG_TEXT_MIDDLE,
    	AG_TEXT_BOTTOM
    };

The AG_LabelSizeHint() function arranges for the minimum scaling of the label to accomodate at least nlines lines of the given text string. If nlines is 0, the number of lines will be based on the contents of the text string.

POLLED LABELS
AG_LabelNewPolled() and AG_LabelNewPolledMT() may be used to display a label containing dynamically accessed elements (i.e., the actual string will be compiled on rendering). AG_LabelNewPolled() accepts an Agar-style format string (see AG_String(3) for details). Subsequent arguments must be pointers (as opposed to literal data), and the formatting engine also provides Agar-specific extensions.

Note that the length of polled labels is difficult to determine automatically, so AG_LabelSizeHint() and AG_ExpandHoriz(3) are typically used with polled labels.

EVENTS
The AG_Label widget does not generate any event.

LABEL FLAGS
The following AG_Label flags are defined:

AG_LABEL_FRAME
    Draw a visible frame around the label.

AG_LABEL_NOMINSIZE
    Don't enforce a minimum size on the label. If the label becomes partially hidden, the text will be truncated with a ‘...’ string.

AG_LABEL_PARTIAL
    The label is partially hidden (read-only).

AG_LABEL_REGEN
    Force re-rendering of the text at next draw (used internally by AG_LabelString(), etc.)

AG_LABEL_HFILL
    Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)). Polled labels, whenever possible, should use this option (otherwise a AG_LabelSizeHint() call is needed).

AG_LABEL_VFILL
    Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)). This option is useful with dynamically changing multi-line labels.

AG_LABEL_EXPAND
    Shorthand for AG_LABEL_HFILL|AG_LABEL_VFILL.

EXAMPLES
The following code snippet creates a window containing both a static label and a polled label:

    AG_Window *win;
    int myInt = 1234;
    AG_Label *myLbl;
    win = AG_WindowNew(0);
    AG_LabelNew(win, 0, "Foo");
    myLbl = AG_LabelNewPolled(win, 0, "myInt=%i", &myInt);
    AG_LabelSizeHint(myLbl, 1, "myInt=0000");

Thread-safe code can associate polled labels with mutexes protecting the data to access:

    int myInt = 1234;
    AG_Mutex myMutex = AG_MUTEX_INITIALIZER;
    AG_LabelNewPolledMT(win, 0, &myMutex, "myInt=%i", &myInt);

The following code fragment defines a custom format specifier, which can be used in polled labels (and is also recognized by AG_Printf()). For more details on custom format specifiers, refer to AG_String(3).

    size_t
    PrintMyVector(AG_FmtString *fs, char *dst, size_t dstSize)
    {
    	struct my_vector *my = AG_LABEL_ARG(fs);
    	return AG_Snprintf(dst, dstSize, "[%f,%f]", my->x, my->y);
    }
    ...
    struct my_vector v;
    AG_RegisterFmtStringExt("myVec", PrintMyVector);
    AG_LabelNewS(parent, 0, "Static label: %[myVec]", &v);
    AG_LabelNewPolled(parent, 0, "Polled label: %[myVec]", &v);

SEE ALSO
AG_FetchFont(3), AG_Intro(3), AG_Pixmap(3), AG_String(3), AG_Widget(3), AG_Window(3)

HISTORY
The AG_Label widget first appeared in Agar 1.0. In Agar 1.5.0, the formatting engine for "polled labels" was rewritten and generalized.