.\" 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_NOTEBOOK 3 .Os Agar 1.7 .Sh NAME .Nm AG_Notebook .Nd agar notebook container widget .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/AG_Notebook.png, "A notebook with 3 tabs") The .Nm widget maintains a set of .Xr AG_Box 3 containers, only one of which is visible at any given time. The user can select the visible container by clicking on a tab, or it can be selected programmatically. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Xr AG_Widget 3 -> .Nm . .Sh INITIALIZATION .nr nS 1 .Ft "AG_Notebook *" .Fn AG_NotebookNew "AG_Widget *parent" "Uint flags" .Pp .Ft "void" .Fn AG_NotebookSetPadding "AG_Notebook *nb" "int padding" .Pp .Ft "void" .Fn AG_NotebookSetSpacing "AG_Notebook *nb" "int spacing" .Pp .Ft "void" .Fn AG_NotebookSetTabAlignment "AG_Notebook *nb" "enum ag_notebook_tab_alignment alignment" .Pp .Ft "void" .Fn AG_NotebookSetTabVisibility "AG_Notebook *nb" "int flag" .Pp .nr nS 0 The .Fn AG_NotebookNew function allocates, initializes, and attaches a new .Nm widget. Acceptable .Fa flags include: .Bl -tag -width "AG_NOTEBOOK_HIDE_TABS " .It AG_NOTEBOOK_HIDE_TABS Don't display the tab selector controls. .It AG_NOTEBOOK_HFILL Expand horizontally in parent container. .It AG_NOTEBOOK_VFILL Expand vertically in parent container. .It AG_NOTEBOOK_EXPAND Shorthand for .Dv AG_NOTEBOOK_HFILL | AG_NOTEBOOK_VFILL . .El .Pp .Fn AG_NotebookSetPadding and .Fn AG_NotebookSetSpacing sets the default .Xr AG_Box 3 padding and spacing to use for new tabs. .Pp By default, tabs are drawn at the top of the widget. .Fn AG_NotebookSetTabAlignment changes the location of the tabs, where the argument is one of: .Bd -literal .\" SYNTAX(c) enum ag_notebook_tab_alignment { AG_NOTEBOOK_TABS_TOP, AG_NOTEBOOK_TABS_BOTTOM, AG_NOTEBOOK_TABS_LEFT, AG_NOTEBOOK_TABS_RIGHT }; .Ed .Pp .Fn AG_NotebookSetTabVisibility toggles the visibility of the tab header. .Sh TAB MANAGEMENT .nr nS 1 .Ft "AG_NotebookTab *" .Fn AG_NotebookAdd "AG_Notebook *nb" "const char *name" "enum ag_box_type type" .Pp .Ft "void" .Fn AG_NotebookDel "AG_Notebook *nb" "AG_NotebookTab *tab" .Pp .Ft "AG_NotebookTab *" .Fn AG_NotebookGetByID "AG_Notebook *nb" "int tabID" .Pp .Ft "AG_NotebookTab *" .Fn AG_NotebookGetByName "AG_Notebook *nb" "const char *text" .Pp .Ft "void" .Fn AG_NotebookSelect "AG_Notebook *nb" "AG_NotebookTab *tab" .Pp .Ft "void" .Fn AG_NotebookSelectByID "AG_Notebook *nb" "int id" .Pp .nr nS 0 .Fn AG_NotebookAdd creates a new tabbed container. .Fa name is an arbitrary text label to be displayed on the tab header. The .Fa type argument sets the type of .Xr AG_Box 3 , that is either for .Dv AG_BOX_HORIZ horizontal packing, or .Dv AG_BOX_VERT for vertical packing (see .Xr AG_Box 3 for details). .Fn AG_NotebookAdd returns a pointer to the newly created .Ft AG_NotebookTab container widget (a subclass of .Xr AG_Box 3 ) . .Pp .Fn AG_NotebookDel removes the given tabbed container, detaching and freeing all associated child widgets. .Pp .Fn AG_NotebookGetByID returns the tab with given numerical ID (or NULL). .Pp .Fn AG_NotebookGetByName looks up a tab based on the contents of its text label and returns a pointer to the tab (or NULL). .Pp The .Fn AG_NotebookSelect function selects the active tabbed container. .Pp .Fn AG_NotebookSelectByID selects the container by numerical ID. .Sh EVENTS The .Nm widget does not generate any event. .Sh STRUCTURE DATA For the .Ft AG_Notebook object: .Pp .Bl -tag -width "AG_NotebookTab *selTab " -compact .It Ft TAILQ tabs The list of tabs as .Ft AG_NotebookTab objects. .It Ft Uint nTabs Total number of tabs. .It Ft AG_NotebookTab *selTab Pointer to the currently selected tab. .It Ft int selTabID Numerical ID of currently selected tab. .El .Pp For the .Ft AG_NotebookTab object: .Pp .Bl -tag -width "AG_Label *lbl " -compact .It Ft AG_Label *lbl Pointer to the .Xr AG_Label 3 of the tab (or NULL). .It Ft int id The numerical ID associated with the tab. .El .Sh EXAMPLES The following code fragment creates a notebook with two tabs: .Bd -literal -offset indent .\" SYNTAX(c) AG_Notebook *nb; AG_Notebook *ntab; nb = AG_NotebookNew(parent, AG_NOTEBOOK_EXPAND); { ntab = AG_NotebookAdd(nb, "Tab #1", AG_BOX_VERT); AG_LabelNew(ntab, 0, "This is Tab #1"); ntab = AG_NotebookAdd(nb, "Tab #2", AG_BOX_VERT); AG_LabelNew(ntab, 0, "This is Tab #2"); } .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. .Fn AG_NotebookGetByID and .Fn AG_NotebookSelectByID appeared in Agar 1.6.0.