Prima::Grids(3)

💖 NAME 💖

You're in Prima::Grids(3), the User Contributed Perl Documentation page. The NAME is Prima::Grids — grid widgets 🎀✨

✨ SYNOPSIS ✨

use Prima qw(Grids Application);

my $grid = Prima::Grid-> new(
        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";
        }
);
run Prima;

🦋 DESCRIPTION 🦋

Okay bestie, this module is giving you classes for several abstraction layers for the representation of grid widgets. The class hierarchy is literally this:

AbstractGridViewer
        AbstractGrid
        GridViewer
                Grid

The root class, Prima::AbstractGridViewer, provides a common interface, but by itself it is not directly usable — it's the vibe-setter, not the whole fit. The main difference between the classes is in 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 their 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. iykyk 💅

The grid widget is designed to contain cells of variable extents, of two types: normal and indent. The indent rows and columns are displayed near to the widget borders, and their cells are drawn with distinguished colors. An example usage 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 at 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. slay 🫶

🌸 Prima::AbstractGridViewer 🌸

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

Prima::AbstractGridViewer is a descendant of Prima::Widget::GroupScroller, and some of its properties are not described here.

🎀 Properties 🎀

• allowChangeCellHeight BOOLEAN — if 1, the user is allowed to change the vertical extents of cells by dragging the horizontal grid lines. The prerequisites are: the lines must be set visible via the drawHGrid property, the constantCellHeight property set to 0, and the changes to the vertical extents can be recorded via the SetExtent notification. Default value: 0.
• allowChangeCellWidth BOOLEAN — if 1, the user is allowed to change the horizontal extents of cells by dragging the horizontal grid lines. The prerequisites are: the lines must be set visible via the drawVGrid property, the constantCellWidth property set to 0, and the changes to the horizontal extents can be recorded via the 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), and cannot be selected and scrolled. X1 and X2 correspond to the number of the indent columns, and Y1 and Y2 to the number of the indent rows. leftCell and topCell do not count the indent cells as the leftmost or topmost visible cells; 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 manages the way clipping is applied when cells are drawn. Depending on the 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 proceeds column-wise.
  • If the value is 2, the clipping is 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.

The 2 setting reduces drawing speed significantly, so don't say I didn't warn you 💀

• columns INTEGER — sets the 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 the width of a column. To acquire or set the width, Measure and SetExtent notifications can be invoked. The result of Measure may be cached internally using the cache_geometry_requests method. The width does not include the 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 the grid lines. Default value: cl::Black.
• gridGravity INTEGER — the property selects the breadth of the area around the grid lines that react to the grid-dragging mouse events. The minimal value of 0, marks only grid lines themselves as the dragging areas but makes the 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 the indent cells. Default value: cl::Gray.
• indentCellColor — selects the foreground color of the indent cells. Default value: cl::Gray.
• leftCell INTEGER — selects the 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 the number of rows, including the indent rows. The number of rows must be larger than the number of the indent rows. Default value: 0.
• topCell — selects the index of the topmost visible normal cell.
• rowHeight INTEGER — a run-time property, selects the height of a row. To acquire or set the height, Measure and SetExtent notifications can be invoked. The result of Measure may be cached internally using the cache_geometry_requests method. The height does not include the heights 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, manages the extent of a rectangular area that contains selected cells. If no such area is present, the selection is (-1,-1,-1,-1), and has_selection returns 0. If multiSelect is 0, in get-mode returns the focused cell, and ignores the parameters in the set-mode.

🧚 Methods 🧚

• cache_geometry_requests CACHE — if CACHE is 1, starts caching results of the Measure notification, thus making the subsequent columnWidth and rowHeight calls lighter. If CACHE is 0, flushes the cache.

If a significant geometry change happens during the caching, the cache is not updated automatically, so it is the caller's responsibility to flush the cache. no cap ✨

