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_Box widget packs its children horizontally or vertically.

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)

AG_Box * AG_BoxNewHorizNS (AG_Widget *parent, Uint flags)

AG_Box * AG_BoxNewVertNS (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_BoxSetHomogenous (AG_Box *box, int homogenous)

void AG_BoxSetPadding (AG_Box *box, int padding)

void AG_BoxSetSpacing (AG_Box *box, int spacing)

void AG_BoxSetDepth (AG_Box *box, int depth)

The AG_BoxNew() function allocates, initializes, and attaches a new AG_Box widget. The type argument defines the packing as AG_BOX_HORIZ or AG_BOX_VERT. Acceptable flags include:

AG_BOX_HOMOGENOUS	Divide space into equal parts.
AG_BOX_FRAME	Draw a decorative frame by default. This flag is implied if a caption text is set.
AG_BOX_HFILL	Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_BOX_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_BOX_EXPAND	Shorthand for AG_BOX_HFILL\|AG_BOX_VFILL.

The AG_BoxNewHoriz() and AG_BoxNewVert() variants are equivalent to setting AG_BOX_HORIZ and AG_BOX_VERT. The AG_BoxNewHorizNS() and AG_BoxNewVertNS() (no spacing) variants implicitely set default padding and spacing parameters to 0 pixels.

The AG_BoxSetLabel() function configures a text label to display over the container.

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

The AG_BoxSetPadding() function sets the padding around the group of child widgets to padding pixels. AG_BoxSetSpacing() sets the spacing between individual child widgets to spacing pixels.

Assuming that the AG_BOX_FRAME flag was given, AG_BoxSetDepth() sets the depth of the frame.

EVENTS

The AG_Box widget neither reacts to nor generates any event.

EXAMPLES

The following code fragment creates two rows of buttons, packed horizontally.

AG_Window *win;
AG_Box *boxVert, *boxRow[2];
int i;
win = AG_WindowNew(0);
boxVert = AG_BoxNewVert(win, AG_BOX_EXPAND);
boxRow[0] = AG_BoxNewHoriz(boxVert, AG_BOX_EXPAND);
boxRow[1] = AG_BoxNewHoriz(boxVert, AG_BOX_EXPAND);
for (i = 0; i < 5; i++)
	AG_ButtonNew(boxRow[0], 0, "foo");
for (i = 0; i < 5; i++)
	AG_ButtonNew(boxRow[1], 0, "bar");
AG_WindowShow(win);

HISTORY

The AG_Box widget first appeared in Agar 1.0.