<-- Back to AG_Intro.3

SYNOPSIS

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

DESCRIPTION

A horizontal box (top), and a vertical box (right)

The AG_Box widget is a general-purpose container which packs its child widgets horizontally or vertically, with padding and spacing.

AG_Box honors the AG_WIDGET_HFILL and AG_WIDGET_VFILL flags of its children. These flags are passed to widget constructors or set by call to AG_ExpandHoriz(3), AG_ExpandVert(3) or AG_Expand(3)). For instance, a vertical AG_Box will arrange widgets top to bottom. All widgets with the HFILL flag will expand to fit the width of the box, and up to one widget with the VFILL flag can expand to fill the remaining space vertically. A vertical box can hold a maximum of one VFILL widget, and a horizontal box can hold a maximum of one HFILL widget.

 <----------- AG_Box width ------------>
 ---------------------------------------
| [ Widget without HFILL ]              |
| [ Another ]                           |
| [ ....... Widget with HFILL ....... ] |
| [ ............ Another ............ ] |
|  -----------------------------------  |
| | ................................. | |
| | .... Widget with VFILL|HFILL .... | |
| | ..... Fills remaining space ..... | |
| | ................................. | |
|  -----------------------------------  |
 ---------------------------------------

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)

void AG_BoxSetHorizAlign (AG_Box *box, enum ag_box_align align)

void AG_BoxSetVertAlign (AG_Box *box, enum ag_box_align align)

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 arranges for a text label to be displayed over the container. If an argument of NULL is passed, the label is removed.

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.

The AG_BoxSetHorizAlign() and AG_BoxSetVertAlign() functions specify the horizontal or vertical alignment of widgets. The horizontal alignment setting may be AG_BOX_LEFT (default), AG_BOX_CENTER or AG_BOX_RIGHT. The vertical alignment may be set to AG_BOX_TOP (default), AG_BOX_CENTER or AG_BOX_BOTTOM.

EVENTS

The AG_Box widget does not generate any event.

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.