• deselect_all — removes the selection if multiSelect is 1.
• draw_cells CANVAS, COLUMNS, ROWS, AREA — a bulk draw routine, called from onPaint to draw individual cells. AREA is an array of four integers in inclusive-inclusive coordinates of the widget inferior without borders and scrollbars (the result of get_active_area(2) call; see get_active_area in Prima::Widget::IntIndents).

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 the inclusive-inclusive coordinate system and do not include eventual grid space, nor gaps between the indent and normal cells. By default, internal arrays {colsDraw} and {rowsDraw} are passed as COLUMNS and ROWS parameters.

In the 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, is called from std_draw_text_cells.
• SCREEN_RECTANGLES and CELL_RECTANGLES — two arrays where every item is a rectangle with an exterior of a cell 🎀 SCREEN_RECTANGLES holds rectangles covering the visible area of the cell, while CELL_RECTANGLES holds rectangles spanning the whole cell extent, ignoring whether it's only partially visible.

Like, say a 100-pixel cell has only its left half showing — then the corresponding array in SCREEN_RECTANGLES is [150,150,200,250], and the one in CELL_RECTANGLES is [150,150,250,250]. See how the second one keeps the full extent? No cap, that's the whole point 💅

• CELL_INDECES — arrays of cell coordinates. Each array item is itself an array of integer pairs, where item 0 is the column and item 1 is the row of the cell.
• FONT_HEIGHT — the current font height value, since draw_text_cells is mostly used for text operations and may require vertical text justification ✨

🛠 Methods

get_cell_area [ WIDTH, HEIGHT ]

Returns the screen area in inclusive-inclusive pixel coordinates. This is the area used to display normal cells. The extensions relate to the current size of a widget, but you can override them by passing 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 how you organize your item storage, these values are queried through the GetAlignment notification 💖

get_cell_text COLUMN, ROW

Returns the text string assigned to the cell at COLUMN and ROW. Again — the class doesn't assume your storage organization, so the text gets queried via the Stringify notification 🌸

get_range VERTICAL, INDEX

Returns a pair of integers: the minimal and maximal breadth of the INDEXth column or row, in pixels. If VERTICAL is 1, the rows are queried; if 0, the columns. This one calls the GetRange notification 🦋

get_screen_cell_info COLUMN, ROW

Returns info about the cell at COLUMN and ROW if it's currently visible. The returned parameters are indexed by the gsci::XXX constants:

• gsci::COL_INDEX — visual column number where the cell is displayed
• gsci::ROW_INDEX — visual row number where the cell is displayed
• gsci::V_FULL — cell is fully visible
• gsci::V_LEFT, gsci::V_BOTTOM, gsci::V_RIGHT, gsci::V_TOP — an inclusive-inclusive rectangle of the visible part of the cell. These four indices are grouped under the list constant gsci::V_RECT.
• gsci::LEFT, gsci::BOTTOM, gsci::RIGHT, gsci::TOP — an inclusive-inclusive rectangle of the cell as if it is fully visible. These four are grouped under the list constant gsci::RECT. If gsci::V_FULL is 1, these values are identical to the ones in gsci::V_RECT 👑

If the cell is not visible, you get an empty array back. That's it, that's the vibe check.

has_selection

Returns a boolean value: 1 if the grid contains a selection, 0 if not.

point2cell X, Y, [ OMIT_GRID = 0 ]

Returns info about the point X, Y in widget coordinates. You get two integers CX and CY with cell coordinates, plus an eventual HINTS hash carrying more info about the pixel location. If OMIT_GRID is set to 1 but the pixel belongs to the grid, the pixels are treated as part of an adjacent cell. The call syntax:

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

If the pixel lies within the cell boundaries by either coordinate, CX and/or CY are correspondingly set to that cell column and/or row. When the pixel is outside the 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 the boundaries of a cell.
  • If -1, the coordinate is on the left/top of the cell body.
  • If +1, the coordinate is on the right/bottom of the cell body, but within the widget.
  • If +2, the coordinate is on the right/bottom of 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 a left or a top indent cell.
  • If +1, the cell is a right or a bottom indent cell.
• "x_grid" and "y_grid" — if 1, the point is at a grid line. This case can only happen when OMIT_GRID is 0. If allowChangeCellHeight and/or allowChangeCellWidth are set, it also treats gridGravity-broad pixel strips on both sides of the line as the grid 🌈

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". Contain the indices of the cells adjacent to the grid line 💜
• "x_gap" and "y_gap" — if 1, the point is inside 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 at a grid line.
• "exterior" — if 1, the point is in an inoperable area or outside the widget boundaries.

