Agar


Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

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_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)

void AG_RegisterLabelFormat (const char *fmt, void (*fn)(AG_Label *label, char *s, size_t len, int fPos))

void AG_UnregisterLabelFormat (const char *fmt)

void AG_LABEL_ARG (AG_Label *label, TYPE type)


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_LabelSetPadding() function 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. The format string argument to AG_LabelNewPolled() is similar to a printf-style format string but the subsequent arguments in the variable-argument list are pointers. The AG_Label widget will display a continuously updated string, dereferencing the specified variables at time of rendering. Built-in format specifiers include:
%d, %iint
%ld, %lilong int
%lld, %llilong long int or Sint64
%o, %u, %x, %Xunsigned int
%lu, %lo, %lxlong unsigned int
%llu, %llo, %llxlong long unsigned int or Uint64
%cchar
%schar *
%pvoid *
%f, %gfloat *
%lf, %lgdouble *
%llf, %llglong double *
%[u8]Uint8 *
%[s8]Sint8 *
%[u16]Uint16 *
%[s16]Sint16 *
%[u32]Uint32 *
%[s32]Sint32 *
%[flags]Uint *
%[flags8]Uint8 *
%[flags16]Uint16 *
%[flags32]Uint32 *

The %[flags*] directives require that bit (or bitmask) descriptions be provided using the AG_LabelFlag*() functions (see FLAG DESCRIPTIONS section below).

It is possible to register custom format specifiers (%[foo]) with the AG_RegisterLabelFormat() function. The callback function provided is expected to fill the contents of fixed-size buffer s with a string. The argument is retrieved using the AG_LABEL_ARG() macro. AG_UnregisterLabelFormat() removes the given format specifier.

Note that the length of dynamic labels is difficult to determine automatically, so it is recommended to use either AG_LabelSizeHint() or AG_ExpandHoriz(3) with polled labels.

FLAG DESCRIPTIONS


void AG_LabelFlag (AG_Label *label, Uint index, const char *descr, Uint bitmask)

void AG_LabelFlag8 (AG_Label *label, Uint index, const char *descr, Uint8 bitmask)

void AG_LabelFlag16 (AG_Label *label, Uint index, const char *descr, Uint16 bitmask)

void AG_LabelFlag32 (AG_Label *label, Uint index, const char *descr, Uint32 bitmask)


The AG_LabelFlag(), AG_LabelFlag8(), AG_LabelFlag16() and AG_LabelFlag32() functions register a new bit "flag" description for the variable at index. If the pointed value AND'ed with bitmask is true, the descr text will be displayed by the label.

EVENTS

The AG_Label widget neither reacts to nor generates any event.

LABEL FLAGS

The following AG_Label flags are defined:
AG_LABEL_FRAMEDraw a visible frame around the label.
AG_LABEL_NOMINSIZEDon't enforce a minimum size on the label. If the label becomes partially hidden, the text will be truncated with a ... string.
AG_LABEL_PARTIALThe label is partially hidden (read-only).
AG_LABEL_REGENForce re-rendering of the text at next draw (used internally by AG_LabelString(), etc.)
AG_LABEL_HFILLExpand 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_VFILLExpand vertically in parent (equivalent to invoking AG_ExpandVert(3)). This option is useful with dynamically changing multi-line labels.
AG_LABEL_EXPANDShorthand 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);
}

It is frequently useful to display bit values in textual format. The following example would display FOO_FLAG, BAR_FLAG. 
{
	Uint MyFlags = FOO_FLAG|BAR_FLAG;
	AG_Label *lbl;
	lbl = AG_LabelNewPolled(win, 0, "MyFlags=%[flags]", &MyFlags);
	AG_LabelFlag(lbl, 0, "FOO_FLAG", FOO_FLAG);
	AG_LabelFlag(lbl, 0, "BAR_FLAG", BAR_FLAG);
}

The following code fragment defines a custom format specifier for use in polled labels: 
void
PrintMyVector(AG_Label *label, char *s, size_t len, int fPos)
{
	struct my_vector *my = AG_LABEL_ARG(label, void *);
	snprintf(s, len, "[%f,%f]", my->x, my->y);
}
{
	struct my_vector v;
	AG_RegisterLabelFormat("myVec", PrintMyVector);
	AG_LabelNewPolled(parent, 0, "%[myVec]", &v);
}

SEE ALSO

AG_Intro(3), AG_Pixmap(3), AG_Widget(3), AG_Window(3), M_Label(3), printf(3)

HISTORY

The AG_Label widget first appeared in Agar 1.0.