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

FreeBSD Manual Pages

  
 
  

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

NAME
       Prima::Lists - user-selectable item list	widgets

DESCRIPTION
       The module provides classes for several abstraction layers of item
       representation. The hierarchy of	classes	is as follows:

	       AbstractListViewer
		       AbstractListBox
		       ListViewer
			       ProtectedListBox
			       ListBox

       The root	class, "Prima::AbstractListViewer", provides common interface,
       while by	itself it is not directly usable.  The main differences
       between classes are centered around the way the item list is stored.
       The simplest organization of a text-only	item list, provided by
       "Prima::ListBox", stores	an array of text scalars in a widget. More
       elaborated storage and representation types are not realized, and the
       programmer is urged to use the more abstract classes to derive own
       mechanisms.  For	example, for a list of items that contain text strings
       and icons see "Prima::DirectoryListBox" in Prima::FileDialog.  To
       organize	an item	storage, different from	"Prima::ListBox", it is
       usually enough to overload either the "Stringify", "MeasureItem", and
       "DrawItem" events, or their method counterparts:	"get_item_text",
       "get_item_width", and "draw_items".

Prima::AbstractListViewer
       "Prima::AbstractListViewer" is a	descendant of "Prima::GroupScroller",
       and some	properties are not described here. See "Prima::GroupScroller"
       in Prima::IntUtils.

       The class provides interface to generic list browsing functionality,
       plus functionality for text-oriented lists. The class is	not usable
       directly.

   Properties
       autoHeight BOOLEAN
	   If 1, the item height is changed automatically when the widget font
	   is changed; this is useful for text items.  If 0, item height is
	   not changed;	this is	useful for non-text items.

	   Default value: 1

       count INTEGER
	   An integer property,	destined to reflect number of items in the
	   list.  Since	it is tied to the item storage organization, and
	   hence, to possibility of changing the number	of items, this
	   property is often declared as read-only in descendants of
	   "Prima::AbstractListViewer".

       dragable	BOOLEAN
	   If 1, allows	the items to be	dragged	interactively by pressing
	   control key together	with left mouse	button.	If 0, item dragging is
	   disabled.

	   Default value: 1

       drawGrid	BOOLEAN
	   If 1, vertical grid lines between columns are drawn with
	   "gridColor".	 Actual	only in	multi-column mode.

	   Default value: 1

       extendedSelect BOOLEAN
	   Regards the way the user selects multiple items and is only actual
	   when	"multiSelect" is 1. If 0, the user must	click each item	in
	   order to mark as selected. If 1, the	user can drag mouse or use
	   "Shift" key plus arrow keys to perform range	selection; the
	   "Control" key can be	used to	select individual items.

	   Default value: 0

       focusedItem INDEX
	   Selects the focused item index. If -1, no item is focused.  It is
	   mostly a run-time property, however,	it can be set during the
	   widget creation stage given that the	item list is accessible	on
	   this	stage as well.

	   Default value: -1

       gridColor COLOR
	   Color, used for drawing vertical divider lines for multi-column
	   list	widgets. The list classes support also the indirect way	of
	   setting the grid color, as well as widget does, via the
	   "colorIndex"	property. To achieve this, "ci::Grid" constant is
	   declared ( for more detail see "colorIndex" in Prima::Widget	).

	   Default value: "cl::Black".

       integralHeight BOOLEAN
	   If 1, only the items	that fit vertically in the widget interiors
	   are drawn. If 0, the	items that are partially visible are drawn
	   also.

	   Default value: 0

       integralWidth BOOLEAN
	   If 1, only the items	that fit horizontally in the widget interiors
	   are drawn. If 0, the	items that are partially visible are drawn
	   also.  Actual only in multi-column mode.

	   Default value: 0

       itemHeight INTEGER
	   Selects the height of the items in pixels. Since the	list classes
	   do not support items	with different dimensions, changes to this
	   property affect all items.

	   Default value: default font height

       itemWidth INTEGER
	   Selects the width of	the items in pixels. Since the list classes do
	   not support items with different dimensions,	changes	to this
	   property affect all items.

	   Default value: default widget width

       multiSelect BOOLEAN
	   If 0, the user can only select one item, and	it is reported by the
	   "focusedItem" property. If 1, the user can select more than one
	   item.  In this case,	"focusedItem"'th item is not necessarily
	   selected.  To access	selected item list, use	"selectedItems"
	   property.

	   Default value: 0

       multiColumn BOOLEAN
	   If 0, the items are arrayed vertically in one column, and the main
	   scroll bar is vertical. If 1, the items are arrayed in several
	   columns, "itemWidth"	pixels wide each. In this case,	the main
	   scroll bar is horizontal.

       offset INTEGER
	   Horizontal offset of	an item	list in	pixels.

       topItem INTEGER
	   Selects the first item drawn.

       selectedCount INTEGER
	   A read-only property. Returns number	of selected items.

       selectedItems ARRAY
	   ARRAY is an array of	integer	indices	of selected items.

       vertical	BOOLEAN
	   Sets	seneral	direction of items in multi-column mode. If 1, items
	   increase down-to-right. Otherwise, right-to-down.

	   Doesn't have	any effect in single-column mode.  Default value: 1.

   Methods
       add_selection ARRAY, FLAG
	   Sets	item indices from ARRAY	in selected or deselected state,
	   depending on	FLAG value, correspondingly 1 or 0.

	   Only	for multi-select mode.

       deselect_all
	   Removes selection from all items.

	   Only	for multi-select mode.

       draw_items CANVAS, ITEM_DRAW_DATA
	   Called from within "Paint" notification to draw items. The default
	   behavior is to call "DrawItem" notification for every item in
	   ITEM_DRAW_DATA array.  ITEM_DRAW_DATA is an array or	arrays,	where
	   each	array consists of parameters, passed to	"DrawItem"
	   notification.

	   This	method is overridden in	some descendant	classes, to increase
	   the speed of	drawing	routine. For example, "std_draw_text_items" is
	   the optimized routine for drawing unified text-based	items. It is
	   used	in "Prima::ListBox" class.

	   See DrawItem	for parameters description.

       draw_text_items CANVAS, FIRST, LAST, STEP, X, Y,	OFFSET,	CLIP_RECT
	   Called by "std_draw_text_items" to draw sequence of text items with
	   indices from	FIRST to LAST, by STEP,	on CANVAS, starting at point
	   X, Y, and incrementing the horizontal position with OFFSET.
	   CLIP_RECT is	a reference to array of	four integers with inclusive-
	   inclusive coordinates of the	active clipping	rectangle.

       get_item_text INDEX
	   Returns text	string assigned	to INDEXth item.  Since	the class does
	   not assume the item storage organization, the text is queried via
	   "Stringify" notification.

       get_item_width INDEX
	   Returns width in pixels of INDEXth item.  Since the class does not
	   assume the item storage organization, the value is queried via
	   "MeasureItem" notification.

       is_selected INDEX
	   Returns 1 if	INDEXth	item is	selected, 0 if it is not.

       item2rect INDEX,	[ WIDTH, HEIGHT	]
	   Calculates and returns four integers	with rectangle coordinates of
	   INDEXth item	within the widget. WIDTH and HEIGHT are	optional
	   parameters with pre-fetched dimension of the	widget;	if not set,
	   the dimensions are queried by calling "size"	property. If set,
	   however, the	"size" property	is not called, thus some speed-up can
	   be achieved.

       point2item X, Y
	   Returns the index of	an item	that contains point (X,Y). If the
	   point belongs to the	item outside the widget's interior, returns
	   the index of	the first item outside the widget's interior in	the
	   direction of	the point.

       redraw_items INDICES
	   Redraws all items in	INDICES	array.

       select_all
	   Selects all items.

	   Only	for multi-select mode.

       set_item_selected INDEX,	FLAG
	   Sets	selection flag of INDEXth item.	 If FLAG is 1, the item	is
	   selected. If	0, it is deselected.

	   Only	for multi-select mode.

       select_item INDEX
	   Selects INDEXth item.

	   Only	for multi-select mode.

       std_draw_text_items CANVAS, ITEM_DRAW_DATA
	   An optimized	method,	draws unified text-based items.	 It is fully
	   compatible to "draw_items" interface, and is	used in
	   "Prima::ListBox" class.

	   The optimization is derived from the	assumption that	items maintain
	   common background and foreground colors, that differ	in selected
	   and non-selected states only. The routine groups drawing requests
	   for selected	and non-selected items,	and draws items	with reduced
	   number of calls to "color" property.	 While the background is drawn
	   by the routine itself, the foreground ( usually text	) is delegated
	   to the "draw_text_items" method, so the text	positioning and
	   eventual decorations	would not require full rewrite of code.

	   ITEM_DRAW_DATA is an	array of arrays	of scalars, where each array
	   contains parameters of "DrawItem" notification.  See	DrawItem for
	   parameters description.

       toggle_item INDEX
	   Toggles selection of	INDEXth	item.

	   Only	for multi-select mode.

       unselect_item INDEX
	   Deselects INDEXth item.

	   Only	for multi-select mode.

   Events
       Click
	   Called when the user	presses	return key or double-clicks on an
	   item. The index of the item is stored in "focusedItem".

       DragItem	OLD_INDEX, NEW_INDEX
	   Called when the user	finishes the drag of an	item from OLD_INDEX to
	   NEW_INDEX position. The default action rearranges the item list in
	   accord with the dragging action.

       DrawItem	CANVAS,	INDEX, X1, Y1, X2, Y2, SELECTED, FOCUSED, PRELIGHT,
       COLUMN
	   Called when an INDEXth item is to be	drawn on CANVAS.  X1, Y1, X2,
	   Y2 designate	the item rectangle in widget coordinates, where	the
	   item	is to be drawn.	SELECTED, FOCUSED, and PRELIGHT	are boolean
	   flags, if the item must be drawn correspondingly in selected	and
	   focused states, with	or without the prelight	effect.

       MeasureItem INDEX, REF
	   Puts	width in pixels	of INDEXth item	into REF scalar	reference.
	   This	notification must be called from within
	   "begin_paint_info/end_paint_info" block.

       SelectItem INDEX, FLAG
	   Called when the item	changed	its selection state.  INDEX is the
	   index of the	item, FLAG is its new selection	state: 1 if it is
	   selected, 0 if it is	not.

       Stringify INDEX,	TEXT_REF
	   Puts	text string, assigned to INDEXth item into TEXT_REF scalar
	   reference.

