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

FreeBSD Manual Pages

  
 
  

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

NAME
       Prima::Grids - grid widgets

   SYNOPSIS
	       use Prima::Grids;

	       $grid = Prima::Grid-> create(
		       cells	   => [
			       [qw(1.First 1.Second 1.Third)],
			       [qw(2.First 2.Second 2.Third)],
			       [qw(3.First 3.Second 3.Third)],
		       ],
		       onClick	   => sub {
			       print $_[0]-> get_cell_text( $_[0]-> focusedCell), " is selected\n";
		       }
	       );

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

	       AbstractGridViewer
		       AbstractGrid
		       GridViewer
			       Grid

       The root	class, "Prima::AbstractGridViewer", provides common interface,
       while by	itself it is not directly usable.  The main differences
       between classes are centered around the way the cell data are stored.
       The simplest organization of a text-only	cell, provided by
       "Prima::Grid", stores data as a two-dimensional array of	text scalars.
       More elaborated storage and representation types	are not	realized, and
       the programmer is urged to use the more abstract	classes	to derive own
       mechanisms.  To organize	an item	storage, different from	"Prima::Grid",
       it is usually enough to overload	either the "Stringify",	"Measure", and
       "DrawCell" events, or their method counterparts:	"get_cell_text",
       "columnWidth", "rowHeight", and "draw_items".

       The grid	widget is designed to contain cells of variable	extents, of
       two types, normal and indent. The indent	rows and columns are displayed
       in grid margins,	and their cell are drawn with distinguished colors.
       An example use for a bottom indent row is a sum row in a	spreadsheet
       application; the	top indent row can be used for displaying columns'
       headers.	The normal cells can be	selected by the	user, scrolled,	and
       selected. The cell selection can	only contain rectangular areas,	and
       therefore is operated with two integer pairs with the beginning and the
       end of the selection.

       The widget operates in two visual scrolling modes; when the space
       allows, the scrollbars affect the leftmost and the topmost cell.	When
       the widget is not large enough to accommodate at	least one cell and all
       indent cells, the layout	is scrolled pixel-wise.	These modes are	named
       'cell' and 'pixel', after the scrolling units.

       The widget allows the interactive changing of cell widths and heights
       by dragging the grid lines between the cells.

