1Prima::Grids(3) User Contributed Perl Documentation Prima::Grids(3)
2
6 Prima::Grids - grid widgets
7 SYNOPSIS
9 use Prima qw(Grids Application);
10 my $grid = Prima::Grid-> new(
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 run Prima;
22
24 The module provides classes for several abstraction layers of grid
25 representation. The classes hierarchy is as follows:
26 AbstractGridViewer
28 AbstractGrid
29 GridViewer
30 Grid
31 The root class, "Prima::AbstractGridViewer", provides common interface,
33 while by itself it is not directly usable. The main differences
34 between classes are centered around the way the cell data are stored.
35 The simplest organization of a text-only cell, provided by
36 "Prima::Grid", stores data as a two-dimensional array of text scalars.
37 More elaborated storage and representation types are not realized, and
38 the programmer is urged to use the more abstract classes to derive own
39 mechanisms. To organize an item storage, different from "Prima::Grid",
40 it is usually enough to overload either the "Stringify", "Measure", and
41 "DrawCell" events, or their method counterparts: "get_cell_text",
42 "columnWidth", "rowHeight", and "draw_items".
43 The grid widget is designed to contain cells of variable extents, of
45 two types, normal and indent. The indent rows and columns are displayed
46 in grid margins, and their cell are drawn with distinguished colors.
47 An example use for a bottom indent row is a sum row in a spreadsheet
48 application; the top indent row can be used for displaying columns'
49 headers. The normal cells can be selected by the user, scrolled, and
50 selected. The cell selection can only contain rectangular areas, and
51 therefore is operated with two integer pairs with the beginning and the
52 end of the selection.
53 The widget operates in two visual scrolling modes; when the space
55 allows, the scrollbars affect the leftmost and the topmost cell. When
56 the widget is not large enough to accommodate at least one cell and all
57 indent cells, the layout is scrolled pixel-wise. These modes are named
58 'cell' and 'pixel', after the scrolling units.
59 The widget allows the interactive changing of cell widths and heights
61 by dragging the grid lines between the cells.
62
64 "Prima::AbstractGridViewer", the base for all grid widgets in the
65 module, provides interface to generic grid browsing functionality, plus
66 functionality for text-oriented grids. The class is not usable
67 directly.
68 "Prima::AbstractGridViewer" is a descendant of
70 "Prima::Widget::GroupScroller", and some properties are not described
71 here.
72 Properties
74 allowChangeCellHeight BOOLEAN
75 If 1, the user is allowed to change vertical extents of cells by
76 dragging the horizontal grid lines. Prerequisites to the options
77 are: the lines must be set visible via "drawHGrid" property,
78 "constantCellHeight" property set to 0, and the changes to the
79 vertical extents can be recorded via "SetExtent" notification.
80 Default value: 0
82 allowChangeCellWidth BOOLEAN
84 If 1, the user is allowed to change horizontal extents of cells by
85 dragging the horizontal grid lines. Prerequisites to the options
86 are: the lines must be set visible via "drawVGrid" property,
87 "constantCellWidth" property set to 0, and the changes to the
88 horizontal extents can be recorded via "SetExtent" notification.
89 Default value: 0
91 cellIndents X1, Y1, X2, Y2
93 Marks the marginal rows and columns as 'indent' cells. The indent
94 cells are drawn with another color pair ( see indentCellColor,
95 indentCellBackColor ), cannot be selected and scrolled. X1 and X2
96 correspond to amount of indent columns, and Y1 and Y2, - to the
97 indent rows.
98 "leftCell" and "topCell" do not count the indent cells as the
100 leftmost or topmost visible cell; in other words, X1 and Y1 are
101 minimal values for "leftCell" and "topCell" properties.
102 Default value: 0,0,0,0
104 clipCells INTEGER
106 A three-state integer property, that governs the way clipping is
107 applied when cells are drawn. Depending on kind of graphic in
108 cells, the clipping may be necessary, or unnecessary.
109 If the value is 1, the clipping is applied for every column drawn,
111 as the default drawing routines proceed column-wise. If the value
112 is 2, the clipping as applied for every cell. This setting reduces
113 the drawing speed significantly. If the value is 0, no clipping is
114 applied.
115 This property is destined for custom-drawn grid widgets, when it is
117 the developer's task to decide what kind of clipping suits better.
118 Text grid widgets, "Prima::AbstractGrid" and "Prima::Grid", are
119 safe with "clipCells" set to 1.
120 Default value: 1
122 columns INTEGER
124 Sets number of columns, including the indent columns. The number of
125 columns must be larger than the number of indent columns.
126 Default value: 0.
128 columnWidth COLUMN [ WIDTH ]
130 A run-time property, selects width of a column. To acquire or set
131 the width, "Measure" and "SetExtent" notifications can be invoked.
132 Result of "Measure" may be cached internally using
133 "cache_geometry_requests" method.
134 The width does not include widths of eventual vertical grid lines.
136 If "constantCellWidth" is defined, the property is used as its
138 alias.
139 constantCellHeight HEIGHT
141 If defined, all rows have equal height, HEIGHT pixels. If "undef",
142 rows have different heights.
143 Default value: undef
145 constantCellWidth WIDTH
147 If defined, all rows have equal width, WIDTH pixels. If "undef",
148 columns have different widths.
149 Default value: undef
151 drawHGrid BOOLEAN
153 If 1, horizontal grid lines between cells are drawn with
154 "gridColor".
155 Default value: 1
157 drawVGrid
159 If 1, vertical grid lines between cells are drawn with "gridColor".
160 Default value: 1
162 dx INTEGER
164 A run-time property. Selects horizontal offset in pixels of grid
165 layout in pixel mode.
166 dy INTEGER
168 A run-time property. Selects vertical offset in pixels of grid
169 layout in pixel mode.
170 focusedCell X, Y
172 Selects coordinates or the focused cell.
173 gridColor COLOR
175 Selects the color of grid lines.
176 Default value: "cl::Black" .
178 gridGravity INTEGER
180 The property selects the breadth of area around the grid lines,
181 that reacts on grid-dragging mouse events. The minimal value, 0,
182 marks only grid lines as the drag area, but makes the dragging
183 operation inconvenient for the user. Larger values make the
184 dragging more convenient, but increase the chance that the user
185 will not be able to select too narrow cells with the mouse.
186 Default value: 3
188 indentCellBackColor COLOR
190 Selects the background color of indent cells.
191 Default value: "cl::Gray" .
193 indentCellColor
195 Selects the foreground color of indent cells.
196 Default value: "cl::Gray" .
198 leftCell INTEGER
200 Selects index of the leftmost visible normal cell.
201 multiSelect BOOLEAN
203 If 1, the normal cells in an arbitrary rectangular area can be
204 marked as selected ( see selection ). If 0, only one cell at a time
205 can be selected.
206 Default value: 0
208 rows INTEGER
210 Sets number of rows, including the indent rows. The number of rows
211 must be larger than the number of indent rows.
212 Default value: 0.
214 topCell
216 Selects index of the topmost visible normal cell.
217 rowHeight INTEGER
219 A run-time property, selects height of a row. To acquire or set the
220 height, "Measure" and "SetExtent" notifications can be invoked.
221 Result of "Measure" may be cached internally using
222 "cache_geometry_requests" method.
223 The height does not include widths of eventual horizontal grid
225 lines.
226 If "constantCellHeight" is defined, the property is used as its
228 alias.
229 selection X1, Y1, X2, Y2
231 If "multiSelect" is 1, governs the extents of a rectangular area,
232 that contains selected cells. If no such area is present, selection
233 is (-1,-1,-1,-1), and "has_selection" returns 0 .
234 If "multiSelect" is 0, in get-mode returns the focused cell, and
236 discards the parameters in the set-mode.
237 Methods
239 cache_geometry_requests CACHE
240 If CACHE is 1, starts caching results of "Measure" notification,
241 thus lighting the subsequent "columnWidth" and "rowHeight" calls;
242 if CACHE is 0, flushes the cache.
243 If a significant geometry change was during the caching, the cache
245 is not updated, so it is the caller's responsibility to flush the
246 cache.
247 deselect_all
249 Nullifies the selection, if "multiSelect" is 1.
250 draw_cells CANVAS, COLUMNS, ROWS, AREA
252 A bulk draw routine, called from "onPaint" to draw cells. AREA is
253 an array of four integers with inclusive-inclusive coordinates of
254 the widget inferior without borders and scrollbars ( result of
255 get_active_area(2) call; see "get_active_area" in
256 Prima::Widget::IntIndents ).
257 COLUMNS and ROWS are structures that reflect the columns and rows
259 of the cells to be drawn. Each item in these corresponds to a
260 column or row, and is an array with the following layout:
261 0: column or row index
263 1: type; 0 - normal cell, 1 - indent cell
264 2: visible cell breadth
265 3: visible cell start
266 4: visible cell end
267 5: real cell start
268 6: real cell end
269 The coordinates are in inclusive-inclusive coordinate system, and
271 do not include eventual grid space, nor gaps between indent and
272 normal cells. By default, internal arrays "{colsDraw}" and
273 "{rowsDraw}" are passed as COLUMNS and ROWS parameters.
274 In "Prima::AbstractGrid" and "Prima::Grid" classes <draw_cells> is
276 overloaded to transfer the call to "std_draw_text_cells", the text-
277 oriented optimized routine.
278 draw_text_cells SCREEN_RECTANGLES, CELL_RECTANGLES, CELL_INDECES,
280 FONT_HEIGHT
281 A bulk routine for drawing text cells, called from
282 "std_draw_text_cells" .
283 SCREEN_RECTANGLES and CELL_RECTANGLES are arrays, where each item
285 is a rectangle with exterior of a cell. SCREEN_RECTANGLES contains
286 rectangles that cover the cell visible area; CELL_RECTANGLES
287 contains rectangles that span the cell extents disregarding its
288 eventual partial visibility. For example, a 100-pixel cell with
289 only its left half visible, would contain corresponding arrays
290 [150,150,200,250] in SCREEN_RECTANGLES, and [150,150,250,250] in
291 CELL_RECTANGLES.
292 CELL_INDECES contains arrays of the cell coordinates; each array
294 item is an array of integer pair where item 0 is column, and item 1
295 is row of the cell.
296 FONT_HEIGHT is a current font height value, cached since
298 "draw_text_cells" is often used for text operations and may require
299 vertical text justification.
300 get_cell_area [ WIDTH, HEIGHT ]
302 Returns screen area in inclusive-inclusive pixel coordinates, that
303 is used to display normal cells. The extensions are related to the
304 current size of a widget, however, can be overridden by specifying
305 WIDTH and HEIGHT.
306 get_cell_alignment COLUMN, ROW
308 Returns two "ta::" constants for horizontal and vertical cell text
309 alignment. Since the class does not assume the item storage
310 organization, the values are queried via "GetAlignment"
311 notification.
312 get_cell_text COLUMN, ROW
314 Returns text string assigned to cell in COLUMN and ROW. Since the
315 class does not assume the item storage organization, the text is
316 queried via "Stringify" notification.
317 get_range VERTICAL, INDEX
319 Returns a pair of integers, minimal and maximal breadth of INDEXth
320 column or row in pixels. If VERTICAL is 1, the rows are queried; if
321 0, the columns.
322 The method calls "GetRange" notification.
324 get_screen_cell_info COLUMN, ROW
326 Returns information about a cell in COLUMN and ROW, if it is
327 currently visible. The returned parameters are indexed by
328 "gsci::XXX" constants, and explained below:
329 gsci::COL_INDEX - visual column number where the cell displayed
331 gsci::ROW_INDEX - visual row number where the cell displayed
332 gsci::V_FULL - cell is fully visible
333 gsci::V_LEFT - inclusive-inclusive rectangle of the visible
335 gsci::V_BOTTOM part of the cell. These four indices are grouped
336 gsci::V_RIGHT under list constant, gsci::V_RECT.
337 gsci::V_TOP
338 gsci::LEFT - inclusive-inclusive rectangle of the cell, as if
340 gsci::BOTTOM it is fully visible. These four indices are grouped
341 gsci::RIGHT under list constant, gsci::RECT. If gsci::V_FULL
342 gsci::TOP is 1, these values are identical to these in gsci::V_RECT.
343 If the cell is not visible, returns empty array.
345 has_selection
347 Returns a boolean value, indicating whether the grid contains a
348 selection (1) or not (0).
349 point2cell X, Y, [ OMIT_GRID = 0 ]
351 Return information about point X, Y in widget coordinates. The
352 method returns two integers, CX and CY, with cell coordinates, and
353 eventual HINTS hash, with more information about pixe localtion. If
354 OMIT_GRID is set to 1 and the pixel belongs to a grid, the pixels
355 is treated a part of adjacent cell. The call syntax:
356 ( $CX, $CY, %HINTS) = $self->point2cell( $X, $Y);
358 If the pixel lies within cell boundaries by either coordinate, CX
360 and/or CY are correspondingly set to cell column and/or row. When
361 the pixel is outside cell space, CX and/or CY are set to -1.
362 HINTS may contain the following values:
364 "x" and "y"
366 If 0, the coordinate lies within boundaries of a cell.
367 If -1, the coordinate is on the left/top to the cell body.
369 If +1, the coordinate is on the right/bottom to the cell body,
371 but within the widget.
372 If +2, the coordinate is on the right/bottom to the cell body,
374 but outside the widget.
375 "x_type" and "y_type"
377 Present when "x" or "y" values are 0.
378 If 0, the cell is a normal cell.
380 If -1, the cell is left/top indent cell.
382 If +1, the cell is right/bottom indent cell.
384 "x_grid" and "y_grid"
386 If 1, the point is over a grid line. This case can only happen
387 when OMIT_GRID is 0. If "allowChangeCellHeight" and/or
388 "allowChangeCellWidth" are set, treats also "gridGravity"-broad
389 pixels strips on both sides of the line as the grid area.
390 Also values of "x_left"/"x_right" or "y_bottom"/"y_top" might
392 be set.
393 "x_left"/"x_right" and "y_bottom"/"y_top"
395 Present together with "x_grid" or "y_grid". Select indices of
396 cells adjacent to the grid line.
397 "x_gap" and "y_gap"
399 If 1, the point is within a gap between the last normal cell
400 and the first right/bottom indent cell.
401 "normal"
403 If 1, the point lies within the boundaries of a normal cell.
404 "indent"
406 If 1, the point lies within the boundaries of an indent cell.
407 "grid"
409 If 1, the point is over a grid line.
410 "exterior"
412 If 1, the point is in inoperable area or outside the widget
413 boundaries.
414 redraw_cell X, Y
416 Repaints cell with coordinates X and Y.
417 reset
419 Recalculates internal geometry variables.
420 select_all
422 Marks all cells as selected, if "multiSelect" is 1.
423 std_draw_text_cells CANVAS, COLUMNS, ROWS, AREA
425 An optimized bulk routine for text-oriented grid widgets. The
426 optimization is achieved under assumption that each cell is drawn
427 with two colors only, so the color switching can be reduced.
428 The routine itself paints the cells background, and calls
430 "draw_text_cells" to draw text and/or otherwise draw the cell
431 content.
432 For explanation of COLUMNS, ROWS, and AREA parameters see
434 draw_cells .
435 Events
437 DrawCell CANVAS, COLUMN, ROW, INDENT, @SCREEN_RECT, @CELL_RECT,
438 SELECTED, FOCUSED, PRELIGHT
439 Called when a cell with COLUMN and ROW coordinates is to be drawn
440 on CANVAS. SCREEN_RECT is a cell rectangle in widget coordinates,
441 where the item is to be drawn. CELL_RECT is same as SCREEN_RECT,
442 but calculated as if the cell is fully visible.
443 SELECTED, FOCUSED, and PRELIGHT are boolean flagss, if the cell
445 must be drawn correspondingly in selected, focused, and pre-lighted
446 states.
447 GetAlignment COLUMN, ROW, HORIZONTAL_ALIGN_REF, VERTICAL_ALIGN_REF
449 Puts two text alignment "ta::" constants, assigned to cell with
450 COLUMN and ROW coordinates, into HORIZONTAL_ALIGN_REF and
451 VERTICAL_ALIGN_REF scalar references.
452 GetRange VERTICAL, INDEX, MIN, MAX
454 Puts minimal and maximal breadth of INDEXth column ( VERTICAL = 0 )
455 or row ( VERTICAL = 1) in corresponding MIN and MAX scalar
456 references.
457 Measure VERTICAL, INDEX, BREADTH
459 Puts breadth in pixels of INDEXth column ( VERTICAL = 0 ) or row (
460 VERTICAL = 1) into BREADTH scalar reference.
461 This notification by default may be called from within
463 "begin_paint_info/end_paint_info" brackets. To disable this feature
464 set internal flag "{NoBulkPaintInfo}" to 1.
465 SelectCell COLUMN, ROW
467 Called when a cell with COLUMN and ROW coordinates is focused.
468 SetExtent VERTICAL, INDEX, BREADTH
470 Reports breadth in pixels of INDEXth column ( VERTICAL = 0 ) or row
471 ( VERTICAL = 1), as a response to "columnWidth" and "rowHeight"
472 calls.
473 Stringify COLUMN, ROW, TEXT_REF
475 Puts text string, assigned to cell with COLUMN and ROW coordinates,
476 into TEXT_REF scalar reference.
477
479 Exactly the same as its ascendant, "Prima::AbstractGridViewer", except
480 that it does not propagate "DrawItem" message, assuming that the items
481 must be drawn as text.
482
484 The class implements cells data and geometry storage mechanism, but
485 leaves the cell data format to the programmer. The cells are accessible
486 via "cells" property and several other helper routines.
487 The cell data are stored in an array, where each item corresponds to a
489 row, and contains array of scalars, where each corresponds to a column.
490 All data managing routines, that accept two-dimensional arrays, assume
491 that the columns arrays are of the same widths.
492 For example, "[[1,2,3]]]" is a valid one-row, three-column structure,
494 and "[[1,2],[2,3],[3,4]]" is a valid three-row, two-column structure.
495 The structure "[[1],[2,3],[3,4]]" is invalid, since its first row has
496 one column, while the others have two.
497 "Prima::GridViewer" is derived from "Prima::AbstractGridViewer".
499 Properties
501 allowChangeCellHeight
502 Default value: 1
503 allowChangeCellWidth
505 Default value: 1
506 cell COLUMN, ROW, [ DATA ]
508 Run-time property. Selects the data in cell with COLUMN and ROW
509 coordinates.
510 cells [ ARRAY ]
512 The property accepts or returns all cells as a two-dimensional
513 rectangular array or scalars.
514 columns INDEX
516 A read-only property; returns number of columns.
517 rows INDEX
519 A read-only property; returns number of rows.
520 Methods
522 add_column CELLS
523 Inserts one-dimensional array of scalars to the end of columns.
524 add_columns CELLS
526 Inserts two-dimensional array of scalars to the end of columns.
527 add_row CELLS
529 Inserts one-dimensional array of scalars to the end of rows.
530 add_rows CELLS
532 Inserts two-dimensional array of scalars to the end of rows.
533 delete_columns OFFSET, LENGTH
535 Removes LENGTH columns starting from OFFSET. Negative values are
536 accepted.
537 delete_rows OFFSET, LENGTH
539 Removes LENGTH rows starting from OFFSET. Negative values are
540 accepted.
541 insert_column OFFSET, CELLS
543 Inserts one-dimensional array of scalars as column OFFSET.
544 Negative values are accepted.
545 insert_columns OFFSET, CELLS
547 Inserts two-dimensional array of scalars in column OFFSET.
548 Negative values are accepted.
549 insert_row
551 Inserts one-dimensional array of scalars as row OFFSET. Negative
552 values are accepted.
553 insert_rows
555 Inserts two-dimensional array of scalars in row OFFSET. Negative
556 values are accepted.
557
559 Descendant of "Prima::GridViewer", declares format of cells as a single
560 text string. Incorporating all functionality of its ascendants,
561 provides a standard text grid widget.
562 Methods
564 get_cell_alignment COLUMN, ROW
565 Returns two "ta::" constants for horizontal and vertical cell text
566 alignment. Since the item storage organization is implemented,
567 does so without calling "GetAlignment" notification.
568 get_cell_text COLUMN, ROW
570 Returns text string assigned to cell in COLUMN and ROW. Since the
571 item storage organization is implemented, does so without calling
572 "Stringify" notification.
573
575 Dmitry Karasik, <dmitry@karasik.eu.org>.
576
578 Prima, Prima::Widget, examples/grid.pl
579perl v5.36.0 2023-03-20 Prima::Grids(3)