.\" Copyright (c) 2002-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" 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 December 21, 2022
.Dt AG_BOX 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Box
.Nd agar box container widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(/widgets/AG_Box.png, "A horizontal box (top), and a vertical box (right)")
.Nm
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.
.Pp
Widgets with
.Dv AG_WIDGET_HFILL
expand horizontally to fill remaining space.
Widgets with
.Dv AG_WIDGET_VFILL
expand vertically to fill remaining space.
.Pp
Horizontal boxes allow only up to 1 widget with
.Dv AG_WIDGET_HFILL
(and any number with
.Dv AG_WIDGET_VFILL ) .
.Pp
Vertical boxes allow only up to 1 widget with
.Dv AG_WIDGET_VFILL
(and any number with
.Dv AG_WIDGET_HFILL ) .
.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 void
.Fn AG_BoxSetLabel "AG_Box *box" "const char *format" "..."
.Pp
.Ft void
.Fn AG_BoxSetLabelS "AG_Box *box" "const char *text"
.Pp
.Ft void
.Fn AG_BoxSizeHint "AG_Box *box" "int width" "int height"
.Pp
.Ft void
.Fn AG_BoxSetHomogenous "AG_Box *box" "int homogenous"
.Pp
.Ft void
.Fn AG_BoxSetDepth "AG_Box *box" "int depth"
.Pp
.Ft void
.Fn AG_BoxSetHorizAlign "AG_Box *box" "enum ag_box_align align"
.Pp
.Ft void
.Fn AG_BoxSetVertAlign "AG_Box *box" "enum ag_box_align align"
.Pp
.nr nS 0
.Fn AG_BoxNew
allocates, initializes, and attaches a new
.Nm
container.
.Fa type
can be
.Dv AG_BOX_HORIZ
for horizontal packing
.Dv AG_BOX_VERT
for vertical packing.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_BOX_HOMOGENOUS "
.It AG_BOX_HOMOGENOUS
Divide space into equal parts.
.It AG_BOX_SHADING
Show 3D-style shading even if no "background-color".
.It AG_BOX_HFILL
Expand horizontally in parent container.
.It AG_BOX_VFILL
Expand vertically in parent container.
.It AG_BOX_EXPAND
Shorthand for
.Dv AG_BOX_HFILL | AG_BOX_VFILL .
.It AG_BOX_NO_SPACING
Set "padding" and "spacing" style attributes to "0".
.El
.Pp
The
.Fn AG_BoxNewHoriz
and
.Fn AG_BoxNewVert
variants are equivalent to setting
.Dv AG_BOX_HORIZ
and
.Dv AG_BOX_VERT .
.Pp
.Fn AG_BoxSetStyle
selects an alternate background and border style:
.Pp
.Bl -tag -compact -width "AG_BOX_STYLE_PLAIN "
.It Dv AG_BOX_STYLE_NONE
No background.
.It Dv AG_BOX_STYLE_BOX
Raised box & border.
.It Dv AG_BOX_STYLE_WELL
3D well & border (the default).
.It Dv AG_BOX_STYLE_PLAIN
Filled rectangle.
.El
.Pp
Visible background styles use the style attributes "background-color",
"low-color" and "high-color".
.Pp
.Fn AG_BoxSetLabel
arranges for a text label to be displayed over the container.
If an argument of NULL is passed, the label is removed.
.Pp
.Fn AG_BoxSizeHint
sets a specific size requisition in pixels (-1 = auto).
The default is determined by the size requisition of attached widgets.
.Pp
.Fn AG_BoxSetHomogenous
sets or clears the
.Dv AG_BOX_HOMOGENOUS
flag, which controls whether available space is divided evenly between widgets.
.Pp
.Fn AG_BoxSetDepth
sets the depth of the shading for
.Dv AG_BOX_SHADING .
.Pp
.Fn AG_BoxSetHorizAlign
and
.Fn AG_BoxSetVertAlign
specify the horizontal or vertical alignment of widgets.
Horizontal alignment can be
.Dv AG_BOX_LEFT
(default),
.Dv AG_BOX_CENTER
or
.Dv AG_BOX_RIGHT .
Vertical alignment can be
.Dv AG_BOX_TOP
(default),
.Dv AG_BOX_CENTER
or
.Dv AG_BOX_BOTTOM .
.Sh EVENTS
The
.Nm
widget does not generate any event.
.Sh STRUCTURE DATA
For the
.Ft AG_Box
object:
.Bl -tag -width "enum ag_box_style style "
.It Ft enum ag_box_style style
Background style (see
.Fn AG_BoxSetStyle ) .
.El
.Sh EXAMPLES
The following code fragment packs two columns of buttons:
.Bd -literal -offset indent
.\" SYNTAX(c)
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);
.Ed
.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.
In Agar 1.6.0, the
.Fn AG_BoxSetPadding
and
.Fn AG_BoxSetSpacing
functions were deprecated in favor of the generic "padding" and "spacing"
style attributes.