.\" Copyright (c) 2002-2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 10, 2003
.Dt AG_BOX 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Box
.Nd agar general container widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
widget packs its children horizontally or vertically.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Box *"
.Fn AG_BoxNew "AG_Widget *parent" "enum ag_box_type type" "Uint flags"
.Pp
.Ft "AG_Box *"
.Fn AG_BoxNewHoriz "AG_Widget *parent" "Uint flags"
.Pp
.Ft "AG_Box *"
.Fn AG_BoxNewVert "AG_Widget *parent" "Uint flags"
.Pp
.Ft "AG_Box *"
.Fn AG_BoxNewHorizNS "AG_Widget *parent" "Uint flags"
.Pp
.Ft "AG_Box *"
.Fn AG_BoxNewVertNS "AG_Widget *parent" "Uint flags"
.Pp
.Ft void
.Fn AG_BoxSetLabel "AG_Box *box" "const char *format" "..."
.Pp
.Ft void
.Fn AG_BoxSetHomogenous "AG_Box *box" "int homogenous"
.Pp
.Ft void
.Fn AG_BoxSetPadding "AG_Box *box" "int padding"
.Pp
.Ft void
.Fn AG_BoxSetSpacing "AG_Box *box" "int spacing"
.Pp
.Ft void
.Fn AG_BoxSetDepth "AG_Box *box" "int depth"
.Pp
.nr nS 0
The
.Fn AG_BoxNew
function allocates, initializes, and attaches a new
.Nm
widget.
The
.Fa type
argument defines the packing as
.Dv AG_BOX_HORIZ
or
.Dv AG_BOX_VERT .
Acceptable
.Fa flags
include:
.Pp
.Bl -tag -width "AG_BOX_HOMOGENOUS "
.It AG_BOX_HOMOGENOUS
Divide space into equal parts.
.It AG_BOX_FRAME
Draw a decorative frame by default.
This flag is implied if a caption text is set.
.El
.Pp
The
.Fn AG_BoxNewHoriz
and
.Fn AG_BoxNewVert
variants are equivalent to setting
.Dv AG_BOX_HORIZ
and
.Dv AG_BOX_VERT .
The
.Fn AG_BoxNewHorizNS
and
.Fn AG_BoxNewVertNS
(no spacing) variants implicitely set default padding and spacing parameters
to 0 pixels.
.Pp
The
.Fn AG_BoxSetLabel
function configures a text label to display over the container.
.Pp
The
.Fn AG_BoxSetHomogenous
function sets/clears the
.Dv AG_BOX_HOMOGENOUS
flag, which controls whether available space is divided evenly between widgets.
.Pp
The
.Fn AG_BoxSetPadding
function sets the padding around the group of child widgets to
.Fa padding
pixels.
.Fn AG_BoxSetSpacing
sets the spacing between individual child widgets to
.Fa spacing
pixels.
.Pp
Assuming that the
.Dv AG_BOX_FRAME
flag was given,
.Fn AG_BoxSetDepth
sets the depth of the frame.
.Sh EVENTS
The
.Nm
widget neither reacts to nor generates any event.
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.