1Prima::Notebooks(3) User Contributed Perl Documentation Prima::Notebooks(3)
2
6 Prima::Notebooks - multipage widgets
7
9 The module contains several widgets useful for organizing multipage (
10 notebook ) containers. "Prima::Notebook" provides basic functionality
11 of a widget container. "Prima::TabSet" is a page selector control, and
12 "Prima::TabbedNotebook" combines these two into a ready-to-use
13 multipage control with interactive navigation.
14
16 use Prima qw(Notebooks Buttons Application);
17 my $nb = Prima::TabbedNotebook-> new(
18 tabs => [ 'First page', 'Second page', 'Second page' ],
19 size => [ 300, 200 ],
20 );
21 $nb-> insert_to_page( 1, 'Prima::Button' );
22 $nb-> insert_to_page( 2,
23 [ 'Prima::Button', bottom => 10 ],
24 [ 'Prima::Button', bottom => 150 ],
25 );
26 $nb-> Notebook-> backColor( cl::Green );
27 run Prima;
28
30 Properties
31 Provides basic widget container functionality. Acts as merely a
32 grouping widget, hiding and showing the children widgets when
33 "pageIndex" property is changed.
34 defaultInsertPage INTEGER
36 Selects the page where widgets, attached by "insert" call are
37 assigned to. If set to "undef", the default page is the current
38 page.
39 Default value: "undef".
41 pageCount INTEGER
43 Selects number of pages. If the number of pages is reduced, the
44 widgets that belong to the rejected pages are removed from the
45 notebook's storage.
46 pageIndex INTEGER
48 Selects the index of the current page. Valid values are from 0 to
49 "pageCount - 1".
50 Methods
52 attach_to_page INDEX, @WIDGETS
53 Attaches list of WIDGETS to INDEXth page. The widgets are not
54 necessarily must be children of the notebook widget. If the page is
55 not current, the widgets get hidden and disabled; otherwise their
56 state is not changed.
57 contains_widget WIDGET
59 Searches for WIDGET in the attached widgets list. If found, returns
60 two integers: location page index and widget list index. Otherwise
61 returns an empty list.
62 delete_page [ INDEX = -1, REMOVE_CHILDREN = 1 ]
64 Deletes INDEXth page, and detaches the widgets associated with it.
65 If REMOVE_CHILDREN is 1, the detached widgets are destroyed.
66 delete_widget WIDGET
68 Detaches WIDGET from the widget list and destroys the widget.
69 detach_from_page WIDGET
71 Detaches WIDGET from the widget list.
72 insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
74 Creates one or more widgets with "owner" property set to the caller
75 widget, and returns the list of references to the newly created
76 widgets.
77 See "insert" in Prima::Widget for details.
79 insert_page [ INDEX = -1 ]
81 Inserts a new empty page at INDEX. Valid range is from 0 to
82 "pageCount"; setting INDEX equal to "pageCount" is equivalent to
83 appending a page to the end of the page list.
84 insert_to_page INDEX, CLASS, %PROFILE, [[ CLASS, %PROFILE], ... ]
86 Inserts one ore more widgets to INDEXth page. The semantics of
87 setting CLASS and PROFILE, as well as the return values are fully
88 equivalent to "insert" method.
89 See "insert" in Prima::Widget for details.
91 insert_transparent CLASS, %PROFILE, [[ CLASS, %PROFILE], ... ]
93 Inserts one or more widgets to the notebook widget, but does not
94 add widgets to the widget list, so the widgets are not flipped
95 together with pages. Useful for setting omnipresent ( or
96 transparent ) widgets, visible on all pages.
97 The semantics of setting CLASS and PROFILE, as well as the return
99 values are fully equivalent to "insert" method.
100 See "insert" in Prima::Widget for details.
102 move_widget WIDGET, INDEX
104 Moves WIDGET from its old page to INDEXth page.
105 widget_get WIDGET, PROPERTY
107 Returns PROPERTY value of WIDGET. If PROPERTY is affected by the
108 page flipping mechanism, the internal flag value is returned
109 instead.
110 widget_set WIDGET, %PROFILE
112 Calls "set" on WIDGET with PROFILE and updates the internal
113 "visible", "enabled", "current", and "geometry" properties if these
114 are present in PROFILE.
115 See "set" in Prima::Object.
117 widgets_from_page INDEX
119 Returns list of widgets, associated with INDEXth page.
120 Events
122 Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
123 Called when "pageIndex" value is changed from OLD_PAGE_INDEX to
124 NEW_PAGE_INDEX. Current implementation invokes this notification
125 while the notebook widget is in locked state, so no redraw requests
126 are honored during the notification execution.
127 Bugs
129 Since the notebook operates directly on children widgets' "::visible"
130 and "::enable" properties, there is a problem when a widget associated
131 with a non-active page must be explicitly hidden or disabled. As a
132 result, such a widget would become visible and enabled anyway. This
133 happens because Prima API does not cache property requests. For
134 example, after execution of the following code
135 $notebook-> pageIndex(1);
137 my $widget = $notebook-> insert_to_page( 0, ... );
138 $widget-> visible(0);
139 $notebook-> pageIndex(0);
140 $widget will still be visible. As a workaround, "widget_set" method can
142 be suggested, to be called together with the explicit state calls.
143 Changing
144 $widget-> visible(0);
146 code to
148 $notebook-> widget_set( $widget, visible => 0);
150 solves the problem, but introduces an inconsistency in API.
152
154 "Prima::TabSet" class implements functionality of an interactive page
155 switcher. A widget is presented as a set of horizontal bookmark-styled
156 tabs with text identifiers.
157 Properties
159 colored BOOLEAN
160 A boolean property, selects whether each tab uses unique color (
161 OS/2 Warp 4 style ), or all tabs are drawn with "backColor".
162 Default value: 1
164 firstTab INTEGER
166 Selects the first ( leftmost ) visible tab.
167 focusedTab INTEGER
169 Selects the currently focused tab. This property value is almost
170 always equals to "tabIndex", except when the widget is navigated by
171 arrow keys, and tab selection does not occur until the user presses
172 the return key.
173 topMost BOOLEAN
175 Selects the way the widget is oriented. If 1, the widget is drawn
176 as if it resides on top of another widget. If 0, it is drawn as if
177 it is at bottom.
178 Default value: 1
180 tabIndex INDEX
182 Selects the INDEXth tab. When changed, "Change" notification is
183 triggered.
184 tabs ARRAY
186 Anonymous array of text scalars. Each scalar corresponds to a tab
187 and is displayed correspondingly. The class supports single-line
188 text strings only; newline characters are not respected.
189 Methods
191 get_item_width INDEX
192 Returns width in pixels of INDEXth tab.
193 tab2firstTab INDEX
195 Returns the index of a tab, that will be drawn leftmost if INDEXth
196 tab is to be displayed.
197 insert_tab TEXT, [ POSITION = -1 ]
199 Inserts a new tab text at the given position, which is at the end
200 by default
201 delete_tab POSITION
203 Removes a tab from the given position
204 Events
206 Change
207 Triggered when "tabIndex" property is changed.
208 DrawTab CANVAS, INDEX, COLOR_SET, POLYGON1, POLYGON2
210 Called when INDEXth tab is to be drawn on CANVAS. COLOR_SET is an
211 array reference, and consists of the four cached color values:
212 foreground, background, dark 3d color, and light 3d color. POLYGON1
213 and POLYGON2 are array references, and contain four points as
214 integer pairs in (X,Y)-coordinates. POLYGON1 keeps coordinates of
215 the larger polygon of a tab, while POLYGON2 of the smaller. Text is
216 displayed inside the larger polygon:
217 POLYGON1
219 [2,3] [4,5]
221 o..........o
222 . .
223 [0,1]. TAB_TEXT . [6,7]
224 o................o
225 POLYGON2
227 [0,1] [2,3]
229 o................o
230 [6,7]o..............o[4,5]
231 Depending on "topMost" property value, POLYGON1 and POLYGON2 change
233 their mutual vertical orientation.
234 The notification is always called from within
236 "begin_paint/end_paint" block.
237 MeasureTab INDEX, REF
239 Puts width of INDEXth tab in pixels into REF scalar value. This
240 notification must be called from within
241 "begin_paint_info/end_paint_info" block.
242
244 The class combines functionality of "Prima::TabSet" and
245 "Prima::Notebook", providing the interactive multipage widget
246 functionality. The page indexing scheme is two-leveled: the first level
247 is equivalent to the "Prima::TabSet" - provided tab scheme. Each first-
248 level tab, in turn, contains one or more second-level pages, which can
249 be switched using native "Prima::TabbedNotebook" controls.
250 First-level tab is often referred as tab, and second-level as page.
252 Properties
254 defaultInsertPage INTEGER
255 Selects the page where widgets, attached by "insert" call are
256 assigned to. If set to "undef", the default page is the current
257 page.
258 Default value: "undef".
260 notebookClass STRING
262 Assigns the notebook widget class.
263 Create-only property.
265 Default value: "Prima::Notebook"
267 notebookProfile HASH
269 Assigns hash of properties, passed to the notebook widget during
270 the creation.
271 Create-only property.
273 notebookDelegations ARRAY
275 Assigns list of delegated notifications to the notebook widget.
276 Create-only property.
278 orientation INTEGER
280 Selects one of the following tno::XXX constants
281 tno::Top
283 The TabSet will be drawn at the top of the widget.
284 tno::Bottom
286 The TabSet will be drawn at the bottom of the widget.
287 Default value: tno::Top
289 pageIndex INTEGER
291 Selects the INDEXth page or a tabset widget ( the second-level tab
292 ). When this property is triggered, "tabIndex" can change its
293 value, and "Change" notification is triggered.
294 style INTEGER
296 Selects one of the following tns::XXX constants
297 tns::Standard
299 The widget will have a raised border surrounding it and a +/-
300 control at the top for moving between pages.
301 tns::Simple
303 The widget will have no decorations (other than a standard
304 border). It is recommended to have only one second-level page
305 per tab with this style.
306 Default value: tns::Standard
308 tabIndex INTEGER
310 Selects the INDEXth tab on a tabset widget using the first-level
311 tab numeration.
312 tabs ARRAY
314 Governs number and names of notebook pages. ARRAY is an anonymous
315 array of text scalars, where each corresponds to a single first-
316 level tab and a single notebook page, with the following exception.
317 To define second-level tabs, the same text string must be repeated
318 as many times as many second-level tabs are desired. For example,
319 the code
320 $nb-> tabs('1st', ('2nd') x 3);
322 results in creation of a notebook of four pages and two first-level
324 tabs. The tab '2nd' contains three second-level pages.
325 The property implicitly operates the underlying notebook's
327 "pageCount" property. When changed at run-time, its effect on the
328 children widgets is therefore the same. See pageCount for more
329 information.
330 tabsetClass STRING
332 Assigns the tab set widget class.
333 Create-only property.
335 Default value: "Prima::TabSet"
337 tabsetProfile HASH
339 Assigns hash of properties, passed to the tab set widget during the
340 creation.
341 Create-only property.
343 tabsetDelegations ARRAY
345 Assigns list of delegated notifications to the tab set widget.
346 Create-only property.
348 Methods
350 The class forwards the following methods of "Prima::Notebook", which
351 are described in Prima::Notebook: "attach_to_page", "insert_to_page",
352 "insert", "insert_transparent", "delete_widget", "detach_from_page",
353 "move_widget", "contains_widget", "widget_get", "widget_set",
354 "widgets_from_page".
355 tab2page INDEX
357 Returns second-level tab index, that corresponds to the INDEXth
358 first-level tab.
359 page2tab INDEX
361 Returns first-level tab index, that corresponds to the INDEXth
362 second-level tab.
363 insert_page TEXT, [ POSITION = -1 ]
365 Inserts a new page with text at the given position, which is at the
366 end by default. If TEXT is same as the existing tab left or right
367 from POSITION, the page is joined the existing tab; otherwise a new
368 tab is created.
369 delete_page POSITION
371 Removes a page from the given position.
372 Events
374 Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
375 Triggered when "pageIndex" property is changes it s value from
376 OLD_PAGE_INDEX to NEW_PAGE_INDEX.
377
379 Dmitry Karasik, <dmitry@karasik.eu.org>. Teo Sankaro,
380 <teo_sankaro@hotmail.com>.
381
383 Prima, Prima::Widget, examples/notebook.pl.
384perl v5.32.0 2020-07-28 Prima::Notebooks(3)