Prima::AbstractGridViewer
       "Prima::AbstractGridViewer", the	base for all grid widgets in the
       module, provides	interface to generic grid browsing functionality, plus
       functionality for text-oriented grids. The class	is not usable
       directly.

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

   Properties
       allowChangeCellHeight BOOLEAN
	   If 1, the user is allowed to	change vertical	extents	of cells by
	   dragging the	horizontal grid	lines. Prerequisites to	the options
	   are:	the lines must be set visible via "drawHGrid" property,
	   "constantCellHeight"	property set to	0, and the changes to the
	   vertical extents can	be recorded via	"SetExtent" notification.

	   Default value: 0

       allowChangeCellWidth BOOLEAN
	   If 1, the user is allowed to	change horizontal extents of cells by
	   dragging the	horizontal grid	lines. Prerequisites to	the options
	   are:	the lines must be set visible via "drawVGrid" property,
	   "constantCellWidth" property	set to 0, and the changes to the
	   horizontal extents can be recorded via "SetExtent" notification.

	   Default value: 0

       cellIndents X1, Y1, X2, Y2
	   Marks the marginal rows and columns as 'indent' cells. The indent
	   cells are drawn with	another	color pair ( see indentCellColor,
	   indentCellBackColor ), cannot be selected and scrolled. X1 and X2
	   correspond to amount	of indent columns, and Y1 and Y2, - to the
	   indent rows.

	   "leftCell" and "topCell" do not count the indent cells as the
	   leftmost or topmost visible cell; in	other words, X1	and Y1 are
	   minimal values for "leftCell" and "topCell" properties.

	   Default value: 0,0,0,0

       clipCells INTEGER
	   A three-state integer property, that	governs	the way	clipping is
	   applied when	cells are drawn. Depending on kind of graphic in
	   cells, the clipping may be necessary, or unnecessary.

	   If the value	is 1, the clipping is applied for every	column drawn,
	   as the default drawing routines proceed column-wise.	If the value
	   is 2, the clipping as applied for every cell. This setting reduces
	   the drawing speed significantly.  If	the value is 0,	no clipping is
	   applied.

	   This	property is destined for custom-drawn grid widgets, when it is
	   the developer's task	to decide what kind of clipping	suits better.
	   Text	grid widgets, "Prima::AbstractGrid" and	"Prima::Grid", are
	   safe	with "clipCells" set to	1.

	   Default value: 1

       columns INTEGER
	   Sets	number of columns, including the indent	columns. The number of
	   columns must	be larger than the number of indent columns.

	   Default value: 0.

       columnWidth COLUMN [ WIDTH ]
	   A run-time property,	selects	width of a column. To acquire or set
	   the width, "Measure"	and "SetExtent"	notifications can be invoked.
	   Result of "Measure" may be cached internally	using
	   "cache_geometry_requests" method.

	   The width does not include widths of	eventual vertical grid lines.

	   If "constantCellWidth" is defined, the property is used as its
	   alias.

       constantCellHeight HEIGHT
	   If defined, all rows	have equal height, HEIGHT pixels. If "undef",
	   rows	have different heights.

	   Default value: undef

       constantCellWidth WIDTH
	   If defined, all rows	have equal width, WIDTH	pixels.	If "undef",
	   columns have	different widths.

	   Default value: undef

       drawHGrid BOOLEAN
	   If 1, horizontal grid lines between cells are drawn with
	   "gridColor".

	   Default value: 1

       drawVGrid
	   If 1, vertical grid lines between cells are drawn with "gridColor".

	   Default value: 1

       dx INTEGER
	   A run-time property.	Selects	horizontal offset in pixels of grid
	   layout in pixel mode.

       dy INTEGER
	   A run-time property.	Selects	vertical offset	in pixels of grid
	   layout in pixel mode.

       focusedCell X, Y
	   Selects coordinates or the focused cell.

       gridColor COLOR
	   Selects the color of	grid lines.

	   Default value: "cl::Black" .

       gridGravity INTEGER
	   The property	selects	the breadth of area around the grid lines,
	   that	reacts on grid-dragging	mouse events. The minimal value, 0,
	   marks only grid lines as the	drag area, but makes the dragging
	   operation inconvenient for the user.	 Larger	values make the
	   dragging more convenient, but increase the chance that the user
	   will	not be able to select too narrow cells with the	mouse.

	   Default value: 3

       indentCellBackColor COLOR
	   Selects the background color	of indent cells.

	   Default value: "cl::Gray" .

       indentCellColor
	   Selects the foreground color	of indent cells.

	   Default value: "cl::Gray" .

       leftCell	INTEGER
	   Selects index of the	leftmost visible normal	cell.

       multiSelect BOOLEAN
	   If 1, the normal cells in an	arbitrary rectangular area can be
	   marked as selected (	see selection ). If 0, only one	cell at	a time
	   can be selected.

	   Default value: 0

       rows INTEGER
	   Sets	number of rows,	including the indent rows. The number of rows
	   must	be larger than the number of indent rows.

	   Default value: 0.

       topCell
	   Selects index of the	topmost	visible	normal cell.

       rowHeight INTEGER
	   A run-time property,	selects	height of a row. To acquire or set the
	   height, "Measure" and "SetExtent" notifications can be invoked.
	   Result of "Measure" may be cached internally	using
	   "cache_geometry_requests" method.

	   The height does not include widths of eventual horizontal grid
	   lines.

	   If "constantCellHeight" is defined, the property is used as its
	   alias.

       selection X1, Y1, X2, Y2
	   If "multiSelect" is 1, governs the extents of a rectangular area,
	   that	contains selected cells. If no such area is present, selection
	   is (-1,-1,-1,-1), and "has_selection" returns 0 .

	   If "multiSelect" is 0, in get-mode returns the focused cell,	and
	   discards the	parameters in the set-mode.

   Methods
       cache_geometry_requests CACHE
	   If CACHE is 1, starts caching results of "Measure" notification,
	   thus	lighting the subsequent	"columnWidth" and "rowHeight" calls;
	   if CACHE is 0, flushes the cache.

	   If a	significant geometry change was	during the caching, the	cache
	   is not updated, so it is the	caller's responsibility	to flush the
	   cache.

       deselect_all
	   Nullifies the selection, if "multiSelect" is	1.

       draw_cells CANVAS, COLUMNS, ROWS, AREA
	   A bulk draw routine,	called from "onPaint" to draw cells.  AREA is
	   an array of four integers with inclusive-inclusive coordinates of
	   the widget inferior without borders and scrollbars (	result of
	   get_active_area(2) call; see	"get_active_area" in Prima::IntUtils
	   ).

	   COLUMNS and ROWS are	structures that	reflect	the columns and	rows
	   of the cells	to be drawn. Each item in these	corresponds to a
	   column or row, and is an array with the following layout:

		   0: column or	row index
		   1: type; 0 -	normal cell, 1 - indent	cell
		   2: visible cell breadth
		   3: visible cell start
		   4: visible cell end
		   5: real cell	start
		   6: real cell	end

	   The coordinates are in inclusive-inclusive coordinate system, and
	   do not include eventual grid	space, nor gaps	between	indent and
	   normal cells. By default, internal arrays "{colsDraw}" and
	   "{rowsDraw}"	are passed as COLUMNS and ROWS parameters.

	   In "Prima::AbstractGrid" and	"Prima::Grid" classes <draw_cells> is
	   overloaded to transfer the call to "std_draw_text_cells", the text-
	   oriented optimized routine.

       draw_text_cells SCREEN_RECTANGLES, CELL_RECTANGLES, CELL_INDECES,
       FONT_HEIGHT
	   A bulk routine for drawing text cells, called from
	   "std_draw_text_cells" .

	   SCREEN_RECTANGLES and CELL_RECTANGLES are arrays, where each	item
	   is a	rectangle with exterior	of a cell. SCREEN_RECTANGLES contains
	   rectangles that cover the cell visible area;	CELL_RECTANGLES
	   contains rectangles that span the cell extents disregarding its
	   eventual partial visibility.	For example, a 100-pixel cell with
	   only	its left half visible, would contain corresponding arrays
	   [150,150,200,250] in	SCREEN_RECTANGLES, and [150,150,250,250] in
	   CELL_RECTANGLES.

	   CELL_INDECES	contains arrays	of the cell coordinates; each array
	   item	is an array of integer pair where item 0 is column, and	item 1
	   is row of the cell.

	   FONT_HEIGHT is a current font height	value, cached since
	   "draw_text_cells" is	often used for text operations and may require
	   vertical text justification.

       get_cell_area [ WIDTH, HEIGHT ]
	   Returns screen area in inclusive-inclusive pixel coordinates, that
	   is used to display normal cells. The	extensions are related to the
	   current size	of a widget, however, can be overridden	by specifying
	   WIDTH and HEIGHT.

       get_cell_alignment COLUMN, ROW
	   Returns two "ta::" constants	for horizontal and vertical cell text
	   alignment.  Since the class does not	assume the item	storage
	   organization, the values are	queried	via "GetAlignment"
	   notification.

       get_cell_text COLUMN, ROW
	   Returns text	string assigned	to cell	in COLUMN and ROW.  Since the
	   class does not assume the item storage organization,	the text is
	   queried via "Stringify" notification.

       get_range VERTICAL, INDEX
	   Returns a pair of integers, minimal and maximal breadth of INDEXth
	   column or row in pixels. If VERTICAL	is 1, the rows are queried; if
	   0, the columns.

	   The method calls "GetRange" notification.

       get_screen_cell_info COLUMN, ROW
	   Returns information about a cell in COLUMN and ROW, if it is
	   currently visible.  The returned parameters are indexed by
	   "gsci::XXX" constants, and explained	below:

		   gsci::COL_INDEX - visual column number where	the cell displayed
		   gsci::ROW_INDEX - visual row	number where the cell displayed
		   gsci::V_FULL	   - cell is fully visible

		   gsci::V_LEFT	   - inclusive-inclusive rectangle of the visible
		   gsci::V_BOTTOM    part of the cell. These four indices are grouped
		   gsci::V_RIGHT     under list	constant, gsci::V_RECT.
		   gsci::V_TOP

		   gsci::LEFT	   - inclusive-inclusive rectangle of the cell,	as if
		   gsci::BOTTOM	     it	is fully visible. These	four indices are grouped
		   gsci::RIGHT	     under list	constant, gsci::RECT. If gsci::V_FULL
		   gsci::TOP	     is	1, these values	are identical to these in gsci::V_RECT.

	   If the cell is not visible, returns empty array.

       has_selection
	   Returns a boolean value, indicating whether the grid	contains a
	   selection (1) or not	(0).

       point2cell X, Y,	[ OMIT_GRID = 0	]
	   Return information about point X, Y in widget coordinates. The
	   method returns two integers,	CX and CY, with	cell coordinates, and
	   eventual HINTS hash,	with more information about pixe localtion. If
	   OMIT_GRID is	set to 1 and the pixel belongs to a grid, the pixels
	   is treated a	part of	adjacent cell.	The call syntax:

		   ( $CX, $CY, %HINTS) = $self->point2cell( $X,	$Y);

	   If the pixel	lies within cell boundaries by either coordinate, CX
	   and/or CY are correspondingly set to	cell column and/or row.	When
	   the pixel is	outside	cell space, CX and/or CY are set to -1.

	   HINTS may contain the following values:

	   "x" and "y"
	       If 0, the coordinate lies within	boundaries of a	cell.

	       If -1, the coordinate is	on the left/top	to the cell body.

	       If +1, the coordinate is	on the right/bottom to the cell	body,
	       but within the widget.

	       If +2, the coordinate is	on the right/bottom to the cell	body,
	       but outside the widget.

	   "x_type" and	"y_type"
	       Present when "x"	or "y" values are 0.

	       If 0, the cell is a normal cell.

	       If -1, the cell is left/top indent cell.

	       If +1, the cell is right/bottom indent cell.

	   "x_grid" and	"y_grid"
	       If 1, the point is over a grid line. This case can only happen
	       when OMIT_GRID is 0.  If	"allowChangeCellHeight"	and/or
	       "allowChangeCellWidth" are set, treats also "gridGravity"-broad
	       pixels strips on	both sides of the line as the grid area.

	       Also values of "x_left"/"x_right" or "y_bottom"/"y_top" might
	       be set.

	   "x_left"/"x_right" and "y_bottom"/"y_top"
	       Present together	with "x_grid" or "y_grid". Select indices of
	       cells adjacent to the grid line.

	   "x_gap" and "y_gap"
	       If 1, the point is within a gap between the last	normal cell
	       and the first right/bottom indent cell.

	   "normal"
	       If 1, the point lies within the boundaries of a normal cell.

	   "indent"
	       If 1, the point lies within the boundaries of an	indent cell.

	   "grid"
	       If 1, the point is over a grid line.

	   "exterior"
	       If 1, the point is in inoperable	area or	outside	the widget
	       boundaries.

       redraw_cell X, Y
	   Repaints cell with coordinates X and	Y.

       reset
	   Recalculates	internal geometry variables.

       select_all
	   Marks all cells as selected,	if "multiSelect" is 1.

       std_draw_text_cells CANVAS, COLUMNS, ROWS, AREA
	   An optimized	bulk routine for text-oriented grid widgets. The
	   optimization	is achieved under assumption that each cell is drawn
	   with	two colors only, so the	color switching	can be reduced.

	   The routine itself paints the cells background, and calls
	   "draw_text_cells" to	draw text and/or otherwise draw	the cell
	   content.

	   For explanation of COLUMNS, ROWS, and AREA parameters see
	   draw_cells .

   Events
       DrawCell	CANVAS,	COLUMN,	ROW, INDENT, @SCREEN_RECT, @CELL_RECT,
       SELECTED, FOCUSED, PRELIGHT
	   Called when a cell with COLUMN and ROW coordinates is to be drawn
	   on CANVAS.  SCREEN_RECT is a	cell rectangle in widget coordinates,
	   where the item is to	be drawn. CELL_RECT is same as SCREEN_RECT,
	   but calculated as if	the cell is fully visible.

	   SELECTED, FOCUSED, and PRELIGHT are boolean flagss, if the cell
	   must	be drawn correspondingly in selected, focused, and pre-lighted
	   states.

       GetAlignment COLUMN, ROW, HORIZONTAL_ALIGN_REF, VERTICAL_ALIGN_REF
	   Puts	two text alignment "ta::" constants, assigned to cell with
	   COLUMN and ROW coordinates, into HORIZONTAL_ALIGN_REF and
	   VERTICAL_ALIGN_REF scalar references.

       GetRange	VERTICAL, INDEX, MIN, MAX
	   Puts	minimal	and maximal breadth of INDEXth column (	VERTICAL = 0 )
	   or row ( VERTICAL = 1) in corresponding MIN and MAX scalar
	   references.

       Measure VERTICAL, INDEX,	BREADTH
	   Puts	breadth	in pixels of INDEXth column ( VERTICAL = 0 ) or	row (
	   VERTICAL = 1) into BREADTH scalar reference.

	   This	notification by	default	may be called from within
	   "begin_paint_info/end_paint_info" brackets. To disable this feature
	   set internal	flag "{NoBulkPaintInfo}" to 1.

       SelectCell COLUMN, ROW
	   Called when a cell with COLUMN and ROW coordinates is focused.

       SetExtent VERTICAL, INDEX, BREADTH
	   Reports breadth in pixels of	INDEXth	column ( VERTICAL = 0 )	or row
	   ( VERTICAL =	1), as a response to "columnWidth" and "rowHeight"
	   calls.

       Stringify COLUMN, ROW, TEXT_REF
	   Puts	text string, assigned to cell with COLUMN and ROW coordinates,
	   into	TEXT_REF scalar	reference.

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

