Prima::Notebooks(3)

Prima::Notebooks(3) · User Contributed Perl Documentation · bestie, this is the multipage-widget lore and it's giving iconic container energy 💅

💖 NAME 💖

Prima::Notebooks — multipage widgets 🦋

🌸 DESCRIPTION 🌸

This module is your little squad of widgets for organizing multipage containers, aka notebooks. Prima::Notebook brings the basic functionality of that kind of widget container. Prima::TabSet is the page selector control, and Prima::TabbedNotebook combines these two into a ready-to-use multipage control with interactive navigation. Periodt. ✨

✨ SYNOPSIS ✨

        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 );
        run Prima;

---

🦋 Prima::Notebook 🦋

This class gives you basic widget container functionality. It's basically a grouping widget that hides and shows child widgets whenever the pageIndex property changes. Lowkey the whole vibe. 🎀

✨ Properties ✨

• defaultInsertPage INTEGER — picks which page widgets attached by the insert call get assigned to. If it's set to undef, the default page is the current page. Default value: undef.
• pageCount INTEGER — picks the number of pages. If you reduce the number of pages, widgets that belong to the rejected pages are removed from the notebook's storage. No leftovers, bestie.
• pageIndex INTEGER — picks the index of the current page. Valid values go from 0 to pageCount - 1.

💅 Methods 💅

• attach_to_page INDEX, @WIDGETS — attaches @WIDGETS to the INDEXth page. The widgets don't necessarily have to be children of the notebook widget. If the INDEXth page is not the current one, the widgets get hidden and disabled; otherwise their state is not changed.
• contains_widget WIDGET — searches for WIDGET in the attached widgets list. If it finds it, returns two integers: the location page index and the widget list index. Otherwise returns an empty list.
• delete_page [ INDEX = -1, REMOVE_CHILDREN = 1 ] — deletes the 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 the owner property set to the caller widget, and returns the list of references to the newly created objects. See insert in Prima::Widget for details.
• insert_page [ INDEX = -1 ] — inserts a new empty page at INDEX. The 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 or more widgets to the INDEXth page. Setting CLASS and PROFILE, plus the return values, is fully equivalent to the insert method. See insert in Prima::Widget 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. Setting CLASS and PROFILE, plus the return values, is fully equivalent to the insert method. See insert in Prima::Widget for details.
• move_widget WIDGET, INDEX — moves WIDGET to the INDEXth page.
• widget_get WIDGET, PROPERTY — returns the 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 Prima::Object.
• widgets_from_page INDEX — returns the list of widgets associated with the INDEXth page.

🔥 Events 🔥

• Change OLD_PAGE_INDEX, NEW_PAGE_INDEX — called when the pageIndex value is changed from OLD_PAGE_INDEX to NEW_PAGE_INDEX. Current implementation invokes this notification while the notebook widget is in the locked state, so no redraw requests are honored during the execution of the notification.

💀 Bugs 💀

Since the notebook operates directly on children widgets' ::visible and ::enable properties, there's 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 the execution of the following code

        $notebook-> pageIndex(1);
        my $widget = $notebook-> insert_to_page( 0, ... );
        $widget-> visible(0);
        $notebook-> pageIndex(0);

$widget will still become visible. As a workaround, the widget_set method can be suggested, to be called together with the explicit state calls. Changing the

        $widget-> visible(0);

code to

        $notebook-> widget_set( $widget, visible => 0);

solves the problem, but introduces an inconsistency in API. 🙈

---

🧚 Prima::TabSet 🧚

The Prima::TabSet class implements the functionality of an interactive page switcher. A widget is presented as a set of horizontal bookmark-styled tabs with text identifiers. It's giving very demure, very page-selector. 🎀

🌸 Properties 🌸

