Provided by: libprima-perl_1.28-1.4_amd64 
NAME
Prima::Notebooks - multipage widgets
DESCRIPTION
The module contains several widgets useful for organizing multipage ( notebook )
containers. "Prima::Notebook" provides basic functionality of a widget container.
"Prima::TabSet" is a page selector control, and "Prima::TabbedNotebook" combines these two
into a ready-to-use multipage control with interactive navigation.
SYNOPSIS
my $nb = Prima::TabbedNotebook-> create(
tabs => [ 'First page', 'Second page', 'Second page' ],
);
$nb-> insert_to_page( 1, 'Prima::Button' );
$nb-> insert_to_page( 2, [
[ 'Prima::Button', bottom => 10 ],
[ 'Prima::Button', bottom => 150 ],
]);
$nb-> Notebook-> backColor( cl::Green );
Prima::Notebook
Properties
Provides basic widget container functionality. Acts as merely a grouping widget, hiding
and showing the children widgets when "pageIndex" property is changed.
defaultInsertPage INTEGER
Selects the page where widgets, attached by "insert" call are assigned to. If set to
"undef", the default page is the current page.
Default value: "undef".
pageCount INTEGER
Selects number of pages. If the number of pages is reduced, the widgets that belong to
the rejected pages are removed from the notebook's storage.
pageIndex INTEGER
Selects the index of the current page. Valid values are from 0 to "pageCount - 1".
Methods
attach_to_page INDEX, @WIDGETS
Attaches list of WIDGETS to INDEXth page. The widgets are not necessarily must be
children of the notebook widget. If the page is not current, the widgets get hidden
and disabled; otherwise their state is not changed.
contains_widget WIDGET
Searches for WIDGET in the attached widgets list. If found, returns two integers:
location page index and widget list index. Otherwise returns an empty list.
delete_page [ INDEX = -1, REMOVE_CHILDREN = 1 ]
Deletes INDEXth page, and detaches the widgets associated with it. If REMOVE_CHILDREN
is 1, the detached widgets are destroyed.
delete_widget WIDGET
Detaches WIDGET from the widget list and destroys the widget.
detach_from_page WIDGET
Detaches WIDGET from the widget list.
insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
Creates one or more widgets with "owner" property set to the caller widget, and
returns the list of references to the newly created widgets.
See "insert" in Prima::Widget for details.
insert_page [ INDEX = -1 ]
Inserts a new empty page at INDEX. Valid range is from 0 to "pageCount"; setting INDEX
equal to "pageCount" is equivalent to appending a page to the end of the page list.
insert_to_page INDEX, CLASS, %PROFILE, [[ CLASS, %PROFILE], ... ]
Inserts one ore more widgets to INDEXth page. The semantics of setting CLASS and
PROFILE, as well as the return values are fully equivalent to "insert" method.
See "insert" in Prima::Widget for details.
insert_transparent CLASS, %PROFILE, [[ CLASS, %PROFILE], ... ]
Inserts one or more widgets to the notebook widget, but does not add widgets to the
widget list, so the widgets are not flipped together with pages. Useful for setting
omnipresent ( or transparent ) widgets, visible on all pages.
The semantics of setting CLASS and PROFILE, as well as the return values are fully
equivalent to "insert" method.
See "insert" in Prima::Widget for details.
move_widget WIDGET, INDEX
Moves WIDGET from its old page to INDEXth page.
widget_get WIDGET, PROPERTY
Returns PROPERTY value of WIDGET. If PROPERTY is affected by the page flipping
mechanism, the internal flag value is returned instead.
widget_set WIDGET, %PROFILE
Calls "set" on WIDGET with PROFILE and updates the internal "visible", "enabled",
"current", and "geometry" properties if these are present in PROFILE.
See "set" in Prima::Object.
widgets_from_page INDEX
Returns list of widgets, associated with INDEXth page.
Events
Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
Called when "pageIndex" value is changed from OLD_PAGE_INDEX to NEW_PAGE_INDEX.
Current implementation invokes this notification while the notebook widget is in
locked state, so no redraw requests are honored during the notification execution.
Bugs
Since the notebook operates directly on children widgets' "::visible" and "::enable"
properties, there is a problem when a widget associated with a non-active page must be
explicitly hidden or disabled. As a result, such a widget would become visible and enabled
anyway. This happens because Prima API does not cache property requests. For example,
after execution of the following code
$notebook-> pageIndex(1);
my $widget = $notebook-> insert_to_page( 0, ... );
$widget-> visible(0);
$notebook-> pageIndex(0);
$widget will still be visible. As a workaround, "widget_set" method can be suggested, to
be called together with the explicit state calls. Changing
$widget-> visible(0);
code to
$notebook-> widget_set( $widget, visible => 0);
solves the problem, but introduces an inconsistency in API.
Prima::TabSet
"Prima::TabSet" class implements functionality of an interactive page switcher. A widget
is presented as a set of horizontal bookmark-styled tabs with text identifiers.
Properties
colored BOOLEAN
A boolean property, selects whether each tab uses unique color ( OS/2 Warp 4 style ),
or all tabs are drawn with "backColor".
Default value: 1
firstTab INTEGER
Selects the first ( leftmost ) visible tab.
focusedTab INTEGER
Selects the currently focused tab. This property value is almost always equals to
"tabIndex", except when the widget is navigated by arrow keys, and tab selection does
not occur until the user presses the return key.
topMost BOOLEAN
Selects the way the widget is oriented. If 1, the widget is drawn as if it resides on
top of another widget. If 0, it is drawn as if it is at bottom.
Default value: 1
tabIndex INDEX
Selects the INDEXth tab. When changed, "Change" notification is triggered.
tabs ARRAY
Anonymous array of text scalars. Each scalar corresponds to a tab and is displayed
correspondingly. The class supports single-line text strings only; newline characters
are not respected.
Methods
get_item_width INDEX
Returns width in pixels of INDEXth tab.
tab2firstTab INDEX
Returns the index of a tab, that will be drawn leftmost if INDEXth tab is to be
displayed.
Events
Change
Triggered when "tabIndex" property is changed.
DrawTab CANVAS, INDEX, COLOR_SET, POLYGON1, POLYGON2
Called when INDEXth tab is to be drawn on CANVAS. COLOR_SET is an array reference, and
consists of the four cached color values: foreground, background, dark 3d color, and
light 3d color. POLYGON1 and POLYGON2 are array references, and contain four points as
integer pairs in (X,Y)-coordinates. POLYGON1 keeps coordinates of the larger polygon
of a tab, while POLYGON2 of the smaller. Text is displayed inside the larger polygon:
POLYGON1
[2,3] [4,5]
o..........o
. .
[0,1]. TAB_TEXT . [6,7]
o................o
POLYGON2
[0,1] [2,3]
o................o
[6,7]o..............o[4,5]
Depending on "topMost" property value, POLYGON1 and POLYGON2 change their mutual
vertical orientation.
The notification is always called from within "begin_paint/end_paint" block.
MeasureTab INDEX, REF
Puts width of INDEXth tab in pixels into REF scalar value. This notification must be
called from within "begin_paint_info/end_paint_info" block.
Prima::TabbedNotebook
The class combines functionality of "Prima::TabSet" and "Prima::Notebook", providing the
interactive multipage widget functionality. The page indexing scheme is two-leveled: the
first level is equivalent to the "Prima::TabSet" - provided tab scheme. Each first-level
tab, in turn, contains one or more second-level pages, which can be switched using native
"Prima::TabbedNotebook" controls.
First-level tab is often referred as tab, and second-level as page.
Properties
defaultInsertPage INTEGER
Selects the page where widgets, attached by "insert" call are assigned to. If set to
"undef", the default page is the current page.
Default value: "undef".
notebookClass STRING
Assigns the notebook widget class.
Create-only property.
Default value: "Prima::Notebook"
notebookProfile HASH
Assigns hash of properties, passed to the notebook widget during the creation.
Create-only property.
notebookDelegations ARRAY
Assigns list of delegated notifications to the notebook widget.
Create-only property.
orientation INTEGER
Selects one of the following tno::XXX constants
tno::Top
The TabSet will be drawn at the top of the widget.
tno::Bottom
The TabSet will be drawn at the bottom of the widget.
Default value: tno::Top
pageIndex INTEGER
Selects the INDEXth page or a tabset widget ( the second-level tab ). When this
property is triggered, "tabIndex" can change its value, and "Change" notification is
triggered.
style INTEGER
Selects one of the following tns::XXX constants
tns::Standard
The widget will have a raised border surrounding it and a +/- control at the top
for moving between pages.
tns::Simple
The widget will have no decorations (other than a standard border). It is
recommended to have only one second-level page per tab with this style.
Default value: tns::Standard
tabIndex INTEGER
Selects the INDEXth tab on a tabset widget using the first-level tab numeration.
tabs ARRAY
Governs number and names of notebook pages. ARRAY is an anonymous array of text
scalars, where each corresponds to a single first-level tab and a single notebook
page, with the following exception. To define second-level tabs, the same text string
must be repeated as many times as many second-level tabs are desired. For example, the
code
$nb-> tabs('1st', ('2nd') x 3);
results in creation of a notebook of four pages and two first-level tabs. The tab
'2nd' contains three second-level pages.
The property implicitly operates the underlying notebook's "pageCount" property. When
changed at run-time, its effect on the children widgets is therefore the same. See
pageCount for more information.
tabsetClass STRING
Assigns the tab set widget class.
Create-only property.
Default value: "Prima::TabSet"
tabsetProfile HASH
Assigns hash of properties, passed to the tab set widget during the creation.
Create-only property.
tabsetDelegations ARRAY
Assigns list of delegated notifications to the tab set widget.
Create-only property.
Methods
The class forwards the following methods of "Prima::Notebook", which are described in
Prima::Notebook: "attach_to_page", "insert_to_page", "insert", "insert_transparent",
"delete_widget", "detach_from_page", "move_widget", "contains_widget", "widget_get",
"widget_set", "widgets_from_page".
tab2page INDEX
Returns second-level tab index, that corresponds to the INDEXth first-level tab.
page2tab INDEX
Returns first-level tab index, that corresponds to the INDEXth second-level tab.
Events
Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
Triggered when "pageIndex" property is changes it s value from OLD_PAGE_INDEX to
NEW_PAGE_INDEX.
AUTHORS
Dmitry Karasik, <dmitry@karasik.eu.org>. Teo Sankaro, <teo_sankaro@hotmail.com>.
SEE ALSO
Prima, Prima::Widget, examples/notebook.pl.