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 colorset ARRAY
166 Allows to specify custom colors for the tabs.
167 Used only when "colored" is set to 1.
169 firstTab INTEGER
171 Selects the first ( leftmost ) visible tab.
172 focusedTab INTEGER
174 Selects the currently focused tab. This property value is almost
175 always equals to "tabIndex", except when the widget is navigated by
176 arrow keys, and tab selection does not occur until the user presses
177 the return key.
178 topMost BOOLEAN
180 Selects the way the widget is oriented. If 1, the widget is drawn
181 as if it resides on top of another widget. If 0, it is drawn as if
182 it is at bottom.
183 Default value: 1
185 tabIndex INDEX
187 Selects the INDEXth tab. When changed, "Change" notification is
188 triggered.
189 tabs ARRAY
191 Anonymous array of text scalars. Each scalar corresponds to a tab
192 and is displayed correspondingly. The class supports single-line
193 text strings only; newline characters are not respected.
194 Methods
196 get_item_width INDEX
197 Returns width in pixels of INDEXth tab.
198 tab2firstTab INDEX
200 Returns the index of a tab, that will be drawn leftmost if INDEXth
201 tab is to be displayed.
202 insert_tab TEXT, [ POSITION = -1 ]
204 Inserts a new tab text at the given position, which is at the end
205 by default
206 delete_tab POSITION
208 Removes a tab from the given position
209 Events
211 Change
212 Triggered when "tabIndex" property is changed.
213 DrawTab CANVAS, INDEX, COLOR_SET, POLYGON1, POLYGON2
215 Called when INDEXth tab is to be drawn on CANVAS. COLOR_SET is an
216 array reference, and consists of the four cached color values:
217 foreground, background, dark 3d color, and light 3d color. POLYGON1
218 and POLYGON2 are array references, and contain four points as
219 integer pairs in (X,Y)-coordinates. POLYGON1 keeps coordinates of
220 the larger polygon of a tab, while POLYGON2 of the smaller. Text is
221 displayed inside the larger polygon:
222 POLYGON1
224 [2,3] [4,5]
226 o..........o
227 . .
228 [0,1]. TAB_TEXT . [6,7]
229 o................o
230 POLYGON2
232 [0,1] [2,3]
234 o................o
235 [6,7]o..............o[4,5]
236 Depending on "topMost" property value, POLYGON1 and POLYGON2 change
238 their mutual vertical orientation.
239 The notification is always called from within
241 "begin_paint/end_paint" block.
242 MeasureTab INDEX, REF
244 Puts width of INDEXth tab in pixels into REF scalar value. This
245 notification must be called from within
246 "begin_paint_info/end_paint_info" block.
247
249 The class combines functionality of "Prima::TabSet" and
250 "Prima::Notebook", providing the interactive multipage widget
251 functionality. The page indexing scheme is two-leveled: the first level
252 is equivalent to the "Prima::TabSet" - provided tab scheme. Each first-
253 level tab, in turn, contains one or more second-level pages, which can
254 be switched using native "Prima::TabbedNotebook" controls.
255 First-level tab is often referred as tab, and second-level as page.
257 Properties
259 The class forwards the following properties of "Prima::TabSet", which
260 are described in Prima::TabSet: "colored", "colorset"
261 defaultInsertPage INTEGER
263 Selects the page where widgets, attached by "insert" call are
264 assigned to. If set to "undef", the default page is the current
265 page.
266 Default value: "undef".
268 notebookClass STRING
270 Assigns the notebook widget class.
271 Create-only property.
273 Default value: "Prima::Notebook"
275 notebookProfile HASH
277 Assigns hash of properties, passed to the notebook widget during
278 the creation.
279 Create-only property.
281 notebookDelegations ARRAY
283 Assigns list of delegated notifications to the notebook widget.
284 Create-only property.
286 orientation INTEGER
288 Selects one of the following tno::XXX constants
289 tno::Top
291 The TabSet will be drawn at the top of the widget.
292 tno::Bottom
294 The TabSet will be drawn at the bottom of the widget.
295 Default value: tno::Top
297 pageIndex INTEGER
299 Selects the INDEXth page or a tabset widget ( the second-level tab
300 ). When this property is triggered, "tabIndex" can change its
301 value, and "Change" notification is triggered.
302 style INTEGER
304 Selects one of the following tns::XXX constants
305 tns::Standard
307 The widget will have a raised border surrounding it and a +/-
308 control at the top for moving between pages.
309 tns::Simple
311 The widget will have no decorations (other than a standard
312 border). It is recommended to have only one second-level page
313 per tab with this style.
314 Default value: tns::Standard
316 tabIndex INTEGER
318 Selects the INDEXth tab on a tabset widget using the first-level
319 tab numeration.
320 tabs ARRAY
322 Governs number and names of notebook pages. ARRAY is an anonymous
323 array of text scalars, where each corresponds to a single first-
324 level tab and a single notebook page, with the following exception.
325 To define second-level tabs, the same text string must be repeated
326 as many times as many second-level tabs are desired. For example,
327 the code
328 $nb-> tabs('1st', ('2nd') x 3);
330 results in creation of a notebook of four pages and two first-level
332 tabs. The tab '2nd' contains three second-level pages.
333 The property implicitly operates the underlying notebook's
335 "pageCount" property. When changed at run-time, its effect on the
336 children widgets is therefore the same. See pageCount for more
337 information.
338 tabsetClass STRING
340 Assigns the tab set widget class.
341 Create-only property.
343 Default value: "Prima::TabSet"
345 tabsetProfile HASH
347 Assigns hash of properties, passed to the tab set widget during the
348 creation.
349 Create-only property.
351 tabsetDelegations ARRAY
353 Assigns list of delegated notifications to the tab set widget.
354 Create-only property.
356 Methods
358 The class forwards the following methods of "Prima::Notebook", which
359 are described in Prima::Notebook: "attach_to_page", "insert_to_page",
360 "insert", "insert_transparent", "delete_widget", "detach_from_page",
361 "move_widget", "contains_widget", "widget_get", "widget_set",
362 "widgets_from_page".
363 tab2page INDEX
365 Returns second-level tab index, that corresponds to the INDEXth
366 first-level tab.
367 page2tab INDEX
369 Returns first-level tab index, that corresponds to the INDEXth
370 second-level tab.
371 insert_page TEXT, [ POSITION = -1 ]
373 Inserts a new page with text at the given position, which is at the
374 end by default. If TEXT is same as the existing tab left or right
375 from POSITION, the page is joined the existing tab; otherwise a new
376 tab is created.
377 delete_page POSITION
379 Removes a page from the given position.
380 Events
382 Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
383 Triggered when "pageIndex" property is changes it s value from
384 OLD_PAGE_INDEX to NEW_PAGE_INDEX.
385
387 Dmitry Karasik, <dmitry@karasik.eu.org>. Teo Sankaro,
388 <teo_sankaro@hotmail.com>.
389
391 Prima, Prima::Widget, examples/notebook.pl.
392perl v5.38.0 2023-07-21 Prima::Notebooks(3)