Prima::GridViewer
       The class implements cells data and geometry storage mechanism, but
       leaves the cell data format to the programmer. The cells	are accessible
       via "cells" property and	several	other helper routines.

       The cell	data are stored	in an array, where each	item corresponds to a
       row, and	contains array of scalars, where each corresponds to a column.
       All data	managing routines, that	accept two-dimensional arrays, assume
       that the	columns	arrays are of the same widths.

       For example, "[[1,2,3]]]" is a valid one-row, three-column structure,
       and "[[1,2],[2,3],[3,4]]" is a valid three-row, two-column structure.
       The structure "[[1],[2,3],[3,4]]" is invalid, since its first row has
       one column, while the others have two.

       "Prima::GridViewer" is derived from "Prima::AbstractGridViewer".

   Properties
       allowChangeCellHeight
	   Default value: 1

       allowChangeCellWidth
	   Default value: 1

       cell COLUMN, ROW, [ DATA	]
	   Run-time property. Selects the data in cell with COLUMN and ROW
	   coordinates.

       cells [ ARRAY ]
	   The property	accepts	or returns all cells as	a two-dimensional
	   rectangular array or	scalars.

       columns INDEX
	   A read-only property; returns number	of columns.

       rows INDEX
	   A read-only property; returns number	of rows.

   Methods
       add_column CELLS
	   Inserts one-dimensional array of scalars to the end of columns.

       add_columns CELLS
	   Inserts two-dimensional array of scalars to the end of columns.

       add_row CELLS
	   Inserts one-dimensional array of scalars to the end of rows.

       add_rows	CELLS
	   Inserts two-dimensional array of scalars to the end of rows.

       delete_columns OFFSET, LENGTH
	   Removes LENGTH columns starting from	OFFSET.	Negative values	are
	   accepted.

       delete_rows OFFSET, LENGTH
	   Removes LENGTH rows starting	from OFFSET. Negative values are
	   accepted.

       insert_column OFFSET, CELLS
	   Inserts one-dimensional array of scalars as column OFFSET.
	   Negative values are accepted.

       insert_columns OFFSET, CELLS
	   Inserts two-dimensional array of scalars in column OFFSET.
	   Negative values are accepted.

       insert_row
	   Inserts one-dimensional array of scalars as row OFFSET.  Negative
	   values are accepted.

       insert_rows
	   Inserts two-dimensional array of scalars in row OFFSET.  Negative
	   values are accepted.

Prima::Grid
       Descendant of "Prima::GridViewer", declares format of cells as a	single
       text string. Incorporating all functionality of its ascendants,
       provides	a standard text	grid widget.

   Methods
       get_cell_alignment COLUMN, ROW
	   Returns two "ta::" constants	for horizontal and vertical cell text
	   alignment.  Since the item storage organization is implemented,
	   does	so without calling "GetAlignment" notification.

       get_cell_text COLUMN, ROW
	   Returns text	string assigned	to cell	in COLUMN and ROW.  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, examples/grid.pl

perl v5.24.1			  2017-05-10		       Prima::Grids(3)

NAME | DESCRIPTION | Prima::AbstractGridViewer | Prima::AbstractGrid | Prima::GridViewer | Prima::Grid | AUTHOR | SEE ALSO

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

home | help