Prima::AbstractListBox
       Exactly the same	as its ascendant, "Prima::AbstractListViewer", except
       that it does not	propagate "DrawItem" message, assuming that the	items
       must be drawn as	text.

Prima::ListViewer
       The class implements items storage mechanism, but leaves	the items
       format to the programmer. The items are accessible via "items" property
       and several other helper	routines.

       The class also defines the user navigation, by accepting	character
       keyboard	input and jumping to the items that have text assigned with
       the first letter	that match the input.

       "Prima::ListViewer" is derived from "Prima::AbstractListViewer".

   Properties
       autoWidth BOOLEAN
	   Selects if the gross	item width must	be recalculated	automatically
	   when	either the font	changes	or item	list is	changed.

	   Default value: 1

       count INTEGER
	   A read-only property; returns number	of items.

       items ARRAY
	   Accesses the	storage	array of items.	The format of items is not
	   defined, it is merely treated as one	scalar per index.

   Methods
       add_items ITEMS
	   Appends array of ITEMS to the end of	the list.

       calibrate
	   Recalculates	all item widths	and adjusts "itemWidth"	if "autoWidth"
	   is set.

       delete_items INDICES
	   Deletes items from the list.	INDICES	can be either an array,	or a
	   reference to	an array of item indices.

       get_item_width INDEX
	   Returns width in pixels of INDEXth item from	internal cache.

       get_items INDICES
	   Returns array of items. INDICES can be either an array, or a
	   reference to	an array of item indices.  Depending on	the caller
	   context, the	results	are different: in array	context	the item list
	   is returned;	in scalar - only the first item	from the list. The
	   semantic of the last	call is	naturally usable only for single item
	   retrieval.

       insert_items OFFSET, ITEMS
	   Inserts array of items at OFFSET index in the list.	Offset must be
	   a valid index; to insert items at the end of	the list use
	   "add_items" method.

	   ITEMS can be	either an array, or a reference	to an array of items.

       replace_items OFFSET, ITEMS
	   Replaces existing items at OFFSET index in the list.	 Offset	must
	   be a	valid index.

	   ITEMS can be	either an array, or a reference	to an array of items.