redraw_cell X, Y

Repaints the cell with coordinates X and Y 🎨

reset

Recalculates internal geometry variables. That's literally the whole thing, bestie.

select_all

Marks all cells as selected — but only if multiSelect is 1. Otherwise? Nothing. Crickets 🦗

std_draw_text_cells CANVAS, COLUMNS, ROWS, AREA

An optimized bulk routine for text-oriented grid widgets 🔥 The optimization is achieved under the 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 then calls draw_text_cells to draw the cells' content.

For the full explanation of the 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 the same as SCREEN_RECT but calculated as if the cell were fully visible.

SELECTED, FOCUSED, and PRELIGHT are boolean flags — whether the cell must be drawn in selected, focused, and pre-lighted states, correspondingly ✨

GetAlignment COLUMN, ROW, HORIZONTAL_ALIGN_REF, VERTICAL_ALIGN_REF

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

GetRange VERTICAL, INDEX, MIN, MAX

Stores the minimal and maximal breadth of the INDEXth column (VERTICAL = 0) or row (VERTICAL = 1) into the corresponding MIN and MAX scalar references.

Measure VERTICAL, INDEX, BREADTH

Stores the breadth in pixels of the INDEXth column (VERTICAL = 0) or row (VERTICAL = 1) into the BREADTH scalar reference.

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

SelectCell COLUMN, ROW

Called when a cell with COLUMN and ROW coordinates is focused 👑

SetExtent VERTICAL, INDEX, BREADTH

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

Stringify COLUMN, ROW, TEXT_REF

Stores the text string, assigned to the cell with COLUMN and ROW coordinates, into the TEXT_REF scalar reference 🌸

---

🧚 Prima::AbstractGrid

Literally the same as its ascendant, Prima::AbstractGridViewer, except that it does not propagate the DrawItem message — it just assumes the items must be drawn as text 💖

👑 Prima::GridViewer

This class implements the cell data and geometry storage mechanisms, but leaves the data format up to you, the programmer. The cells are accessible via the cells property and several other helper routines 🫶

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

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. Not me warning you about that one 😭

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 the 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 the number of columns.
• rows INDEX — a read-only property; returns the number of rows.

💅 Methods

• add_column CELLS — inserts a one-dimensional array of scalars to the end of columns.
• add_columns CELLS — inserts a two-dimensional array of scalars to the end of columns.
• add_row CELLS — inserts a one-dimensional array of scalars to the end of rows.
• add_rows CELLS — inserts a 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 a one-dimensional array of scalars as column OFFSET. Negative values are accepted.
• insert_columns OFFSET, CELLS — inserts a two-dimensional array of scalars in column OFFSET. Negative values are accepted.
• insert_row — inserts a one-dimensional array of scalars as row OFFSET. Negative values are accepted.
• insert_rows — inserts a two-dimensional array of scalars in row OFFSET. Negative values are accepted.

👑 Prima::Grid 👑

It's a descendant of Prima::GridViewer, and it declares the format of cell data as a single text string. Basically it gives you the standard text grid widget with all the functionality of its ancestors. Iconic behavior, no notes. ✨

💅 Methods 💅

get_cell_alignment COLUMN, ROW

Returns two ta:: constants for horizontal and vertical cell text alignment. Since the item storage organization is implemented, it does this without calling the GetAlignment notification. Slay. 💖

get_cell_text COLUMN, ROW

Returns the text string assigned to the cell in COLUMN and ROW. Since the item storage organization is implemented, it does this without calling the Stringify notification. Periodt. 🎀

---

🌸 AUTHOR 🌸

Dmitry Karasik, <dmitry@karasik.eu.org>. 💌

🦋 SEE ALSO 🦋

• Prima
• Prima::Widget
• examples/grid.pl

---

okay bestie, that's the whole vibe 💅✨ — this page is from perl v5.42.0, dated 2024-08-20, and it's serving Prima::Grids(3) realness. 🫶