|
Prima::Grids - grid widgets |
Prima::Grids - grid widgets
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, 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 the Prima::IntUtils manpage.
drawHGrid property, constantCellHeight
property set to 0, and the changes to the vertical extents can be recorded
via SetExtent notification.
Default value: 0
drawVGrid property, constantCellWidth
property set to 0, and the changes to the horizontal extents can be recorded
via SetExtent notification.
Default value: 0
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
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
Default value: 0.
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.
undef,
rows have different heights.
Default value: undef
undef,
columns have different widths.
Default value: undef
gridColor.
Default value: 1
gridColor.
Default value: 1
Default value: cl::Black .
Default value: 3
Default value: cl::Gray .
Default value: cl::Gray .
Default value: 0
Default value: 0.
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.
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.
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.
multiSelect is 1.
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 the Prima::IntUtils manpage ).
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.
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.
Stringify notification.
The method calls GetRange notification.
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 indeces 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 indeces 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.
( $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 yIf -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 +1, the coordinate is on the right/bottom to the cell body, but outside the widget.
x_type and y_typex 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_gridallowChangeCellHeight 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_topx_grid or y_grid. Select indeces of
cells adjacent to the grid line.
x_gap and y_gapnormalindentgridexteriormultiSelect is 1.
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 .
SELECTED and FOCUSED are boolean flags, if the cell must be drawn correspondingly in selected and focused states.
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.
columnWidth and rowHeight calls.
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.
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.
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.
$grid = Prima::Grid-> create(
cells => [
[qw(1.First 1.Second 1.Third)],
[qw(2.First 2.Second 3.Third)],
[qw(3.First 2.Second 3.Third)],
],
onClick => sub {
print $_[0]-> get_cell_text( $_[0]-> focusedCell), " is selected\n";
}
);
Stringify notification.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, the Prima::Widget manpage, examples/grid.pl
|
Prima::Grids - grid widgets |