1Prima::Grids(3) User Contributed Perl Documentation Prima::Grids(3)
2
6 Prima::Grids - grid widgets
7 SYNOPSIS
9 use Prima::Grids;
10 $grid = Prima::Grid-> create(
12 cells => [
13 [qw(1.First 1.Second 1.Third)],
14 [qw(2.First 2.Second 2.Third)],
15 [qw(3.First 3.Second 3.Third)],
16 ],
17 onClick => sub {
18 print $_[0]-> get_cell_text( $_[0]-> focusedCell), " is selected\n";
19 }
20 );
21
23 The module provides classes for several abstraction layers of grid
24 representation. The classes hierarchy is as follows:
25 AbstractGridViewer
27 AbstractGrid
28 GridViewer
29 Grid
30 The root class, "Prima::AbstractGridViewer", provides common interface,
32 while by itself it is not directly usable. The main differences
33 between classes are centered around the way the cell data are stored.
34 The simplest organization of a text-only cell, provided by
35 "Prima::Grid", stores data as a two-dimensional array of text scalars.
36 More elaborated storage and representation types are not realized, and
37 the programmer is urged to use the more abstract classes to derive own
38 mechanisms. To organize an item storage, different from "Prima::Grid",
39 it is usually enough to overload either the "Stringify", "Measure", and
40 "DrawCell" events, or their method counterparts: "get_cell_text",
41 "columnWidth", "rowHeight", and "draw_items".
42 The grid widget is designed to contain cells of variable extents, of
44 two types, normal and indent. The indent rows and columns are displayed
45 in grid margins, and their cell are drawn with distinguished colors.
46 An example use for a bottom indent row is a sum row in a spreadsheet
47 application; the top indent row can be used for displaying columns'
48 headers. The normal cells can be selected by the user, scrolled, and
49 selected. The cell selection can only contain rectangular areas, and
50 therefore is operated with two integer pairs with the beginning and the
51 end of the selection.
52 The widget operates in two visual scrolling modes; when the space
54 allows, the scrollbars affect the leftmost and the topmost cell. When
55 the widget is not large enough to accommodate at least one cell and all
56 indent cells, the layout is scrolled pixel-wise. These modes are named
57 'cell' and 'pixel', after the scrolling units.
58 The widget allows the interactive changing of cell widths and heights
60 by dragging the grid lines between the cells.
61
63 "Prima::AbstractGridViewer", the base for all grid widgets in the
64 module, provides interface to generic grid browsing functionality, plus
65 functionality for text-oriented grids. The class is not usable
66 directly.
67 "Prima::AbstractGridViewer" is a descendant of "Prima::GroupScroller",
69 and some properties are not described here. See "Prima::GroupScroller"
70 in Prima::IntUtils.
71 Properties
73 allowChangeCellHeight BOOLEAN
74 If 1, the user is allowed to change vertical extents of cells by
75 dragging the horizontal grid lines. Prerequisites to the options
76 are: the lines must be set visible via "drawHGrid" property,
77 "constantCellHeight" property set to 0, and the changes to the
78 vertical extents can be recorded via "SetExtent" notification.
79 Default value: 0
81 allowChangeCellWidth BOOLEAN
83 If 1, the user is allowed to change horizontal extents of cells by
84 dragging the horizontal grid lines. Prerequisites to the options
85 are: the lines must be set visible via "drawVGrid" property,
86 "constantCellWidth" property set to 0, and the changes to the
87 horizontal extents can be recorded via "SetExtent" notification.
88 Default value: 0
90 cellIndents X1, Y1, X2, Y2
92 Marks the marginal rows and columns as 'indent' cells. The indent
93 cells are drawn with another color pair ( see indentCellColor,
94 indentCellBackColor ), cannot be selected and scrolled. X1 and X2
95 correspond to amount of indent columns, and Y1 and Y2, - to the
96 indent rows.
97 "leftCell" and "topCell" do not count the indent cells as the
99 leftmost or topmost visible cell; in other words, X1 and Y1 are
100 minimal values for "leftCell" and "topCell" properties.
101 Default value: 0,0,0,0
103 clipCells INTEGER
105 A three-state integer property, that governs the way clipping is
106 applied when cells are drawn. Depending on kind of graphic in
107 cells, the clipping may be necessary, or unnecessary.
108 If the value is 1, the clipping is applied for every column drawn,
110 as the default drawing routines proceed column-wise. If the value
111 is 2, the clipping as applied for every cell. This setting reduces
112 the drawing speed significantly. If the value is 0, no clipping is
113 applied.
114 This property is destined for custom-drawn grid widgets, when it is
116 the developer's task to decide what kind of clipping suits better.
117 Text grid widgets, "Prima::AbstractGrid" and "Prima::Grid", are
118 safe with "clipCells" set to 1.
119 Default value: 1
121 columns INTEGER
123 Sets number of columns, including the indent columns. The number of
124 columns must be larger than the number of indent columns.
125 Default value: 0.
127 columnWidth COLUMN [ WIDTH ]
129 A run-time property, selects width of a column. To acquire or set
130 the width, "Measure" and "SetExtent" notifications can be invoked.
131 Result of "Measure" may be cached internally using
132 "cache_geometry_requests" method.
133 The width does not include widths of eventual vertical grid lines.
135 If "constantCellWidth" is defined, the property is used as its
137 alias.
138 constantCellHeight HEIGHT
140 If defined, all rows have equal height, HEIGHT pixels. If "undef",
141 rows have different heights.
142 Default value: undef
144 constantCellWidth WIDTH
146 If defined, all rows have equal width, WIDTH pixels. If "undef",
147 columns have different widths.
148 Default value: undef
150 drawHGrid BOOLEAN
152 If 1, horizontal grid lines between cells are drawn with
153 "gridColor".
154 Default value: 1
156 drawVGrid
158 If 1, vertical grid lines between cells are drawn with "gridColor".
159 Default value: 1
161 dx INTEGER
163 A run-time property. Selects horizontal offset in pixels of grid
164 layout in pixel mode.
165 dy INTEGER
167 A run-time property. Selects vertical offset in pixels of grid
168 layout in pixel mode.
169 focusedCell X, Y
171 Selects coordinates or the focused cell.
172 gridColor COLOR
174 Selects the color of grid lines.
175 Default value: "cl::Black" .
177 gridGravity INTEGER
179 The property selects the breadth of area around the grid lines,
180 that reacts on grid-dragging mouse events. The minimal value, 0,
181 marks only grid lines as the drag area, but makes the dragging
182 operation inconvenient for the user. Larger values make the
183 dragging more convenient, but increase the chance that the user
184 will not be able to select too narrow cells with the mouse.
185 Default value: 3
187 indentCellBackColor COLOR
189 Selects the background color of indent cells.
190 Default value: "cl::Gray" .
192 indentCellColor
194 Selects the foreground color of indent cells.
195 Default value: "cl::Gray" .
197 leftCell INTEGER
199 Selects index of the leftmost visible normal cell.
200 multiSelect BOOLEAN
202 If 1, the normal cells in an arbitrary rectangular area can be
203 marked as selected ( see selection ). If 0, only one cell at a time
204 can be selected.
205 Default value: 0
207 rows INTEGER
209 Sets number of rows, including the indent rows. The number of rows
210 must be larger than the number of indent rows.
211 Default value: 0.
213 topCell
215 Selects index of the topmost visible normal cell.
216 rowHeight INTEGER
218 A run-time property, selects height of a row. To acquire or set the
219 height, "Measure" and "SetExtent" notifications can be invoked.
220 Result of "Measure" may be cached internally using
221 "cache_geometry_requests" method.
222 The height does not include widths of eventual horizontal grid
224 lines.
225 If "constantCellHeight" is defined, the property is used as its
227 alias.
228 selection X1, Y1, X2, Y2
230 If "multiSelect" is 1, governs the extents of a rectangular area,
231 that contains selected cells. If no such area is present, selection
232 is (-1,-1,-1,-1), and "has_selection" returns 0 .
233 If "multiSelect" is 0, in get-mode returns the focused cell, and
235 discards the parameters in the set-mode.
236 Methods
238 cache_geometry_requests CACHE
239 If CACHE is 1, starts caching results of "Measure" notification,
240 thus lighting the subsequent "columnWidth" and "rowHeight" calls;
241 if CACHE is 0, flushes the cache.
242 If a significant geometry change was during the caching, the cache
244 is not updated, so it is the caller's responsibility to flush the
245 cache.
246 deselect_all
248 Nullifies the selection, if "multiSelect" is 1.
249 draw_cells CANVAS, COLUMNS, ROWS, AREA
251 A bulk draw routine, called from "onPaint" to draw cells. AREA is
252 an array of four integers with inclusive-inclusive coordinates of
253 the widget inferior without borders and scrollbars ( result of
254 get_active_area(2) call; see "get_active_area" in Prima::IntUtils
255 ).
256 COLUMNS and ROWS are structures that reflect the columns and rows
258 of the cells to be drawn. Each item in these corresponds to a
259 column or row, and is an array with the following layout:
260 0: column or row index
262 1: type; 0 - normal cell, 1 - indent cell
263 2: visible cell breadth
264 3: visible cell start
265 4: visible cell end
266 5: real cell start
267 6: real cell end
268 The coordinates are in inclusive-inclusive coordinate system, and
270 do not include eventual grid space, nor gaps between indent and
271 normal cells. By default, internal arrays "{colsDraw}" and
272 "{rowsDraw}" are passed as COLUMNS and ROWS parameters.
273 In "Prima::AbstractGrid" and "Prima::Grid" classes <draw_cells> is
275 overloaded to transfer the call to "std_draw_text_cells", the text-
276 oriented optimized routine.
277 draw_text_cells SCREEN_RECTANGLES, CELL_RECTANGLES, CELL_INDECES,
279 FONT_HEIGHT
280 A bulk routine for drawing text cells, called from
281 "std_draw_text_cells" .
282 SCREEN_RECTANGLES and CELL_RECTANGLES are arrays, where each item
284 is a rectangle with exterior of a cell. SCREEN_RECTANGLES contains
285 rectangles that cover the cell visible area; CELL_RECTANGLES
286 contains rectangles that span the cell extents disregarding its
287 eventual partial visibility. For example, a 100-pixel cell with
288 only its left half visible, would contain corresponding arrays
289 [150,150,200,250] in SCREEN_RECTANGLES, and [150,150,250,250] in
290 CELL_RECTANGLES.
291 CELL_INDECES contains arrays of the cell coordinates; each array
293 item is an array of integer pair where item 0 is column, and item 1
294 is row of the cell.
295 FONT_HEIGHT is a current font height value, cached since
297 "draw_text_cells" is often used for text operations and may require
298 vertical text justification.
299 get_cell_area [ WIDTH, HEIGHT ]
301 Returns screen area in inclusive-inclusive pixel coordinates, that
302 is used to display normal cells. The extensions are related to the
303 current size of a widget, however, can be overridden by specifying
304 WIDTH and HEIGHT.
305 get_cell_alignment COLUMN, ROW
307 Returns two "ta::" constants for horizontal and vertical cell text
308 alignment. Since the class does not assume the item storage
309 organization, the values are queried via "GetAlignment"
310 notification.
311 get_cell_text COLUMN, ROW
313 Returns text string assigned to cell in COLUMN and ROW. Since the
314 class does not assume the item storage organization, the text is
315 queried via "Stringify" notification.
316 get_range VERTICAL, INDEX
318 Returns a pair of integers, minimal and maximal breadth of INDEXth
319 column or row in pixels. If VERTICAL is 1, the rows are queried; if
320 0, the columns.
321 The method calls "GetRange" notification.
323 get_screen_cell_info COLUMN, ROW
325 Returns information about a cell in COLUMN and ROW, if it is
326 currently visible. The returned parameters are indexed by
327 "gsci::XXX" constants, and explained below:
328 gsci::COL_INDEX - visual column number where the cell displayed
330 gsci::ROW_INDEX - visual row number where the cell displayed
331 gsci::V_FULL - cell is fully visible
332 gsci::V_LEFT - inclusive-inclusive rectangle of the visible
334 gsci::V_BOTTOM part of the cell. These four indices are grouped
335 gsci::V_RIGHT under list constant, gsci::V_RECT.
336 gsci::V_TOP
337 gsci::LEFT - inclusive-inclusive rectangle of the cell, as if
339 gsci::BOTTOM it is fully visible. These four indices are grouped
340 gsci::RIGHT under list constant, gsci::RECT. If gsci::V_FULL
341 gsci::TOP is 1, these values are identical to these in gsci::V_RECT.
342 If the cell is not visible, returns empty array.
344 has_selection
346 Returns a boolean value, indicating whether the grid contains a
347 selection (1) or not (0).
348 point2cell X, Y, [ OMIT_GRID = 0 ]
350 Return information about point X, Y in widget coordinates. The
351 method returns two integers, CX and CY, with cell coordinates, and
352 eventual HINTS hash, with more information about pixe localtion. If
353 OMIT_GRID is set to 1 and the pixel belongs to a grid, the pixels
354 is treated a part of adjacent cell. The call syntax:
355 ( $CX, $CY, %HINTS) = $self->point2cell( $X, $Y);
357 If the pixel lies within cell boundaries by either coordinate, CX
359 and/or CY are correspondingly set to cell column and/or row. When
360 the pixel is outside cell space, CX and/or CY are set to -1.
361 HINTS may contain the following values:
363 "x" and "y"
365 If 0, the coordinate lies within boundaries of a cell.
366 If -1, the coordinate is on the left/top to the cell body.
368 If +1, the coordinate is on the right/bottom to the cell body,
370 but within the widget.
371 If +2, the coordinate is on the right/bottom to the cell body,
373 but outside the widget.
374 "x_type" and "y_type"
376 Present when "x" or "y" values are 0.
377 If 0, the cell is a normal cell.
379 If -1, the cell is left/top indent cell.
381 If +1, the cell is right/bottom indent cell.
383 "x_grid" and "y_grid"
385 If 1, the point is over a grid line. This case can only happen
386 when OMIT_GRID is 0. If "allowChangeCellHeight" and/or
387 "allowChangeCellWidth" are set, treats also "gridGravity"-broad
388 pixels strips on both sides of the line as the grid area.
389 Also values of "x_left"/"x_right" or "y_bottom"/"y_top" might
391 be set.
392 "x_left"/"x_right" and "y_bottom"/"y_top"
394 Present together with "x_grid" or "y_grid". Select indices of
395 cells adjacent to the grid line.
396 "x_gap" and "y_gap"
398 If 1, the point is within a gap between the last normal cell
399 and the first right/bottom indent cell.
400 "normal"
402 If 1, the point lies within the boundaries of a normal cell.
403 "indent"
405 If 1, the point lies within the boundaries of an indent cell.
406 "grid"
408 If 1, the point is over a grid line.
409 "exterior"
411 If 1, the point is in inoperable area or outside the widget
412 boundaries.
413 redraw_cell X, Y
415 Repaints cell with coordinates X and Y.
416 reset
418 Recalculates internal geometry variables.
419 select_all
421 Marks all cells as selected, if "multiSelect" is 1.
422 std_draw_text_cells CANVAS, COLUMNS, ROWS, AREA
424 An optimized bulk routine for text-oriented grid widgets. The
425 optimization is achieved under assumption that each cell is drawn
426 with two colors only, so the color switching can be reduced.
427 The routine itself paints the cells background, and calls
429 "draw_text_cells" to draw text and/or otherwise draw the cell
430 content.
431 For explanation of COLUMNS, ROWS, and AREA parameters see
433 draw_cells .
434 Events
436 DrawCell CANVAS, COLUMN, ROW, INDENT, @SCREEN_RECT, @CELL_RECT,
437 SELECTED, FOCUSED, PRELIGHT
438 Called when a cell with COLUMN and ROW coordinates is to be drawn
439 on CANVAS. SCREEN_RECT is a cell rectangle in widget coordinates,
440 where the item is to be drawn. CELL_RECT is same as SCREEN_RECT,
441 but calculated as if the cell is fully visible.
442 SELECTED, FOCUSED, and PRELIGHT are boolean flagss, if the cell
444 must be drawn correspondingly in selected, focused, and pre-lighted
445 states.
446 GetAlignment COLUMN, ROW, HORIZONTAL_ALIGN_REF, VERTICAL_ALIGN_REF
448 Puts two text alignment "ta::" constants, assigned to cell with
449 COLUMN and ROW coordinates, into HORIZONTAL_ALIGN_REF and
450 VERTICAL_ALIGN_REF scalar references.
451 GetRange VERTICAL, INDEX, MIN, MAX
453 Puts minimal and maximal breadth of INDEXth column ( VERTICAL = 0 )
454 or row ( VERTICAL = 1) in corresponding MIN and MAX scalar
455 references.
456 Measure VERTICAL, INDEX, BREADTH
458 Puts breadth in pixels of INDEXth column ( VERTICAL = 0 ) or row (
459 VERTICAL = 1) into BREADTH scalar reference.
460 This notification by default may be called from within
462 "begin_paint_info/end_paint_info" brackets. To disable this feature
463 set internal flag "{NoBulkPaintInfo}" to 1.
464 SelectCell COLUMN, ROW
466 Called when a cell with COLUMN and ROW coordinates is focused.
467 SetExtent VERTICAL, INDEX, BREADTH
469 Reports breadth in pixels of INDEXth column ( VERTICAL = 0 ) or row
470 ( VERTICAL = 1), as a response to "columnWidth" and "rowHeight"
471 calls.
472 Stringify COLUMN, ROW, TEXT_REF
474 Puts text string, assigned to cell with COLUMN and ROW coordinates,
475 into TEXT_REF scalar reference.
476
478 Exactly the same as its ascendant, "Prima::AbstractGridViewer", except
479 that it does not propagate "DrawItem" message, assuming that the items
480 must be drawn as text.
481
483 The class implements cells data and geometry storage mechanism, but
484 leaves the cell data format to the programmer. The cells are accessible
485 via "cells" property and several other helper routines.
486 The cell data are stored in an array, where each item corresponds to a
488 row, and contains array of scalars, where each corresponds to a column.
489 All data managing routines, that accept two-dimensional arrays, assume
490 that the columns arrays are of the same widths.
491 For example, "[[1,2,3]]]" is a valid one-row, three-column structure,
493 and "[[1,2],[2,3],[3,4]]" is a valid three-row, two-column structure.
494 The structure "[[1],[2,3],[3,4]]" is invalid, since its first row has
495 one column, while the others have two.
496 "Prima::GridViewer" is derived from "Prima::AbstractGridViewer".
498 Properties
500 allowChangeCellHeight
501 Default value: 1
502 allowChangeCellWidth
504 Default value: 1
505 cell COLUMN, ROW, [ DATA ]
507 Run-time property. Selects the data in cell with COLUMN and ROW
508 coordinates.
509 cells [ ARRAY ]
511 The property accepts or returns all cells as a two-dimensional
512 rectangular array or scalars.
513 columns INDEX
515 A read-only property; returns number of columns.
516 rows INDEX
518 A read-only property; returns number of rows.
519 Methods
521 add_column CELLS
522 Inserts one-dimensional array of scalars to the end of columns.
523 add_columns CELLS
525 Inserts two-dimensional array of scalars to the end of columns.
526 add_row CELLS
528 Inserts one-dimensional array of scalars to the end of rows.
529 add_rows CELLS
531 Inserts two-dimensional array of scalars to the end of rows.
532 delete_columns OFFSET, LENGTH
534 Removes LENGTH columns starting from OFFSET. Negative values are
535 accepted.
536 delete_rows OFFSET, LENGTH
538 Removes LENGTH rows starting from OFFSET. Negative values are
539 accepted.
540 insert_column OFFSET, CELLS
542 Inserts one-dimensional array of scalars as column OFFSET.
543 Negative values are accepted.
544 insert_columns OFFSET, CELLS
546 Inserts two-dimensional array of scalars in column OFFSET.
547 Negative values are accepted.
548 insert_row
550 Inserts one-dimensional array of scalars as row OFFSET. Negative
551 values are accepted.
552 insert_rows
554 Inserts two-dimensional array of scalars in row OFFSET. Negative
555 values are accepted.
556
558 Descendant of "Prima::GridViewer", declares format of cells as a single
559 text string. Incorporating all functionality of its ascendants,
560 provides a standard text grid widget.
561 Methods
563 get_cell_alignment COLUMN, ROW
564 Returns two "ta::" constants for horizontal and vertical cell text
565 alignment. Since the item storage organization is implemented,
566 does so without calling "GetAlignment" notification.
567 get_cell_text COLUMN, ROW
569 Returns text string assigned to cell in COLUMN and ROW. Since the
570 item storage organization is implemented, does so without calling
571 "Stringify" notification.
572
574 Dmitry Karasik, <dmitry@karasik.eu.org>.
575
577 Prima, Prima::Widget, examples/grid.pl
578perl v5.28.0 2017-05-10 Prima::Grids(3)