Gamma/Photon : Using Gamma™ with the Photon microGUI®, Version 1.1
	Widget Classes

`CwMatrix`

CwMatrix — A Cogent matrix widget.

Synopsis

class CwMatrix PtContainer
{
    matrix_cols;       // short
    matrix_flags;      // flag 
    matrix_offset;     // PhPoint
    matrix_range;      // PhRect 
    matrix_rows;       // short
    matrix_visible;    // PhRect
}

Base Classes

PtWidget <-- PtBasic <-- PtContainer <-- CwMatrix

Description

This widget is the basis for building spreadsheets. It consists of a group of cells arranged in rows and columns that allow for entering numbers or text. Ranges of cells can be specified, modified, and moved. Cell display can be modified, and cell contents can be edited.

This widget does not appear in the Photon documentation.

Instance Variables

matrix_cols: An integer specifying the number of columns in the matrix.
matrix_flags: For internal use only.
matrix_offset: For internal use only. A PhPoint specifying the row/column offset of the upper left matrix cell.
matrix_range: Read only. A PhRect indicating the currently selected range.
matrix_rows: An integer indicating the number of rows in the matrix.
matrix_visible: Read only. An integer indicating the range of visible cells. Current implementation specifies that this will be the whole range.

Callbacks

The following callbacks are associated with this widget. For information on the callback class instance variables, please refer to CwMatrixCallback.

Callback	Description
`Cw_CB_MATRIX_BEGIN_EDIT`	This callback is generated when the user has begun to edit the contents of a cell. The program may choose to modify the text_string in order to have the user edit something other than the current cell contents. The relevant callback class instance variables are cur_range, prev_string, text_string and cell.
`Cw_CB_MATRIX_CELL_CHANGE`	This callback is generated when the user or program has changed something about a cell. The relevant callback class instance variables are cur_range and cell. cur_range simply contains the coordinates of the cell.
`Cw_CB_MATRIX_CHARINPUT`	This callback is generated when the user has typed a character of input. The relevant callback class instance variables are prev_range, cur_range, prev_string, text_string and cell. The cbinfo.reason_subtype can be Cw_MATRIX_INPUT_BEGIN_EDIT, Cw_MATRIX_INPUT_EDIT, or Cw_MATRIX_INPUT_SELECT.
`Cw_CB_MATRIX_KEYPRESS`	This callback is generated when the user has pressed a key while not editing a cell. This callback will only be invoked if the key is not a printable character. When the user presses a printable character, editing is automatically started in the currently selected cell. Relevant callback structure elements are cur_range and cell. The key press information can be found in the callback function through the function global variable "event_data" as event_data.key_event.
`Cw_CB_MATRIX_RANGE_CONVERT`	This callback is generated when the CwMatrix widget requires a printable representation for a range. The range is stored in the callback structure cur_range element, and the suggested printable representation is stored in text_string. The programmer can set text_string to an alternate representation in this callback. Relevant callback class instance variables are cur_range and text_string.
`Cw_CB_MATRIX_RANGE_MOVE`	This callback is generated when the currently selected range is moved through a dragging operation. The callback is performed only when the user releases the mouse button at the end of the move operation. Relevant callback class instance variables are prev_range and cur_range.
`Cw_CB_MATRIX_RANGE_SEL`	This callback is generated when a new range has been selected by the user dragging the mouse. The relevant callback class instance variables are prev_range and cur_range. The cbinfo.reason_subtype can be Cw_MATRIX_RANGE_START, Cw_MATRIX_RANGE_MODIFY or Cw_MATRIX_RANGE_FINAL.
`Cw_CB_MATRIX_SIZE_CHANGE`	This callback is generated when a row or column is resized. The row and column are stored in cur_range.ul.y and cur_range.ul.x respectively in the callback structure. The width or height of the relevant row or column is stored in the dim element of the callback structure. If a row is resized, the column and width will be reported as -1, and if a column is resized, the row and height will be reported as -1.
`Cw_CB_MATRIX_TEXT_CHANGE`	This callback is generated when the user has changed the text in a cell. The relevant callback class instance variables are prev_range, cur_range, prev_string, cur_string and cell.

Associated Classes

CwMatrixCallback, CwMatrixCell, PtCallbackInfo

Methods

Arguments

`area`	A `PhArea`, which you can create with a call to: `new (PhArea)`.
`col`	The column number, as an integer.
`flags`	One or more `CwMatrixCell`.`flags`, depending on the method (see below).
`flush`	An integer. Any non-zero value immediately updates the screen.
`height`	The height of a cell, in pixels.
`inverted`	0 or 1.
`mask`	One or more `CwMatrixCell`.`flags`, depending on the method (see below).
`range`	A `PhRect`.
`row`	The row number, as an integer.
`width`	The width of a cell, in pixels.

Methods

