Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_LABEL(3)	       FreeBSD Library Functions Manual		   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 automati-
     cally, 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 invok-
			  ing 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 dy-
			  namically 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 la-
     bel 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 for-
     matting engine for	"polled	labels"	was rewritten and generalized.

FreeBSD	13.0			August 21, 2002			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INITIALIZATION | POLLED LABELS | EVENTS | LABEL FLAGS | EXAMPLES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Label&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help