Man Linux: Main Page and Category List

NAME

       Prima::Notebooks - multipage widgets

DESCRIPTION

       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.

SYNOPSIS

               my $nb = Prima::TabbedNotebook-> create(
                       tabs => [ 'First page', 'Second page', 'Second page' ],
               );
               $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 );

Prima::Notebook

   Properties
       Provides basic widget container functionality. Acts as merely a
       grouping widget, hiding and showing the children widgets when
       "pageIndex" property is changed.

       defaultInsertPage INTEGER
           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".

       pageCount INTEGER
           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.

       pageIndex INTEGER
           Selects the index of the current page. Valid values are from 0 to
           "pageCount - 1".

   Methods
       attach_to_page INDEX, @WIDGETS
           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.

       contains_widget WIDGET
           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.

       delete_page [ INDEX = -1, REMOVE_CHILDREN = 1 ]
           Deletes 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 "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.

       insert_page [ INDEX = -1 ]
           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.

       insert_to_page INDEX, CLASS, %PROFILE, [[ CLASS, %PROFILE], ... ]
           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.

           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.

           The semantics of setting CLASS and PROFILE, as well as the return
           values are fully equivalent to "insert" method.

           See "insert" in Prima::Widget for details.

       move_widget WIDGET, INDEX
           Moves WIDGET from its old page to INDEXth page.

       widget_get WIDGET, PROPERTY
           Returns 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 list of widgets, associated with INDEXth page.

   Events
       Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
           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.

   Bugs
       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

               $notebook-> pageIndex(1);
               my $widget = $notebook-> insert_to_page( 0, ... );
               $widget-> visible(0);
               $notebook-> pageIndex(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

               $widget-> visible(0);

       code to

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

       solves the problem, but introduces an inconsistency in API.

Prima::TabSet

       "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.

   Properties
       colored BOOLEAN
           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

       firstTab INTEGER
           Selects the first ( leftmost ) visible tab.

       focusedTab INTEGER
           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.

       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 bottom.

           Default value: 1

       tabIndex INDEX
           Selects the INDEXth tab. When changed, "Change" notification is
           triggered.

       tabs ARRAY
           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.

   Methods
       get_item_width INDEX
           Returns width in pixels of INDEXth tab.

       tab2firstTab INDEX
           Returns the index of a tab, that will be drawn leftmost if INDEXth
           tab is to be displayed.

   Events
       Change
           Triggered when "tabIndex" property is changed.

       DrawTab CANVAS, INDEX, COLOR_SET, POLYGON1, POLYGON2
           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:

              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 "topMost" property value, POLYGON1 and POLYGON2 change
           their mutual vertical orientation.

           The notification is always called from within
           "begin_paint/end_paint" block.

       MeasureTab INDEX, REF
           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.

Prima::TabbedNotebook

       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.

   Properties
       defaultInsertPage INTEGER
           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".

       notebookClass STRING
           Assigns the notebook widget class.

           Create-only property.

           Default value: "Prima::Notebook"

       notebookProfile HASH
           Assigns hash of properties, passed to the notebook widget during
           the creation.

           Create-only property.

       notebookDelegations ARRAY
           Assigns 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 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.

       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 INDEXth tab on a tabset widget using the first-level
           tab numeration.

       tabs ARRAY
           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.

       tabsetClass STRING
           Assigns the tab set widget class.

           Create-only property.

           Default value: "Prima::TabSet"

       tabsetProfile HASH
           Assigns hash of properties, passed to the tab set widget during the
           creation.

           Create-only property.

       tabsetDelegations ARRAY
           Assigns 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 second-level tab index, that corresponds to the INDEXth
           first-level tab.

       page2tab INDEX
           Returns first-level tab index, that corresponds to the INDEXth
           second-level tab.

   Events
       Change OLD_PAGE_INDEX, NEW_PAGE_INDEX
           Triggered when "pageIndex" property is changes it s 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.