NAME

AG_Box — agar box container widget

SYNOPSIS

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

DESCRIPTION

AG_Box is a general-purpose container widget which aligns and packs its widgets either horizontally or vertically based on their size requisitions and adds spacing and padding. Overflowing widgets are clipped.

Widgets with AG_WIDGET_HFILL expand horizontally to fill remaining space. Widgets with AG_WIDGET_VFILL expand vertically to fill remaining space.

Horizontal boxes allow only up to 1 widget with AG_WIDGET_HFILL (and any number with AG_WIDGET_VFILL).

Vertical boxes allow only up to 1 widget with AG_WIDGET_VFILL (and any number with AG_WIDGET_HFILL).

INHERITANCE HIERARCHY

AG_Object(3) -> AG_Widget(3) -> AG_Box.

INITIALIZATION

AG_Box *
AG_BoxNew(AG_Widget *parent, enum ag_box_type type, Uint flags);

AG_Box *
AG_BoxNewHoriz(AG_Widget *parent, Uint flags);

AG_Box *
AG_BoxNewVert(AG_Widget *parent, Uint flags);

void
AG_BoxSetLabel(AG_Box *box, const char *format, ...);

void
AG_BoxSetLabelS(AG_Box *box, const char *text);

void
AG_BoxSizeHint(AG_Box *box, int width, int height);

void
AG_BoxSetHomogenous(AG_Box *box, int homogenous);

void
AG_BoxSetDepth(AG_Box *box, int depth);

void
AG_BoxSetHorizAlign(AG_Box *box, enum ag_box_align align);

void
AG_BoxSetVertAlign(AG_Box *box, enum ag_box_align align);

AG_BoxNew() allocates, initializes, and attaches a new AG_Box container. type can be AG_BOX_HORIZ for horizontal packing AG_BOX_VERT for vertical packing. Acceptable flags include:

AG_BOX_HOMOGENOUS: Divide space into equal parts.
AG_BOX_SHADING: Show 3D-style shading even if no "background-color".
AG_BOX_HFILL: Expand horizontally in parent container.
AG_BOX_VFILL: Expand vertically in parent container.
AG_BOX_EXPAND: Shorthand for AG_BOX_HFILL | AG_BOX_VFILL.
AG_BOX_NO_SPACING: Set "padding" and "spacing" style attributes to "0".

The AG_BoxNewHoriz() and AG_BoxNewVert() variants are equivalent to setting AG_BOX_HORIZ and AG_BOX_VERT.

AG_BoxSetStyle() selects an alternate background and border style:

AG_BOX_STYLE_NONE: No background.
AG_BOX_STYLE_BOX: Raised box & border.
AG_BOX_STYLE_WELL: 3D well & border (the default).
AG_BOX_STYLE_PLAIN: Filled rectangle.

Visible background styles use the style attributes "background-color", "low-color" and "high-color".

AG_BoxSetLabel() arranges for a text label to be displayed over the container. If an argument of NULL is passed, the label is removed.

AG_BoxSizeHint() sets a specific size requisition in pixels (-1 = auto). The default is determined by the size requisition of attached widgets.

AG_BoxSetHomogenous() sets or clears the AG_BOX_HOMOGENOUS flag, which controls whether available space is divided evenly between widgets.

AG_BoxSetDepth() sets the depth of the shading for AG_BOX_SHADING.

AG_BoxSetHorizAlign() and AG_BoxSetVertAlign() specify the horizontal or vertical alignment of widgets. Horizontal alignment can be AG_BOX_LEFT (default), AG_BOX_CENTER or AG_BOX_RIGHT. Vertical alignment can be AG_BOX_TOP (default), AG_BOX_CENTER or AG_BOX_BOTTOM.

EVENTS

The AG_Box widget does not generate any event.

STRUCTURE DATA

For the AG_Box object:

enum ag_box_style style: Background style (see AG_BoxSetStyle()).

EXAMPLES

The following code fragment packs two columns of buttons:

AG_Window *win;
AG_Box *boxHoriz, *boxCol[2];
int i;

win = AG_WindowNew(0);
boxHoriz = AG_BoxNewVert(win, 0);
boxCol[0] = AG_BoxNewHoriz(boxHoriz, 0);
boxCol[1] = AG_BoxNewHoriz(boxHoriz, 0);

for (i = 0; i < 5; i++)
	AG_ButtonNew(boxCol[0], 0, "In column 1");
for (i = 0; i < 5; i++)
	AG_ButtonNew(boxCol[1], 0, "In column 2");

AG_WindowShow(win);

HISTORY

The AG_Box widget first appeared in Agar 1.0. In Agar 1.6.0, the AG_BoxSetPadding() and AG_BoxSetSpacing() functions were deprecated in favor of the generic "padding" and "spacing" style attributes.