Provided by: libmotif-dev_2.3.8-2build1_amd64 
NAME
XmNotebook — The Notebook widget class "XmNotebook" "widget class" "Notebook"
SYNOPSIS
#include <Xm/Notebook.h>
DESCRIPTION
Notebook is a manager widget that organizes its children into pages, tabs, status areas,
and page scrollers to simulate a real notebook. It stacks its page children so that all
page children occupy the same area like real book pages. Notebook displays visuals that
look like the binding of a book and the edges of other pages around the page that is
shown. Tab children simulate notebook tabs. Major tabs divide Notebook into several
sections, and minor tabs subdivide these sections. Status area children provide additional
information about pages such as page numbers. The page scroller child allows the user to
move from page to page. Notebook also provides tab scrollers for scrolling major and minor
tabs if it cannot display all tabs within its edges.
The application creates pages, tabs, status areas, and page scroller as children of the
Notebook widget. Notebook creates tab scrollers when the Notebook is created.
The XmNnotebookChildType constraint resource of Notebook determines whether a child widget
is a page, tab, status area, or page scroller. Any Motif widget can be a page of the
Notebook. When the application creates a child of the Notebook widget without setting the
child type constraint, the child becomes a page by default, unless it has the
XmQTactivatable, XmQTaccessTextual, or XmQTnavigator trait. Children with the
XmQTactivatable, XmQTaccessTextual, or XmQTnavigator trait become major tabs, status
areas, and page scrollers, respectively.
Notebook uses the XmQTaccessTextual, XmQTactivatable, XmQTjoinSide, and XmQTnavigator
traits, and installs the XmQTscrollFrame trait.
The application attaches a tab to a page by creating a tab child of the Notebook and
setting the XmNpageNumber constraint to the page number of the targeted page. By the same
method, a status area widget can be attached to a page. The page scroller child, on the
other hand, is associated with the Notebook, not with a specific page. Therefore, there is
only one valid page scroller for each Notebook.
Pages
Only one child of type XmPAGE is displayed at a time by Notebook. Other page children are
hidden off-screen. When Notebook displays a particular page, it positions the previously-
displayed page off-screen and puts the new page in its place. The page is resized to fit
into the dimensions that Notebook has allocated to display pages.
Page Numbers
Notebook uses the XmNcurrentPageNumber, XmNfirstPageNumber, and XmNlastPageNumber
resources to determine the current page and available page number range. Only those pages
whose page numbers are within the range can be displayed. Other pages cannot be displayed
until the range between XmNfirstPageNumber and XmNlastPageNumber is changed to include
them or their page numbers are changed to a number within the range.
If XmNfirstPageNumber and XmNlastPageNumber are not set explicitly by the application,
they are set to 1 by default; Notebook sets XmNlastPageNumber to the largest page number
assigned by the application thereafter by default. However, once XmNlastPageNumber is set
by the application, Notebook no longer changes it even when a page with a higher page
number is managed.
The XmNpageNumber constraint resource is used for specifying the page number of a page
widget. It can be set to any integer. For tab and status area children, the resource is
used for linking the child widget to a page. For the page scroller child, the resource
has no meaning and is ignored by the Notebook.
When a page without a page number is managed, Notebook assigns it the smallest unallocated
page number that is not less than the first page number and greater than the last
allocated page number. When a tab or a status area without a page number is managed, the
newly managed widget is assigned the page number of the most recently managed page, unless
the page already has the same type of child. If the page does have the same type of child,
Notebook assigns the newly managed widget a page number one greater than the most recently
managed page; this new page number is now occupied. Notebook may generate a default page
number greater than XmNlastPageNumber, making those pages inaccessible to the user.
Duplicate and Empty Pages
Since an application can create or change page numbers, it is possible to have duplicate
page numbers and empty pages. When two pages with the same page number are managed, only
the more recently managed page can be displayed. Inserting a page with an existing page
number does not cause a warning. The old page widget cannot be displayed until the new
page widget is removed from the Notebook or until the page number of the old page widget
is changed to some other number.
An empty page is a page slot where no page is inserted. Empty pages occur when a tab or
status area is associated with a page number that has no matching page widget. Empty
pages display the blank Notebook background unless the application provides visual
information to this empty area while processing XmNpageChangedCallback.
Notebook Visuals
Notebook draws lines around two sides of the top page to simulate the edges of other pages
that are behind the top page. The XmNbackPagePlacement and XmNorientation resources
determine which two sides have the lines drawn around them. By default, they are drawn on
the bottom and right sides of the top page. The application can set resources to control
how many lines are drawn and how wide the area that they are drawn in is. Applications can
also choose from three styles of binding visual that simulates the binding of a Notebook.
Solid or spiral bindings can be drawn by Notebook, or the application can supply a pixmap
that is tiled into the binding.
Tabs
A major or minor tab is a Motif widget with the XmQTactivatable trait. If a widget
without the trait is created for a tab, Notebook does not provide the page activation
callback. As a result, even though the tab is displayed, it cannot automatically move the
associated page to the top.
Major tabs divide the Notebook pages into sections. Minor tabs subdivide these sections.
Only minor tabs associated with the current section are displayed, where a section
consists of the group of pages between the current major tab and the next major tab,
including the current major tab but not including the page containing the next major tab.
The exception to this is when there is no preceding major tab, in which case the section
starts from the XmNfirstPageNumber value. A user in one major tab section does not see
the minor tabs in other sections. However, all tabs are used in computing the size of the
Notebook.
Unlike regular notebook tabs, tabs in the Notebook are not attached to a physical page (a
widget). They are, instead, attached to a logical page (a page number). Therefore, it is
possible to have a tab with an empty page. When a page with a tab is removed from the
Notebook, the tab is not removed because it is still bound to a logical page. Destroying
or unmanaging a page widget only erases the page and leaves an empty page. It does not
tear the page out of the Notebook. To remove the tab, the application must explicitly
destroy or unmanage it.
Notebook supports the XmQTjoinSide trait. A widget that has the XmQTjoinSide trait can be
added to the Notebook as a Major or Minor tab and will appear to be attached to its
associated page with no margins or shadows between them.
Status Areas
A status area is any widget that is used for describing the associated page. For example,
the Label widget as a status area child can hold a simple string or a pixmap that
describes a page. A status area widget is also attached to a page by the page number
constraint resource. Therefore, it is possible to have multiple status area widgets for
one page. Only the most recently managed status area widget for that page can be
displayed. All others for that page are not unmanaged, but their sizes are used for
computing the size of the Notebook. If no status area widget is provided, the Notebook
displays its blank background in the status area's reserved space. Notebook does not
create any default status area widget.
Page Scrollers
The page scroller of the Notebook is any widget that the application creates for scrolling
pages. If the application does not create one when the Notebook is realized, Notebook
creates a SpinBox widget as the default page scroller. If the application creates a new
page scroller, the default page scroller is destroyed. If the application creates multiple
page scrollers, only the most recently managed one can be displayed and used. All others
are unmanaged.
The default SpinBox page scroller grays out one of the arrow visuals if the current page
is a boundary page. If the current page is the first page, the previous arrow of the
SpinBox is grayed. If the current page is the last page, the next arrow of the SpinBox is
grayed.
Tab Scrollers
Tab scrollers are created by the Notebook for scrolling major tabs and minor tabs. When
Notebook is initialized, it creates four ArrowButtonGadgets for scrolling to the next
major tab, the previous major tab, the next minor tab, and the previous minor tab. The
application cannot replace these tab scrollers. The application can change all resources
of these widgets except the position and the arrow direction. Tab scrollers are only
visible and enabled when there is not enough space to display all the major or minor tabs
appropriate to the page. Tab scrollers are also grayed out when scrolling is
inappropriate. The following lists the tab scrollers that are created:
┌─────────────────────────────────────────────────────────────────────────────┐
--
RELATED
Composite(3), Constraint(3), Core(3), XmCreateNotebook(3), XmManager(3),
XmNotebookGetPageInfo(3), XmVaCreateNotebook(3), and XmVaCreateManagedNotebook(3).
XmNotebook(3)