• colored BOOLEAN — a boolean property that selects whether each tab uses a unique color ( OS/2 Warp 4 style ), or all tabs are drawn with backColor. Default value: 1.
• colorset ARRAY — lets you specify custom colors for the tabs. Used only when colored is set to 1.
• firstTab INTEGER — selects the first ( leftmost ) visible tab.
• focusedTab INTEGER — selects the currently focused tab. This property value is almost always equal to tabIndex except when the widget is navigated by arrow keys, and the 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 the bottom. Default value: 1.
• tabIndex INDEX — selects the INDEXth tab. When changed, the Change notification is triggered.
• tabs ARRAY — an 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.

🌟 Methods 🌟

• get_item_width INDEX — returns the width in pixels of the INDEXth tab.
• tab2firstTab INDEX — returns the index of the tab that will be drawn leftmost if the 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 the tab from the given position.

🦋 Events 🦋

• Change — triggered when the tabIndex property is changed.
• DrawTab CANVAS, INDEX, COLOR_SET, POLYGON1, POLYGON2 — called when the INDEXth tab is to be drawn on CANVAS. COLOR_SET is an array reference that consists of four cached color values: foreground, background, dark 3d color, and light 3d color. POLYGON1 and POLYGON2 are array references that contain four points as integer pairs in (X,Y)-coordinates. POLYGON1 keeps the coordinates of the larger polygon of a tab, while POLYGON2 keeps 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 the topMost property value, POLYGON1 and POLYGON2 change their mutual vertical orientation. The notification is always called from within the begin_paint/end_paint block.

• MeasureTab INDEX, REF — stores the width of the INDEXth tab in pixels into the REF scalar value. This notification must be called from within the begin_paint_info/end_paint_info block.

💖 Prima::TabbedNotebook 💖

okay so bestie, this class is the collab we all needed: it combines the functionality of Prima::TabSet and Prima::Notebook, giving you the interactive multipage widget functionality. The page indexing scheme has two levels: the first level is equivalent to the tabs provided by Prima::TabSet. Each first-level tab, in turn, may contain one or more second-level pages, which can be switched using native Prima::TabbedNotebook controls.

Term check, because words matter: the first-level tabs are referred to as tabs, and the second-level ones are pages. iykyk 💅

✨ Properties ✨

The class forwards the following properties of Prima::TabSet, which are described in Prima::TabSet: colored, colorset.

• defaultInsertPage INTEGER — Selects the page where widgets attached by the 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 a hash of properties passed to the notebook widget during the creation. Create-only property.
• notebookDelegations ARRAY — Assigns a 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 *INDEX*th page or a tabset widget (the second-level tab). When this property is triggered, tabIndex can change its value, and the 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 *INDEX*th tab on the tabset widget using the first-level tab numeration.
• tabs ARRAY — Manages the 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, however, with a single exception. To define second-level tabs, the same text string must be repeated as many times as many second-level tabs are needed. For example, the code

$nb-> tabs('1st', ('2nd') x 3);

results in the 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 a hash of properties passed to the tab set widget during the creation. Create-only property.
• tabsetDelegations ARRAY — Assigns a list of delegated notifications to the tab set widget. Create-only property.

🌸 Methods 🌸

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.

• tab2page INDEX — Returns the second-level tab index that corresponds to the *INDEX*th first-level tab.
• page2tab INDEX — Returns the first-level tab index that corresponds to the *INDEX*th 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 the TEXT is the same as the existing tab left or right from POSITION, the page is joined to the existing tab as a page; otherwise, a new tab is created.
• delete_page POSITION — Removes the page from the given position.

🦋 Events 🦋

• Change OLD_PAGE_INDEX, NEW_PAGE_INDEX — Triggered when the pageIndex property changes its value from OLD_PAGE_INDEX to NEW_PAGE_INDEX.

👑 AUTHORS 👑

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

🔎 SEE ALSO 🔎

Prima, Prima::Widget, examples/notebook.pl.

---

💋 later bestie — this manual page is from perl v5.42.0, dated 2024-08-20, and it's Prima::Notebooks(3) 🫶