Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Prima::Notebooks(3)   User Contributed Perl Documentation  Prima::Notebooks(3)

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.

       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 a tab from the given	position

   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.

       insert_page TEXT, [ POSITION = -1 ]
	   Inserts a new page with text	at the given position, which is	at the
	   end by default.  If TEXT is same as the existing tab	left or	right
	   from	POSITION, the page is joined the existing tab; otherwise a new
	   tab is created.

       delete_page POSITION
	   Removes a page from the given position.

   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.

perl v5.24.1			  2017-02-28		   Prima::Notebooks(3)

NAME | DESCRIPTION | SYNOPSIS | Prima::Notebook | Prima::TabSet | Prima::TabbedNotebook | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::Notebooks&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help