matrix.Cell (row, col) -- returns the cell at the position (row, col). If there is no cell currently at that position, one is created and returned. If the (row,col) coordinates are beyond the size of the matrix, returns nil.

matrix.ColumnWidth (col) -- returns the width of col, the specified column, in pixels.

matrix.DamageCell (row, col) -- damages the cell at (row,col). The screen is not updated until you call FlushDamage.

matrix.Edit (row, col) -- allows for editing the cell at (row, col).

matrix.ExistingCell (row, col) -- returns the cell at the position (row, col). If there is no cell currently at that position, it returns nil. If the (row, col) coordinates are beyond the size of the matrix, return nil.

matrix.Flush () -- is a synonym for matrix.FlushDamage.

matrix.FlushDamage () -- causes all damage to be updated on the screen. Many functions delay updating screen damage for efficiency reasons.

matrix.GetCellArea (row, col, area) -- fills in the elements of the area. This gives the pixel position and area of the cell at (row,col). The area is relative to the CwMatrix widget. The method returns -1 if the cell is completely off-screen, otherwise 0.

matrix.GetCellExtent (row, col, area) -- fills in the elements of the provided PhArea. This gives the pixel position and area of the cell at (row,col). The area is relative to the parent of the CwMatrix widget. The method returns -1 if the cell is completely off-screen, otherwise 0.

matrix.InvertRange (range, inverted) -- inverts or un-inverts the given range.

matrix.JustifyRange (range, flags) -- sets the text justification on all cells in the range. The flags parameter can be one of: Cw_CELL_LEFT, Cw_CELL_RIGHT or Cw_CELL_CENTER.

matrix.MaskRange (range, flags, mask) -- generally sets or un-sets flags on a range. The flags and mask parameters can be any combination of Cw_CELL_* flags.

matrix.OutlineRange (range, flags, mask) -- draws a border around the selected range. This is not the same as MaskRange, as it draws the border only on the outside edge of the entire range, whereas MaskRange will apply the flags and mask to every cell in the range. The flags and mask parameters can be any combination of Cw_CELL_* flags.

matrix.Redraw () -- redraws the entire widget.

matrix.RowHeight (row) -- returns the height of the specified row, in pixels.

matrix.SetColumnWidth (col, width, flush) -- sets the width in pixels for col, the specified column. If flush is non-zero, it causes the screen to be updated immediately.

matrix.SetRowHeight (row, height, flush) -- sets the height in pixels for the specified row. If flush is non-zero, it causes the screen to be updated immediately.

Example

This example, ex_CwMatrix.g, is included in the product distribution.

#!/usr/cogent/bin/phgamma

/*
 * This example illustrates CwMatrix and CwMatrixCell.
 */

/* Load the required files, which include two dynamic
 * libraries that are not generally needed for Photon
 * widgets.
 */
if (_os_ == "QNX4")
{
  dyna_add_lib("/usr/cogent/lib/photon_s.dlb");
  dyna_add_lib("/usr/cogent/lib/phwidgets.dlb");
}
require_lisp("PhotonWidgets.lsp");
PtInit(nil);

/* Create the Matrix.
 */
win = new(PtWindow);
win.SetArea(340,10,200,100);
mtx = new(CwMatrix);
mtx.SetArea(25,20,150,70);
mtx.matrix_cols = 3;
mtx.matrix_rows = 3;

/* Demonstrate some methods.
 */
w = mtx.ColumnWidth(0);
h = mtx.RowHeight(2);
cellarea = new(PhArea);
mtx.GetCellArea(2,2,cellarea);
princ("The width of the first column is ",w,".\n");
princ("The height of the bottom row is ",h,".\n\n");
pretty_princ("The bottom-right cell area is: \n",
	     cellarea,"\n\n");

/* Specify a range, and invert its colors.
 */
ul = new(PhPoint);
lr = new(PhPoint);
ul.x = 0;
ul.y = 0;
lr.x = 2;
lr.y = 0;
range = new(PhRect);
range.ul = ul;
range.lr = lr;
pretty_princ("The inverted range is:\n",range,"\n\n");
mtx.InvertRange(range,1);

/* Demonstrate a CwMatrixCell.
 */
cell = mtx.Cell(1,1);
cell.text_string = "Test";
cell.text_color = 0x0000ff;
cell.fill_color = 0xffffaa;
pretty_princ("The center cell definition is: \n",cell,"\n\n");

/* Demonstrate some callbacks.
 */
PtAttachCallback(mtx,Cw_CB_MATRIX_RANGE_MOVE,
                 #princ("Range has moved.\n"));
PtAttachCallback(mtx,Cw_CB_MATRIX_TEXT_CHANGE,
                 #princ("Text has changed.\n"));

PtRealizeWidget(win);
PtMainLoop();

Also see A CwMatrix Spreadsheet in the Sample Code and Cool Stuff chapter of the Programmer's Manual for a more sophisticated example.


CwGraph		PtArc