.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::Grids 3"
.TH Prima::Grids 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::Grids \- grid widgets
.SS "\s-1SYNOPSIS\s0"
.IX Subsection "SYNOPSIS"
.Vb 1
\&        use Prima::Grids;
\&
\&        $grid = Prima::Grid\-> create(
\&                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\en";
\&                }
\&        );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module provides classes for several abstraction layers
of grid representation. The classes hierarchy is as follows:
.PP
.Vb 4
\&        AbstractGridViewer
\&                AbstractGrid
\&                GridViewer
\&                        Grid
.Ve
.PP
The root class, \f(CW\*(C`Prima::AbstractGridViewer\*(C'\fR, 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 \f(CW\*(C`Prima::Grid\*(C'\fR,
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 \f(CW\*(C`Prima::Grid\*(C'\fR, it is
usually enough to overload either the \f(CW\*(C`Stringify\*(C'\fR, \f(CW\*(C`Measure\*(C'\fR, 
and \f(CW\*(C`DrawCell\*(C'\fR events, or their method counterparts: \f(CW\*(C`get_cell_text\*(C'\fR,
\&\f(CW\*(C`columnWidth\*(C'\fR, \f(CW\*(C`rowHeight\*(C'\fR, and \f(CW\*(C`draw_items\*(C'\fR.
.PP
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.
.PP
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.
.PP
The widget allows the interactive changing of cell widths and heights by dragging
the grid lines between the cells.
.SH "Prima::AbstractGridViewer"
.IX Header "Prima::AbstractGridViewer"
\&\f(CW\*(C`Prima::AbstractGridViewer\*(C'\fR, 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.
.PP
\&\f(CW\*(C`Prima::AbstractGridViewer\*(C'\fR is a descendant of \f(CW\*(C`Prima::GroupScroller\*(C'\fR,
and some properties are not described here. See \*(L"Prima::GroupScroller\*(R" in Prima::IntUtils.
.SS "Properties"
.IX Subsection "Properties"
.IP "allowChangeCellHeight \s-1BOOLEAN\s0" 4
.IX Item "allowChangeCellHeight BOOLEAN"
If 1, the user is allowed to change vertical extents of cells by dragging the
horizontal grid lines. Prerequisites to the options are:
the lines must be set visible via \f(CW\*(C`drawHGrid\*(C'\fR property, \f(CW\*(C`constantCellHeight\*(C'\fR
property set to 0, and the changes to the vertical extents can be recorded
via \f(CW\*(C`SetExtent\*(C'\fR notification.
.Sp
Default value: 0
.IP "allowChangeCellWidth \s-1BOOLEAN\s0" 4
.IX Item "allowChangeCellWidth BOOLEAN"
If 1, the user is allowed to change horizontal extents of cells by dragging the
horizontal grid lines. Prerequisites to the options are:
the lines must be set visible via \f(CW\*(C`drawVGrid\*(C'\fR property, \f(CW\*(C`constantCellWidth\*(C'\fR
property set to 0, and the changes to the horizontal extents can be recorded
via \f(CW\*(C`SetExtent\*(C'\fR notification.
.Sp
Default value: 0
.IP "cellIndents X1, Y1, X2, Y2" 4
.IX Item "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 ),
cannot be selected and scrolled. X1 and X2 correspond to amount of indent columns,
and Y1 and Y2, \- to the indent rows.
.Sp
\&\f(CW\*(C`leftCell\*(C'\fR and \f(CW\*(C`topCell\*(C'\fR do not count the indent cells as the leftmost or topmost
visible cell; in other words, X1 and Y1 are minimal values for \f(CW\*(C`leftCell\*(C'\fR and \f(CW\*(C`topCell\*(C'\fR
properties.
.Sp
Default value: 0,0,0,0
.IP "clipCells \s-1INTEGER\s0" 4
.IX Item "clipCells INTEGER"
A three-state integer property, that governs the way clipping is applied 
when cells are drawn. Depending on kind of graphic in cells, the clipping 
may be necessary, or unnecessary.
.Sp
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.
.Sp
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, \f(CW\*(C`Prima::AbstractGrid\*(C'\fR and \f(CW\*(C`Prima::Grid\*(C'\fR, are safe with \f(CW\*(C`clipCells\*(C'\fR
set to 1.
.Sp
Default value: 1
.IP "columns \s-1INTEGER\s0" 4
.IX Item "columns INTEGER"
Sets number of columns, including the indent columns. The number of
columns must be larger than the number of indent columns.
.Sp
Default value: 0.
.IP "columnWidth \s-1COLUMN\s0 [ \s-1WIDTH\s0 ]" 4
.IX Item "columnWidth COLUMN [ WIDTH ]"
A run-time property, selects width of a column. To acquire or set 
the width, \f(CW\*(C`Measure\*(C'\fR and \f(CW\*(C`SetExtent\*(C'\fR notifications can be invoked.
Result of \f(CW\*(C`Measure\*(C'\fR may be cached internally using \f(CW\*(C`cache_geometry_requests\*(C'\fR
method.
.Sp
The width does not include widths of eventual vertical grid lines.
.Sp
If \f(CW\*(C`constantCellWidth\*(C'\fR is defined, the property is used as its alias.
.IP "constantCellHeight \s-1HEIGHT\s0" 4
.IX Item "constantCellHeight HEIGHT"
If defined, all rows have equal height, \s-1HEIGHT\s0 pixels. If \f(CW\*(C`undef\*(C'\fR,
rows have different heights.
.Sp
Default value: undef
.IP "constantCellWidth \s-1WIDTH\s0" 4
.IX Item "constantCellWidth WIDTH"
If defined, all rows have equal width, \s-1WIDTH\s0 pixels. If \f(CW\*(C`undef\*(C'\fR,
columns have different widths.
.Sp
Default value: undef
.IP "drawHGrid \s-1BOOLEAN\s0" 4
.IX Item "drawHGrid BOOLEAN"
If 1, horizontal grid lines between cells are drawn with \f(CW\*(C`gridColor\*(C'\fR.
.Sp
Default value: 1
.IP "drawVGrid" 4
.IX Item "drawVGrid"
If 1, vertical grid lines between cells are drawn with \f(CW\*(C`gridColor\*(C'\fR.
.Sp
Default value: 1
.IP "dx \s-1INTEGER\s0" 4
.IX Item "dx INTEGER"
A run-time property. Selects horizontal offset in pixels of grid layout
in pixel mode.
.IP "dy \s-1INTEGER\s0" 4
.IX Item "dy INTEGER"
A run-time property. Selects vertical offset in pixels of grid layout
in pixel mode.
.IP "focusedCell X, Y" 4
.IX Item "focusedCell X, Y"
Selects coordinates or the focused cell.
.IP "gridColor \s-1COLOR\s0" 4
.IX Item "gridColor COLOR"
Selects the color of grid lines.
.Sp
Default value: \f(CW\*(C`cl::Black\*(C'\fR .
.IP "gridGravity \s-1INTEGER\s0" 4
.IX Item "gridGravity INTEGER"
The property selects the breadth of area around the grid lines, that 
reacts on grid-dragging mouse events. The minimal value, 0, marks
only grid lines as the drag area, but makes the dragging 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.
.Sp
Default value: 3
.IP "indentCellBackColor \s-1COLOR\s0" 4
.IX Item "indentCellBackColor COLOR"
Selects the background color of indent cells.
.Sp
Default value: \f(CW\*(C`cl::Gray\*(C'\fR .
.IP "indentCellColor" 4
.IX Item "indentCellColor"
Selects the foreground color of indent cells.
.Sp
Default value: \f(CW\*(C`cl::Gray\*(C'\fR .
.IP "leftCell \s-1INTEGER\s0" 4
.IX Item "leftCell INTEGER"
Selects index of the leftmost visible normal cell.
.IP "multiSelect \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
Default value: 0
.IP "rows \s-1INTEGER\s0" 4
.IX Item "rows INTEGER"
Sets number of rows, including the indent rows. The number of
rows must be larger than the number of indent rows.
.Sp
Default value: 0.
.IP "topCell" 4
.IX Item "topCell"
Selects index of the topmost visible normal cell.
.IP "rowHeight \s-1INTEGER\s0" 4
.IX Item "rowHeight INTEGER"
A run-time property, selects height of a row. To acquire or set 
the height, \f(CW\*(C`Measure\*(C'\fR and \f(CW\*(C`SetExtent\*(C'\fR notifications can be invoked.
Result of \f(CW\*(C`Measure\*(C'\fR may be cached internally using \f(CW\*(C`cache_geometry_requests\*(C'\fR
method.
.Sp
The height does not include widths of eventual horizontal grid lines.
.Sp
If \f(CW\*(C`constantCellHeight\*(C'\fR is defined, the property is used as its alias.
.IP "selection X1, Y1, X2, Y2" 4
.IX Item "selection X1, Y1, X2, Y2"
If \f(CW\*(C`multiSelect\*(C'\fR 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 \f(CW\*(C`has_selection\*(C'\fR returns 0 .
.Sp
If \f(CW\*(C`multiSelect\*(C'\fR is 0, in get-mode returns the focused cell, and discards
the parameters in the set-mode.
.SS "Methods"
.IX Subsection "Methods"
.IP "cache_geometry_requests \s-1CACHE\s0" 4
.IX Item "cache_geometry_requests CACHE"
If \s-1CACHE\s0 is 1, starts caching results of \f(CW\*(C`Measure\*(C'\fR notification, thus lighting the
subsequent \f(CW\*(C`columnWidth\*(C'\fR and \f(CW\*(C`rowHeight\*(C'\fR calls; if \s-1CACHE\s0 is 0, flushes the cache.
.Sp
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.
.IP "deselect_all" 4
.IX Item "deselect_all"
Nullifies the selection, if \f(CW\*(C`multiSelect\*(C'\fR is 1.
.IP "draw_cells \s-1CANVAS\s0, \s-1COLUMNS\s0, \s-1ROWS\s0, \s-1AREA\s0" 4
.IX Item "draw_cells CANVAS, COLUMNS, ROWS, AREA"
A bulk draw routine, called from \f(CW\*(C`onPaint\*(C'\fR to draw cells.
\&\s-1AREA\s0 is an array of four integers with inclusive-inclusive
coordinates of the widget inferior without borders and scrollbars
( result of \f(CWget_active_area(2)\fR call; see \*(L"get_active_area\*(R" in Prima::IntUtils ).
.Sp
\&\s-1COLUMNS\s0 and \s-1ROWS\s0 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:
.Sp
.Vb 7
\&        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
.Ve
.Sp
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 \f(CW\*(C`{colsDraw}\*(C'\fR and
\&\f(CW\*(C`{rowsDraw}\*(C'\fR are passed as \s-1COLUMNS\s0 and \s-1ROWS\s0 parameters.
.Sp
In \f(CW\*(C`Prima::AbstractGrid\*(C'\fR and \f(CW\*(C`Prima::Grid\*(C'\fR classes <draw_cells> is overloaded to 
transfer the call to \f(CW\*(C`std_draw_text_cells\*(C'\fR, the text-oriented optimized routine.
.IP "draw_text_cells \s-1SCREEN_RECTANGLES\s0, \s-1CELL_RECTANGLES\s0, \s-1CELL_INDECES\s0, \s-1FONT_HEIGHT\s0" 4
.IX Item "draw_text_cells SCREEN_RECTANGLES, CELL_RECTANGLES, CELL_INDECES, FONT_HEIGHT"
A bulk routine for drawing text cells, called from \f(CW\*(C`std_draw_text_cells\*(C'\fR .
.Sp
\&\s-1SCREEN_RECTANGLES\s0 and \s-1CELL_RECTANGLES\s0 are arrays, where each item is a rectangle
with exterior of a cell. \s-1SCREEN_RECTANGLES\s0 contains rectangles that cover the
cell visible area; \s-1CELL_RECTANGLES\s0 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 \s-1SCREEN_RECTANGLES\s0, and [150,150,250,250] in \s-1CELL_RECTANGLES\s0.
.Sp
\&\s-1CELL_INDECES\s0 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.
.Sp
\&\s-1FONT_HEIGHT\s0 is a current font height value, cached since \f(CW\*(C`draw_text_cells\*(C'\fR is
often used for text operations and may require vertical text justification.
.IP "get_cell_area [ \s-1WIDTH\s0, \s-1HEIGHT\s0 ]" 4
.IX Item "get_cell_area [ WIDTH, HEIGHT ]"
Returns screen area in inclusive-inclusive pixel coordinates, that is used
to display normal cells. The extensions are related to the current size of a widget, 
however, can be overridden by specifying \s-1WIDTH\s0 and \s-1HEIGHT\s0.
.IP "get_cell_text \s-1COLUMN\s0, \s-1ROW\s0" 4
.IX Item "get_cell_text COLUMN, ROW"
Returns text string assigned to cell in \s-1COLUMN\s0 and \s-1ROW\s0.
Since the class does not assume the item storage organization,
the text is queried via \f(CW\*(C`Stringify\*(C'\fR notification.
.IP "get_range \s-1AXIS\s0, \s-1INDEX\s0" 4
.IX Item "get_range AXIS, INDEX"
Returns a pair of integers, minimal and maximal breadth of INDEXth column
or row in pixels. If \s-1AXIS\s0 is 1, the rows are queried; if 0, the columns.
.Sp
The method calls \f(CW\*(C`GetRange\*(C'\fR notification.
.IP "get_screen_cell_info \s-1COLUMN\s0, \s-1ROW\s0" 4
.IX Item "get_screen_cell_info COLUMN, ROW"
Returns information about a cell in \s-1COLUMN\s0 and \s-1ROW\s0, if it is currently visible.
The returned parameters are indexed by \f(CW\*(C`gsci::XXX\*(C'\fR constants,
and explained below:
.Sp
.Vb 3
\&        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 indices 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 indices 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.
.Ve
.Sp
If the cell is not visible, returns empty array.
.IP "has_selection" 4
.IX Item "has_selection"
Returns a boolean value, indicating whether the grid contains a selection (1) or not (0).
.IP "point2cell X, Y, [ \s-1OMIT_GRID\s0 = 0 ]" 4
.IX Item "point2cell X, Y, [ OMIT_GRID = 0 ]"
Return information about point X, Y in widget coordinates. The method
returns two integers, \s-1CX\s0 and \s-1CY\s0, with cell coordinates, and 
eventual \s-1HINTS\s0 hash, with more information about pixe localtion. If \s-1OMIT_GRID\s0 is set to 1
and the pixel belongs to a grid, the pixels is treated a part of adjacent cell.
The call syntax:
.Sp
.Vb 1
\&        ( $CX, $CY, %HINTS) = $self\->point2cell( $X, $Y);
.Ve
.Sp
If the pixel lies within cell boundaries by either coordinate, \s-1CX\s0 and/or \s-1CY\s0
are correspondingly set to cell column and/or row. When the pixel is outside
cell space, \s-1CX\s0 and/or \s-1CY\s0 are set to \-1.
.Sp
\&\s-1HINTS\s0 may contain the following values:
.RS 4
.ie n .IP """x"" and ""y""" 4
.el .IP "\f(CWx\fR and \f(CWy\fR" 4
.IX Item "x and y"
If 0, the coordinate lies within boundaries of a cell.
.Sp
If \-1, the coordinate is on the left/top to the cell body.
.Sp
If +1, the coordinate is on the right/bottom to the cell body, but within
the widget.
.Sp
If +2, the coordinate is on the right/bottom to the cell body, but outside
the widget.
.ie n .IP """x_type"" and ""y_type""" 4
.el .IP "\f(CWx_type\fR and \f(CWy_type\fR" 4
.IX Item "x_type and y_type"
Present when \f(CW\*(C`x\*(C'\fR or \f(CW\*(C`y\*(C'\fR values are 0.
.Sp
If 0, the cell is a normal cell.
.Sp
If \-1, the cell is left/top indent cell.
.Sp
If +1, the cell is right/bottom indent cell.
.ie n .IP """x_grid"" and ""y_grid""" 4
.el .IP "\f(CWx_grid\fR and \f(CWy_grid\fR" 4
.IX Item "x_grid and y_grid"
If 1, the point is over a grid line. This case can only happen when \s-1OMIT_GRID\s0 is 0.
If \f(CW\*(C`allowChangeCellHeight\*(C'\fR and/or \f(CW\*(C`allowChangeCellWidth\*(C'\fR are set, treats also
\&\f(CW\*(C`gridGravity\*(C'\fR\-broad pixels strips on both sides of the line as the grid area.
.Sp
Also values of \f(CW\*(C`x_left\*(C'\fR/\f(CW\*(C`x_right\*(C'\fR or \f(CW\*(C`y_bottom\*(C'\fR/\f(CW\*(C`y_top\*(C'\fR might be set.
.ie n .IP """x_left""/""x_right"" and ""y_bottom""/""y_top""" 4
.el .IP "\f(CWx_left\fR/\f(CWx_right\fR and \f(CWy_bottom\fR/\f(CWy_top\fR" 4
.IX Item "x_left/x_right and y_bottom/y_top"
Present together with \f(CW\*(C`x_grid\*(C'\fR or \f(CW\*(C`y_grid\*(C'\fR. Select indices of
cells adjacent to the grid line.
.ie n .IP """x_gap"" and ""y_gap""" 4
.el .IP "\f(CWx_gap\fR and \f(CWy_gap\fR" 4
.IX Item "x_gap and y_gap"
If 1, the point is within a gap between the last normal cell and the first 
right/bottom indent cell.
.ie n .IP """normal""" 4
.el .IP "\f(CWnormal\fR" 4
.IX Item "normal"
If 1, the point lies within the boundaries of a normal cell.
.ie n .IP """indent""" 4
.el .IP "\f(CWindent\fR" 4
.IX Item "indent"
If 1, the point lies within the boundaries of an indent cell.
.ie n .IP """grid""" 4
.el .IP "\f(CWgrid\fR" 4
.IX Item "grid"
If 1, the point is over a grid line.
.ie n .IP """exterior""" 4
.el .IP "\f(CWexterior\fR" 4
.IX Item "exterior"
If 1, the point is in inoperable area or outside the widget boundaries.
.RE
.RS 4
.RE
.IP "redraw_cell X, Y" 4
.IX Item "redraw_cell X, Y"
Repaints cell with coordinates X and Y.
.IP "reset" 4
.IX Item "reset"
Recalculates internal geometry variables.
.IP "select_all" 4
.IX Item "select_all"
Marks all cells as selected, if \f(CW\*(C`multiSelect\*(C'\fR is 1.
.IP "std_draw_text_cells \s-1CANVAS\s0, \s-1COLUMNS\s0, \s-1ROWS\s0, \s-1AREA\s0" 4
.IX Item "std_draw_text_cells CANVAS, COLUMNS, ROWS, AREA"
An optimized bulk routine for text-oriented grid widgets. The optimization
is achieved under assumption that each cell is drawn with two colors only,
so the color switching can be reduced.
.Sp
The routine itself paints the cells background, and calls \f(CW\*(C`draw_text_cells\*(C'\fR
to draw text and/or otherwise draw the cell content.
.Sp
For explanation of \s-1COLUMNS\s0, \s-1ROWS\s0, and \s-1AREA\s0 parameters see draw_cells .
.SS "Events"
.IX Subsection "Events"
.ie n .IP "DrawCell \s-1CANVAS\s0, \s-1COLUMN\s0, \s-1ROW\s0, \s-1INDENT\s0, @SCREEN_RECT, @CELL_RECT, \s-1SELECTED\s0, \s-1FOCUSED\s0" 4
.el .IP "DrawCell \s-1CANVAS\s0, \s-1COLUMN\s0, \s-1ROW\s0, \s-1INDENT\s0, \f(CW@SCREEN_RECT\fR, \f(CW@CELL_RECT\fR, \s-1SELECTED\s0, \s-1FOCUSED\s0" 4
.IX Item "DrawCell CANVAS, COLUMN, ROW, INDENT, @SCREEN_RECT, @CELL_RECT, SELECTED, FOCUSED"
Called when a cell with \s-1COLUMN\s0 and \s-1ROW\s0 coordinates is to be drawn on \s-1CANVAS\s0. 
\&\s-1SCREEN_RECT\s0 is a cell rectangle in widget coordinates,
where the item is to be drawn. \s-1CELL_RECT\s0 is same as \s-1SCREEN_RECT\s0, but calculated
as if the cell is fully visible.
.Sp
\&\s-1SELECTED\s0 and \s-1FOCUSED\s0 are boolean
flags, if the cell must be drawn correspondingly in selected and
focused states.
.IP "GetRange \s-1AXIS\s0, \s-1INDEX\s0, \s-1MIN\s0, \s-1MAX\s0" 4
.IX Item "GetRange AXIS, INDEX, MIN, MAX"
Puts minimal and maximal breadth of INDEXth column ( \s-1AXIS\s0 = 0 ) or row ( \s-1AXIS\s0 = 1)
in corresponding \s-1MIN\s0 and \s-1MAX\s0 scalar references.
.IP "Measure \s-1AXIS\s0, \s-1INDEX\s0, \s-1BREADTH\s0" 4
.IX Item "Measure AXIS, INDEX, BREADTH"
Puts breadth in pixels of INDEXth column ( \s-1AXIS\s0 = 0 ) or row ( \s-1AXIS\s0 = 1)
into \s-1BREADTH\s0 scalar reference.
.Sp
This notification by default may be called from within 
\&\f(CW\*(C`begin_paint_info/end_paint_info\*(C'\fR brackets. To disable this feature
set internal flag \f(CW\*(C`{NoBulkPaintInfo}\*(C'\fR to 1.
.IP "SelectCell \s-1COLUMN\s0, \s-1ROW\s0" 4
.IX Item "SelectCell COLUMN, ROW"
Called when a cell with \s-1COLUMN\s0 and \s-1ROW\s0 coordinates is focused.
.IP "SetExtent \s-1AXIS\s0, \s-1INDEX\s0, \s-1BREADTH\s0" 4
.IX Item "SetExtent AXIS, INDEX, BREADTH"
Reports breadth in pixels of INDEXth column ( \s-1AXIS\s0 = 0 ) or row ( \s-1AXIS\s0 = 1),
as a response to \f(CW\*(C`columnWidth\*(C'\fR and \f(CW\*(C`rowHeight\*(C'\fR calls.
.IP "Stringify \s-1COLUMN\s0, \s-1ROW\s0, \s-1TEXT_REF\s0" 4
.IX Item "Stringify COLUMN, ROW, TEXT_REF"
Puts text string, assigned to cell with \s-1COLUMN\s0 and \s-1ROW\s0 coordinates, into \s-1TEXT_REF\s0
scalar reference.
.SH "Prima::AbstractGrid"
.IX Header "Prima::AbstractGrid"
Exactly the same as its ascendant, \f(CW\*(C`Prima::AbstractGridViewer\*(C'\fR,
except that it does not propagate \f(CW\*(C`DrawItem\*(C'\fR message, 
assuming that the items must be drawn as text.
.SH "Prima::GridViewer"
.IX Header "Prima::GridViewer"
The class implements cells data and geometry storage mechanism, but leaves
the cell data format to the programmer. The cells are accessible via
\&\f(CW\*(C`cells\*(C'\fR property and several other helper routines.
.PP
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.
.PP
For example, \f(CW\*(C`[[1,2,3]]]\*(C'\fR is a valid one-row, three-column structure, and 
\&\f(CW\*(C`[[1,2],[2,3],[3,4]]\*(C'\fR is a valid three-row, two-column structure.
The structure \f(CW\*(C`[[1],[2,3],[3,4]]\*(C'\fR is invalid, since its first row has
one column, while the others have two.
.PP
\&\f(CW\*(C`Prima::GridViewer\*(C'\fR is derived from \f(CW\*(C`Prima::AbstractGridViewer\*(C'\fR.
.SS "Properties"
.IX Subsection "Properties"
.IP "allowChangeCellHeight" 4
.IX Item "allowChangeCellHeight"
Default value: 1
.IP "allowChangeCellWidth" 4
.IX Item "allowChangeCellWidth"
Default value: 1
.IP "cell \s-1COLUMN\s0, \s-1ROW\s0, [ \s-1DATA\s0 ]" 4
.IX Item "cell COLUMN, ROW, [ DATA ]"
Run-time property. Selects the data in cell with \s-1COLUMN\s0 and \s-1ROW\s0 coordinates.
.IP "cells [ \s-1ARRAY\s0 ]" 4
.IX Item "cells [ ARRAY ]"
The property accepts or returns all cells as a two-dimensional
rectangular array or scalars.
.IP "columns \s-1INDEX\s0" 4
.IX Item "columns INDEX"
A read-only property; returns number of columns.
.IP "rows \s-1INDEX\s0" 4
.IX Item "rows INDEX"
A read-only property; returns number of rows.
.SS "Methods"
.IX Subsection "Methods"
.IP "add_column \s-1CELLS\s0" 4
.IX Item "add_column CELLS"
Inserts one-dimensional array of scalars to the end of columns.
.IP "add_columns \s-1CELLS\s0" 4
.IX Item "add_columns CELLS"
Inserts two-dimensional array of scalars to the end of columns.
.IP "add_row \s-1CELLS\s0" 4
.IX Item "add_row CELLS"
Inserts one-dimensional array of scalars to the end of rows.
.IP "add_rows \s-1CELLS\s0" 4
.IX Item "add_rows CELLS"
Inserts two-dimensional array of scalars to the end of rows.
.IP "delete_columns \s-1OFFSET\s0, \s-1LENGTH\s0" 4
.IX Item "delete_columns OFFSET, LENGTH"
Removes \s-1LENGTH\s0 columns starting from \s-1OFFSET\s0. Negative values
are accepted.
.IP "delete_rows \s-1OFFSET\s0, \s-1LENGTH\s0" 4
.IX Item "delete_rows OFFSET, LENGTH"
Removes \s-1LENGTH\s0 rows starting from \s-1OFFSET\s0. Negative values
are accepted.
.IP "insert_column \s-1OFFSET\s0, \s-1CELLS\s0" 4
.IX Item "insert_column OFFSET, CELLS"
Inserts one-dimensional array of scalars as column \s-1OFFSET\s0.
Negative values are accepted.
.IP "insert_columns \s-1OFFSET\s0, \s-1CELLS\s0" 4
.IX Item "insert_columns OFFSET, CELLS"
Inserts two-dimensional array of scalars in column \s-1OFFSET\s0.
Negative values are accepted.
.IP "insert_row" 4
.IX Item "insert_row"
Inserts one-dimensional array of scalars as row \s-1OFFSET\s0.
Negative values are accepted.
.IP "insert_rows" 4
.IX Item "insert_rows"
Inserts two-dimensional array of scalars in row \s-1OFFSET\s0.
Negative values are accepted.
.SH "Prima::Grid"
.IX Header "Prima::Grid"
Descendant of \f(CW\*(C`Prima::GridViewer\*(C'\fR, declares format of cells 
as a single text string. Incorporating all functionality of
its ascendants, provides a standard text grid widget.
.SS "Methods"
.IX Subsection "Methods"
.IP "get_cell_text \s-1COLUMN\s0, \s-1ROW\s0" 4
.IX Item "get_cell_text COLUMN, ROW"
Returns text string assigned to cell in \s-1COLUMN\s0 and \s-1ROW\s0. 
Since the item storage organization is implemented, does
so without calling \f(CW\*(C`Stringify\*(C'\fR notification.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Widget, \fIexamples/grid.pl\fR