Prima::ProtectedListBox
       A semi-demonstrational class, derived from "Prima::ListViewer", that
       applies certain protection for every item drawing session.  Assuming
       that several item drawing routines can be assembled in one widget,
       "Prima::ProtectedListBox" provides a safety layer between these,	so,
       for example, one	drawing	routine	that selects a font or a color and
       does not	care to	restore	the old	value back, does not affect the
       outlook of the other items.

       This functionality is implementing by overloading "draw_items" method
       and also	all graphic properties.

Prima::ListBox
       Descendant of "Prima::ListViewer", declares format of items as a	single
       text string. Incorporating all of functionality of its predecessors,
       provides	a standard listbox widget.

   Synopsis
	       my $lb =	Prima::ListBox-> create(
		       items	   => [qw(First	Second Third)],
		       focusedItem => 2,
		       onClick	   => sub {
			       print $_[0]-> get_items(	$_[0]->	focusedItem), "	is selected\n";
		       }
	       );

   Methods
       get_item_text INDEX
	   Returns text	string assigned	to INDEXth item.  Since	the item
	   storage organization	is implemented,	does so	without	calling
	   "Stringify" notification.

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO
       Prima, Prima::Widget, Prima::ComboBox, Prima::FileDialog,
       examples/editor.pl

perl v5.24.1			  2017-05-29		       Prima::Lists(3)

NAME | DESCRIPTION | Prima::AbstractListViewer | Prima::AbstractListBox | Prima::ListViewer | Prima::ProtectedListBox | Prima::ListBox | AUTHOR | SEE ALSO

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

home | help