Prima::Notebooks - multipage widgets
|
Prima::Notebooks - multipage widgets
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.
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 );
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
.
- 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 the Prima::Widget manpage 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 the Prima::Widget manpage 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 the Prima::Widget manpage 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 the Prima::Object manpage.
- widgets_from_page INDEX
-
Returns list of widgets, associated with INDEXth page.
- 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.
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
class implements functionality of an interactive
page switcher. A widget is presented as a set of horizontal
bookmark-styled tabs with text identifiers.
- 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.
- 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.
- insert_tab TEXT, [ POSITION = -1 ]
-
Inserts a new tab text at the given position, which is at the end by default
- delete_tab POSITION
-
Removes a tab from the given position
- 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.
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.
- 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.
The class forwards the following methods of Prima::Notebook
, which are
described in the Prima::Notebook manpage: 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.
- insert_page TEXT, [ POSITION = -1 ]
-
Inserts a new page with text at the given position, which is at the end by default.
If TEXT is same as the existing tab left or right from POSITION, the page is joined
the existing tab; otherwise a new tab is created.
- delete_page POSITION
-
Removes a page from the given position.
- Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
-
Triggered when
pageIndex
property is changes it s value from OLD_PAGE_INDEX
to NEW_PAGE_INDEX.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Teo Sankaro, <teo_sankaro@hotmail.com>.
Prima, the Prima::Widget manpage, examples/notebook.pl.
Prima::Notebooks - multipage widgets
|