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.
use Prima qw(Notebooks Buttons Application);
my $nb = Prima::TabbedNotebook-> new(
tabs => [ 'First page', 'Second page', 'Second page' ],
size => [ 300, 200 ],
$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.
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.
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.
Selects the index of the current page. Valid values are from 0 to pageCount - 1.
pageCount - 1
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.
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.
Deletes INDEXth page, and detaches the widgets associated with it. If REMOVE_CHILDREN is 1, the detached widgets are destroyed.
Detaches WIDGET from the widget list and destroys the widget.
Detaches WIDGET from the widget list.
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.
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.
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.
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.
Moves WIDGET from its old page to INDEXth page.
Returns PROPERTY value of WIDGET. If PROPERTY is affected by the page flipping mechanism, the internal flag value is returned instead.
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.
Returns list of widgets, associated with INDEXth page.
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
my $widget = $notebook-> insert_to_page( 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
$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.
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
Allows to specify custom colors for the tabs.
Used only when colored is set to 1.
Selects the first ( leftmost ) visible tab.
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.
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.
Selects the INDEXth tab. When changed, Change notification is triggered.
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.
Returns width in pixels of INDEXth tab.
Returns the index of a tab, that will be drawn leftmost if INDEXth tab is to be displayed.
Inserts a new tab text at the given position, which is at the end by default
Removes a tab from the given position
Triggered when tabIndex property is changed.
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:
[0,1]. TAB_TEXT . [6,7]
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.
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.
The class forwards the following properties of Prima::TabSet, which are described in Prima::TabSet: colored, colorset
Assigns the notebook widget class.
Default value: Prima::Notebook
Assigns hash of properties, passed to the notebook widget during the creation.
Assigns list of delegated notifications to the notebook widget.
Selects one of the following tno::XXX constants
The TabSet will be drawn at the top of the widget.
The TabSet will be drawn at the bottom of the widget.
Default value: tno::Top
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.
Selects one of the following tns::XXX constants
The widget will have a raised border surrounding it and a +/- control at the top for moving between pages.
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
Selects the INDEXth tab on a tabset widget using the first-level tab numeration.
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.
Assigns the tab set widget class.
Default value: Prima::TabSet
Assigns hash of properties, passed to the tab set widget during the creation.
Assigns list of delegated notifications to the tab set widget.
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.
Returns second-level tab index, that corresponds to the INDEXth first-level tab.
Returns first-level tab index, that corresponds to the INDEXth second-level tab.
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.
Removes a page from the given position.
Triggered when pageIndex property is changes it s value from OLD_PAGE_INDEX to NEW_PAGE_INDEX.
Dmitry Karasik, <firstname.lastname@example.org>. Teo Sankaro, <email@example.com>.
Prima, Prima::Widget, examples/notebook.pl.
To install Prima, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.