.\" Copyright (c) 2006-2022 Julien Nadeau Carriere .\" 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_PANE 3 .Os Agar 1.7 .Sh NAME .Nm AG_Pane .Nd agar paned container widget .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/AG_Pane.png, "A horizontal pane with a vertical sub-pane on the left") The .Nm container divides its allocated space into two partitions (general-purpose .Xr AG_Box 3 containers) horizontally or vertically. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Xr AG_Widget 3 -> .Nm . .Sh INITIALIZATION .nr nS 1 .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 x" .Pp .Ft "int" .Fn AG_PaneMoveDividerPct "AG_Pane *pane" "int pct" .Pp .Ft "void" .Fn AG_PaneResizeAction "AG_Pane *pane" "enum ag_pane_resize_action resizeAction" .Pp .nr nS 0 The .Fn AG_PaneNewHoriz and .Fn AG_PaneNewVert functions allocate, initialize, and attach a new .Nm container, dividing space in the specified orientation. .Pp Acceptable .Fa flags include: .Bl -tag -width "AG_PANE_UNMOVABLE " .It AG_PANE_DIV1FILL By default, the size of the first (left or top) division is computed from its child widgets, and the second division is sized to use the remaining space. This option arranges for the first division to be sized from the remaining space instead. .It AG_PANE_FRAME Render decorative frames. .It AG_PANE_UNMOVABLE Do not allow the user to move the divider. .It AG_PANE_HFILL Expand horizontally in parent container. .It AG_PANE_VFILL Expand vertically in parent container. .It AG_PANE_EXPAND Shorthand for .Dv AG_PANE_HFILL | AG_PANE_VFILL . .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. If the argument is 0 then the divider will be invisible and not selectable. If the argument is -1, reset to default (which is based on the zoom level). .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 .Fa x (in pixels) and returns the actual new position. Note that .Fn AG_PaneMoveDivider will not have any effect if any of the .Dv AG_PANE_FORCE_* options are set. .Pp The .Fn AG_PaneMoveDividerPct variant accepts an argument in % of total available size. If .Fn AG_PaneResizeAction is used with .Dv AG_PANE_DIVIDE_PCT , this percentage is preserved through resizing. .Pp .Fn AG_PaneResizeAction specifies the behavior of .Nm following a resize of the parent container widget. Possible arguments include: .Pp .Bl -tag -compact -width "AG_PANE_EXPAND_DIV1 " .It AG_PANE_EXPAND_DIV1 Expand or shrink the left/upper division (default). .It AG_PANE_EXPAND_DIV2 Expand or shrink the right/lower division. .It AG_PANE_DIVIDE_EVEN Divide the space evenly in two. .It AG_PANE_DIVIDE_PCT Divide the space by the percentage value specified in .Fn AG_PaneMoveDividerPct . .El .Sh EVENTS The .Nm widget does not generate any event. .Sh STRUCTURE DATA For the .Ft AG_Pane object: .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 EXAMPLES The following code fragment displays two expanded, multi-line .Xr AG_Textbox 3 widgets, separated horizontally by a .Nm . .Bd -literal -offset indent .\" SYNTAX(c) AG_Window *win; AG_Pane *pane; AG_Textbox *textbox[2]; win = AG_WindowNew(0); pane = AG_PaneNewVert(win, AG_PANE_EXPAND); textbox[0] = AG_TextboxNew(pane->div[0], AG_TEXTBOX_MULTILINE|AG_TEXTBOX_EXPAND, NULL); textbox[1] = AG_TextboxNew(pane->div[1], AG_TEXTBOX_MULTILINE|AG_TEXTBOX_EXPAND, NULL); AG_PaneMoveDividerPct(pane, 50); AG_WindowShow(win); .Ed .Sh SEE ALSO .Xr AG_Box 3 , .Xr AG_Intro 3 , .Xr AG_MPane 3 , .Xr AG_Widget 3 , .Xr AG_Window 3 .Sh HISTORY The .Nm widget first appeared in Agar 1.0.