1Prima::Grids(3)       User Contributed Perl Documentation      Prima::Grids(3)
2
3
4

NAME

6       Prima::Grids - grid widgets
7
8   SYNOPSIS
9               use Prima qw(Grids Application);
10
11               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

DESCRIPTION

24       The module provides classes for several abstraction layers of grid
25       representation. The classes hierarchy is as follows:
26
27               AbstractGridViewer
28                       AbstractGrid
29                       GridViewer
30                               Grid
31
32       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
44       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
54       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
60       The widget allows the interactive changing of cell widths and heights
61       by dragging the grid lines between the cells.
62

Prima::AbstractGridViewer

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
69       "Prima::AbstractGridViewer" is a descendant of
70       "Prima::Widget::GroupScroller", and some properties are not described
71       here.
72
73   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
81           Default value: 0
82
83       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
90           Default value: 0
91
92       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
99           "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
103           Default value: 0,0,0,0
104
105       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
110           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
116           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
121           Default value: 1
122
123       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
127           Default value: 0.
128
129       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
135           The width does not include widths of eventual vertical grid lines.
136
137           If "constantCellWidth" is defined, the property is used as its
138           alias.
139
140       constantCellHeight HEIGHT
141           If defined, all rows have equal height, HEIGHT pixels. If "undef",
142           rows have different heights.
143
144           Default value: undef
145
146       constantCellWidth WIDTH
147           If defined, all rows have equal width, WIDTH pixels. If "undef",
148           columns have different widths.
149
150           Default value: undef
151
152       drawHGrid BOOLEAN
153           If 1, horizontal grid lines between cells are drawn with
154           "gridColor".
155
156           Default value: 1
157
158       drawVGrid
159           If 1, vertical grid lines between cells are drawn with "gridColor".
160
161           Default value: 1
162
163       dx INTEGER
164           A run-time property. Selects horizontal offset in pixels of grid
165           layout in pixel mode.
166
167       dy INTEGER
168           A run-time property. Selects vertical offset in pixels of grid
169           layout in pixel mode.
170
171       focusedCell X, Y
172           Selects coordinates or the focused cell.
173
174       gridColor COLOR
175           Selects the color of grid lines.
176
177           Default value: "cl::Black" .
178
179       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
187           Default value: 3
188
189       indentCellBackColor COLOR
190           Selects the background color of indent cells.
191
192           Default value: "cl::Gray" .
193
194       indentCellColor
195           Selects the foreground color of indent cells.
196
197           Default value: "cl::Gray" .
198
199       leftCell INTEGER
200           Selects index of the leftmost visible normal cell.
201
202       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
207           Default value: 0
208
209       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
213           Default value: 0.
214
215       topCell
216           Selects index of the topmost visible normal cell.
217
218       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
224           The height does not include widths of eventual horizontal grid
225           lines.
226
227           If "constantCellHeight" is defined, the property is used as its
228           alias.
229
230       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
235           If "multiSelect" is 0, in get-mode returns the focused cell, and
236           discards the parameters in the set-mode.
237
238   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
244           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
248       deselect_all
249           Nullifies the selection, if "multiSelect" is 1.
250
251       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
258           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
262                   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
270           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
275           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
279       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
284           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
293           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
297           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
301       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
307       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
313       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
318       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
323           The method calls "GetRange" notification.
324
325       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
330                   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
334                   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
339                   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
344           If the cell is not visible, returns empty array.
345
346       has_selection
347           Returns a boolean value, indicating whether the grid contains a
348           selection (1) or not (0).
349
350       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
357                   ( $CX, $CY, %HINTS) = $self->point2cell( $X, $Y);
358
359           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
363           HINTS may contain the following values:
364
365           "x" and "y"
366               If 0, the coordinate lies within boundaries of a cell.
367
368               If -1, the coordinate is on the left/top to the cell body.
369
370               If +1, the coordinate is on the right/bottom to the cell body,
371               but within the widget.
372
373               If +2, the coordinate is on the right/bottom to the cell body,
374               but outside the widget.
375
376           "x_type" and "y_type"
377               Present when "x" or "y" values are 0.
378
379               If 0, the cell is a normal cell.
380
381               If -1, the cell is left/top indent cell.
382
383               If +1, the cell is right/bottom indent cell.
384
385           "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
391               Also values of "x_left"/"x_right" or "y_bottom"/"y_top" might
392               be set.
393
394           "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
398           "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
402           "normal"
403               If 1, the point lies within the boundaries of a normal cell.
404
405           "indent"
406               If 1, the point lies within the boundaries of an indent cell.
407
408           "grid"
409               If 1, the point is over a grid line.
410
411           "exterior"
412               If 1, the point is in inoperable area or outside the widget
413               boundaries.
414
415       redraw_cell X, Y
416           Repaints cell with coordinates X and Y.
417
418       reset
419           Recalculates internal geometry variables.
420
421       select_all
422           Marks all cells as selected, if "multiSelect" is 1.
423
424       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
429           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
433           For explanation of COLUMNS, ROWS, and AREA parameters see
434           draw_cells .
435
436   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
444           SELECTED, FOCUSED, and PRELIGHT are boolean flagss, if the cell
445           must be drawn correspondingly in selected, focused, and pre-lighted
446           states.
447
448       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
453       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
458       Measure VERTICAL, INDEX, BREADTH
459           Puts breadth in pixels of INDEXth column ( VERTICAL = 0 ) or row (
460           VERTICAL = 1) into BREADTH scalar reference.
461
462           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
466       SelectCell COLUMN, ROW
467           Called when a cell with COLUMN and ROW coordinates is focused.
468
469       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
474       Stringify COLUMN, ROW, TEXT_REF
475           Puts text string, assigned to cell with COLUMN and ROW coordinates,
476           into TEXT_REF scalar reference.
477

