1Prima::Notebooks(3)   User Contributed Perl Documentation  Prima::Notebooks(3)
2
3
4

NAME

6       Prima::Notebooks - multipage widgets
7

DESCRIPTION

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

SYNOPSIS

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

Prima::Notebook

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
35       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
40           Default value: "undef".
41
42       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
47       pageIndex INTEGER
48           Selects the index of the current page. Valid values are from 0 to
49           "pageCount - 1".
50
51   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
58       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
63       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
67       delete_widget WIDGET
68           Detaches WIDGET from the widget list and destroys the widget.
69
70       detach_from_page WIDGET
71           Detaches WIDGET from the widget list.
72
73       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
78           See "insert" in Prima::Widget for details.
79
80       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
85       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
90           See "insert" in Prima::Widget for details.
91
92       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
98           The semantics of setting CLASS and PROFILE, as well as the return
99           values are fully equivalent to "insert" method.
100
101           See "insert" in Prima::Widget for details.
102
103       move_widget WIDGET, INDEX
104           Moves WIDGET from its old page to INDEXth page.
105
106       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
111       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
116           See "set" in Prima::Object.
117
118       widgets_from_page INDEX
119           Returns list of widgets, associated with INDEXth page.
120
121   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
128   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
136               $notebook-> pageIndex(1);
137               my $widget = $notebook-> insert_to_page( 0, ... );
138               $widget-> visible(0);
139               $notebook-> pageIndex(0);
140
141       $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
145               $widget-> visible(0);
146
147       code to
148
149               $notebook-> widget_set( $widget, visible => 0);
150
151       solves the problem, but introduces an inconsistency in API.
152

Prima::TabSet

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
158   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
163           Default value: 1
164
165       firstTab INTEGER
166           Selects the first ( leftmost ) visible tab.
167
168       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
174       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
179           Default value: 1
180
181       tabIndex INDEX
182           Selects the INDEXth tab. When changed, "Change" notification is
183           triggered.
184
185       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
190   Methods
191       get_item_width INDEX
192           Returns width in pixels of INDEXth tab.
193
194       tab2firstTab INDEX
195           Returns the index of a tab, that will be drawn leftmost if INDEXth
196           tab is to be displayed.
197
198       insert_tab TEXT, [ POSITION = -1 ]
199           Inserts a new tab text at the given position, which is at the end
200           by default
201
202       delete_tab POSITION
203           Removes a tab from the given position
204
205   Events
206       Change
207           Triggered when "tabIndex" property is changed.
208
209       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
218              POLYGON1
219
220                   [2,3]        [4,5]
221                     o..........o
222                    .            .
223              [0,1].   TAB_TEXT   . [6,7]
224                  o................o
225
226              POLYGON2
227
228               [0,1]               [2,3]
229                  o................o
230              [6,7]o..............o[4,5]
231
232           Depending on "topMost" property value, POLYGON1 and POLYGON2 change
233           their mutual vertical orientation.
234
235           The notification is always called from within
236           "begin_paint/end_paint" block.
237
238       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

Prima::TabbedNotebook

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
251       First-level tab is often referred as tab, and second-level as page.
252
253   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
259           Default value: "undef".
260
261       notebookClass STRING
262           Assigns the notebook widget class.
263
264           Create-only property.
265
266           Default value: "Prima::Notebook"
267
268       notebookProfile HASH
269           Assigns hash of properties, passed to the notebook widget during
270           the creation.
271
272           Create-only property.
273
274       notebookDelegations ARRAY
275           Assigns list of delegated notifications to the notebook widget.
276
277           Create-only property.
278
279       orientation INTEGER
280           Selects one of the following tno::XXX constants
281
282           tno::Top
283               The TabSet will be drawn at the top of the widget.
284
285           tno::Bottom
286               The TabSet will be drawn at the bottom of the widget.
287
288           Default value: tno::Top
289
290       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
295       style INTEGER
296           Selects one of the following tns::XXX constants
297
298           tns::Standard
299               The widget will have a raised border surrounding it and a +/-
300               control at the top for moving between pages.
301
302           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
307           Default value: tns::Standard
308
309       tabIndex INTEGER
310           Selects the INDEXth tab on a tabset widget using the first-level
311           tab numeration.
312
313       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
321                   $nb-> tabs('1st', ('2nd') x 3);
322
323           results in creation of a notebook of four pages and two first-level
324           tabs. The tab '2nd' contains three second-level pages.
325
326           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
331       tabsetClass STRING
332           Assigns the tab set widget class.
333
334           Create-only property.
335
336           Default value: "Prima::TabSet"
337
338       tabsetProfile HASH
339           Assigns hash of properties, passed to the tab set widget during the
340           creation.
341
342           Create-only property.
343
344       tabsetDelegations ARRAY
345           Assigns list of delegated notifications to the tab set widget.
346
347           Create-only property.
348
349   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
356       tab2page INDEX
357           Returns second-level tab index, that corresponds to the INDEXth
358           first-level tab.
359
360       page2tab INDEX
361           Returns first-level tab index, that corresponds to the INDEXth
362           second-level tab.
363
364       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
370       delete_page POSITION
371           Removes a page from the given position.
372
373   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

AUTHORS

379       Dmitry Karasik, <dmitry@karasik.eu.org>.  Teo Sankaro,
380       <teo_sankaro@hotmail.com>.
381

SEE ALSO

383       Prima, Prima::Widget, examples/notebook.pl.
384
385
386
387perl v5.36.0                      2022-07-22               Prima::Notebooks(3)
Impressum