.\" Copyright (c) 2006-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 August 28, 2006
.Dt AG_PANE 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Pane
.Nd agar paned container widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
widget is a dual container widget with a separator that is (by default)
movable by the user.
The two partitions are general-purpose
.Xr AG_Box 3
containers.
Depending on the application, partitions may or may not be allowed to shrink
to zero size.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Pane *"
.Fn AG_PaneNew "AG_Widget *parent" "enum ag_pane_type type" "Uint flags"
.Pp
.Ft "AG_Pane *"
.Fn AG_PaneNewHoriz "AG_Widget *parent" "Uint flags"
.Pp
.Ft "AG_Pane *"
.Fn AG_PaneNewVert "AG_Widget *parent" "Uint flags"
.Pp
.Ft "void"
.Fn AG_PaneAttachBox "AG_Pane *pane" "int which" "AG_Box *box"
.Pp
.Ft "void"
.Fn AG_PaneAttachBoxes "AG_Pane *pane" "AG_Box *box1" "AG_Box *box2"
.Pp
.Ft "void"
.Fn AG_PaneSetDividerWidth "AG_Pane *pane" "int pixels"
.Pp
.Ft "void"
.Fn AG_PaneSetDivisionMin "AG_Pane *pane" "int which" "int min_w" "int min_h"
.Pp
.Ft "int"
.Fn AG_PaneMoveDivider "AG_Pane *pane" "int dx"
.Pp
.nr nS 0
The
.Fn AG_PaneNew
function allocates, initializes, and attaches a new
.Nm
widget.
The
.Fa type
argument is one of:
.Pp
.Bd -literal
enum ag_pane_type {
	AG_PANE_HORIZ,
	AG_PANE_VERT
};
.Ed
.Pp
The
.Fa flags
may include:
.Pp
.Bl -tag -width "AG_PANE_FORCE_DIV "
.It AG_PANE_DIV1FILL
Allocate the preferred size for the second division, and allocate the
remaining space to the first division (default is the other way around).
.It AG_PANE_FRAME
Render decorative frames.
.It AG_PANE_DIV
Ignore the preferred sizes and divide into two equal parts.
.It AG_PANE_FORCE_DIV
Don't allow the user to move the divider.
.El
.Pp
If
.Dv AG_PANE_FRAME
is set, the depth of the frame can be adjusted by invoking
.Xr AG_BoxSetDepth 3
on the partitions.
.Pp
By default, the two
.Xr AG_Box 3
sub-containers of
.Nm
are created automatically.
.Fn AG_PaneAttachBox
allows existing boxes to be attached and re-used.
.Fa which
must be 0 or 1.
.Fn AG_PaneAttachBoxes
is a variant that accepts two box arguments.
.Pp
.Fn AG_PaneSetDividerWidth
sets the width of the divider widget in pixels.
.Pp
By default, the user is allowed to move the separator such that one of the
two partitions can be shrunk to zero.
.Fn AG_PaneSetDivisionMin
prevents this by setting a minimal geometry in pixels for the given partition
.Fa which
(which must be either 0 or 1).
If the value -1 is given, no minimum is set.
.Pp
The separator can also be moved programmatically with the
.Fn AG_PaneMoveDivider
function.
.Fn AG_PaneMoveDivider
tries to move the divider to the specified position and returns the actual
new position.
.Sh EVENTS
The
.Nm
widget reacts to the following events:
.Pp
.Bl -tag -compact -width "window-mousebuttondown "
.It window-mousemotion
.It window-mousebuttonup
.It window-mousebuttondown
Move the separator, resizing the partitions.
.El
.Pp
The
.Nm
widget does not generate any event.
.Sh STRUCTURE DATA
For the
.Ft AG_Pane
object:
.Pp
.Bl -tag -width "AG_Box *div[2] "
.It Ft AG_Box *div[2]
Division containers (assuming that
.Fn AG_PaneAttachBox
was not used).
.It Ft int dmoving
Divider is currently being moved by the user (read-only).
.It Ft int dx
Actual divider position (read-only)
.El
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Box 3 ,
.Xr AG_MPane 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.