Prima::AbstractGrid

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

Prima::GridViewer

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
488       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
493       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
498       "Prima::GridViewer" is derived from "Prima::AbstractGridViewer".
499
500   Properties
501       allowChangeCellHeight
502           Default value: 1
503
504       allowChangeCellWidth
505           Default value: 1
506
507       cell COLUMN, ROW, [ DATA ]
508           Run-time property. Selects the data in cell with COLUMN and ROW
509           coordinates.
510
511       cells [ ARRAY ]
512           The property accepts or returns all cells as a two-dimensional
513           rectangular array or scalars.
514
515       columns INDEX
516           A read-only property; returns number of columns.
517
518       rows INDEX
519           A read-only property; returns number of rows.
520
521   Methods
522       add_column CELLS
523           Inserts one-dimensional array of scalars to the end of columns.
524
525       add_columns CELLS
526           Inserts two-dimensional array of scalars to the end of columns.
527
528       add_row CELLS
529           Inserts one-dimensional array of scalars to the end of rows.
530
531       add_rows CELLS
532           Inserts two-dimensional array of scalars to the end of rows.
533
534       delete_columns OFFSET, LENGTH
535           Removes LENGTH columns starting from OFFSET. Negative values are
536           accepted.
537
538       delete_rows OFFSET, LENGTH
539           Removes LENGTH rows starting from OFFSET. Negative values are
540           accepted.
541
542       insert_column OFFSET, CELLS
543           Inserts one-dimensional array of scalars as column OFFSET.
544           Negative values are accepted.
545
546       insert_columns OFFSET, CELLS
547           Inserts two-dimensional array of scalars in column OFFSET.
548           Negative values are accepted.
549
550       insert_row
551           Inserts one-dimensional array of scalars as row OFFSET.  Negative
552           values are accepted.
553
554       insert_rows
555           Inserts two-dimensional array of scalars in row OFFSET.  Negative
556           values are accepted.
557

Prima::Grid

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
563   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
569       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

AUTHOR

575       Dmitry Karasik, <dmitry@karasik.eu.org>.
576

SEE ALSO

578       Prima, Prima::Widget, examples/grid.pl
579
580
581
582perl v5.36.0                      2023-03-20                   Prima::Grids(3)
Impressum