CwMatrix

Gamma/Photon: Using Gamma™ with the Photon microGUIŽ, Version 4.0
Prev |  | Next

# `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 varialbes, 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 `gamma_ph_`#`_examples_1_QNX4.tgz` file available on the Cogent Web Site.

    #!/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.
     */
    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.

Prev | Home | Next
`CwGraph` | Up | `PtArc`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.