View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
kmx > IUP-0.006 > IUP::Matrix



Annotate this POD


New  2
Open  1
View/Report Bugs
Source   Latest Release: IUP-0.305


IUP::Matrix - [GUI element] matrix of alphanumeric fields


Creates a matrix of alphanumeric fields. Therefore, all values of the matrixs fields are strings. The matrix is not a grid container like many systems have.

It has two modes of operation: normal and callback mode. In normal mode, string values are stored in attributes for each cell. In callback mode these attributes are ignored and the cells are filled with strings returned by the "VALUE_CB" callback. So the existence of this callback defines the mode the matrix will operate.


CREATION - new() method

 $matrix = IUP::Matrix->new( NUMCOL=>5, NUMCOL_VISIBLE=>2, NUMLIN=>8, NUMLIN_VISIBLE=>3 );

Returns: the identifier of the created element, or undef if an error occurs.

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.


Before mapped to the native system, all attributes are stored in the hash table, independently from the size of the matrix or its operation mode. The action attributes like ADDLIN and DELCOL will NOT work.

When the matrix is mapped, and it is NOT in callback mode, then the cell values and mark state are moved from the hash table to an internal storage at the matrix. Other cell attributes remains on the hash table. Cell values with indices greater than (NUMLIN,NUMCOL) are ignored. When in callback mode cell values stored in the hash table are ignored.

Callback Mode

Very large matrices must use the callback mode to set the values, and not the regular value attributes of the cells. The idea is the following:

1. Register the VALUE_CB callback
2. No longer set the value of the cells. They will be set one by one by the callback. Note that the values of the cells must now be stored by the user.
3. If the matrix is editable, set the VALUE_EDIT_CB callback.
4. When the matrix must be invalidated, use the REDRAW attribute to force a matrix redraw.

A negative aspect is that, when VALUE_CB is defined, after it is mapped the matrix never verifies attributes of type L:C again.

If callback VALUE_CB is defined and VALUE_EDIT_CB is not defined when the matrix is mapped then READONLY will be set to YES.

Number of Cells

If you do not plan to use ADDLIN nor ADDCOL, and plan to set sparse cell values, then you must set NUMLIN and NUMCOL before mapping.


A matrix might have titles for lines and columns. Titles are always non scrollable, non editable and presented with a different default background color. A matrix will have a line of titles if an attribute of the "(L):0" type is defined, where L is a line number, or if the HEIGHT0 attribute is defined. It will have a column of titles if an attribute of the "0:(C)" type is defined, where C is a column number, or if the WIDTH0 attribute is defined.

When allowed the width of a column can be changed by holding and dragging its title right border, see RESIZEMATRIX.

Any cell can have more than one text line, just use the \n control character. Multiple text lines will be considered when calculating the title cell size based on its contents. The contents of ordinary cells (not a title) do not affect the cell size.

Natural Size

The Natural size is calculated using only the title cells size plus the size of NUMCOL_VISIBLE and NUMLIN_VISIBLE cells, but it is also affected if SCROLBAR is enabled. The natural height is the sum of the line heights from line 0 to NUMLIN_VISIBLE (inclusive). The natural width is the sum of the column width from column 0 to NUMCOL_VISIBLE (inclusive). Notice that since NUMCOL_VISIBLE and NUMLIN_VISIBLE do not include the titles then NUMCOL_VISIBLE+1 columns and NUMLIN_VISIBLE+1 lines are included in the sum.

The height of a line L depends on several attributes, first it checks the HEIGHTL attribute, then checks RASTERHEIGHTL, then when USETITLESIZE=YES or not in callback mode the height of the title text for the line or if L=0 it searches for the highest column title, if still could not define a height then if L!=0 it will use HEIGHTDEF, if L=0 then height will be 0.

A similar approach is valid for the column width. The width of a column C first checks the WIDTHC attribute, then checks RASTERWIDTHC, then when USETITLESIZE=YES or not in callback mode the width of the title text for the column or if C=0 it searches for the widest line title, if still could not define a width then if C!=0 it will use WIDTHDEF, if C=0 then height will be 0.

Virtual Size

When the scrollbars are enabled if the matrix area is greater than the visible area then scrollbars will be displayed so the cells can be scrolled to be visible area. When dragging the scrollbar the position of cells is free, when clicking on its buttons it will move in cell steps, aligning to the left border of the cell.

By default EXPAND=Yes, so matrix will be automatically resized when the dialog is resized. So more columns and lines will be displayed. But the matrix Natural size will be used as minimum size. To remove the minimum size limitation set NUMCOL_VISIBLE and NUMLIN_VISIBLE to 0 after showing it for the first time.

Keyboard Navigation

Keyboard navigation through the matrix cells outside the edition mode is done by using the following keys:

When the matrix is outside the edition mode, pressing any character key makes the current key to enter in the edition mode, the old text is replaced by the new one being typed. If F2, Enter or Space is pressed, the current cell enters the edition mode with the current text of the cell. Double-clicking a cell also enters the edition mode (in Motif the user must click again to the edit control get the focus).

When using the keyboard to change the focus cell if the limit of the visible area is reached then the cells are automatically scrolled. Also if a cell partially visible is edited then first it is scrolled to the visible area.

Inside the edition mode, the following keys are used for a text field:

The cell will also leave the edition mode if the user clicked in another cell or in another control, then the value will be confirmed. When pressing Enter to confirm the value the focus goes to the cell below the current cell, if at the last line then the focus goes to the cell on the left. The value confirmation depends on the EDITION_CB callback return code.


When a mark mode is set the cells can be marked using mouse.

A marked cell will have its background attenuated to indicate that it is marked. A title cell appears marked only when MARKMODE=LIN, COL or LINCOL.

Cells can be selected individually or can be restricted to lines or columns. Also multiple cells can be marked simultaneously in continuous or in segmented areas. Lines and columns are marked only when the user clicks in their respective titles, if MARKMODE=CELL then all the cells of the line or column will be marked. Continuous areas are marked holding and dragging the mouse or holding the Shift key when clicking at the end of the area. Segmented areas are marked or unmarked holding the Ctrl key, the mark state is inverted. Clicking on the cell 0:0 will select all the items depending on MARKMODE, except for LINCOL.


For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:

General Attributes


Default cursor used by the matrix. The default cursor is a symbol that looks like a cross. If you need to refer to this default cursor, use the name "IUP::MatrixCrossCursor".


When set to YES, programmatically puts the current cell in edition mode, allowing the user to modify its value. When consulted informs if the the current cell is being edited. Possible values: "YES" or "NO".


controls how the next cell after editing is chosen. Can be LIN, COL, LINCR, COLCR. Default: LIN. (since 3.4)

 LIN - go to the next line, if at last line then go to the next column at the same line;
 LINCR - go to the next line, if at last line then go to the next column at the first line;
 COL - go to the next column, if at last column then go to the next line at the same column;
 COLCR - go to the next column, if at last column then go to the next line at the first column;

Defines the current cell. Two numbers in the "(L):(C)" format, ((L) > 0 and (C) > 0, a title cell can NOT be the current cell). Default: "1:1".


do not show the focus mark when drawing the matrix. Default is NO.


when text is greater than cell space, it is normally cropped, but when set to YES a "..." mark will be added at the crop point to indicate that there is more text not visible. Default: NO. (since 3.1)


limit expansion to the maximum size that shows all cells. (since 3.5)


Scroll the visible area to the given cell. Returns the cell at the upper left corner. To scroll to a line or a column, use a value such as "(L):*" or "*:(C)" (where L > 0 and (C) > 0). L and C can not be a non scrollable cell either.


complements the ORIGIN attribute by specifying the drag offset of the top left cell. Returns the current value. Has the format "XxY" or "%dx%d" in C. Used only the ORIGIN is set. (since 3.5)


disables the editing of all cells. EDITION_CB and VALUE_EDIT_CB will not be called anymore. The L:C attribute will still be able to change the cell value.


Defines if the width of a column can be interactively changed. When this is possible, the user can change the size of a column by dragging the column title right border. Possible values: "YES" or "NO". Default: "NO" (does not allow interactive width change).


Use the title size to define the cell size if necessary. See WIDTHn and HEIGHTn. Default: NO.

The following common attributes are also accepted:

Cell Attributes (no redraw)

These attributes are only updated in the display when you set the REDRAW attribute.

Column Attributes (no redraw)

Column Size Attributes

For all columns if WIDTHn is not defined, then RASTERWIDTHn is used. If also not defined, then depending on the circumstances a logic is used to find the column width.

If it is the title column (n=0), then if USETITLESIZE=YES or not in callback mode, it will search for the maximum width among the titles of all lines. Finally if the conditions are not true or the maximum width of the column is 0, then the column of line titles is hidden.

If it is a regular column (n > 0), then if USETITLESIZE=YES, then it will use the width of the title of the column. Finally if the condition is not true or the width of the title of the column is 0, then the default value WIDTHDEF is used.

Line Size Attributes

For all lines if HEIGHTn is not defined, then RASTERHEIGHTn is used. If also not defined, then depending on the circumstances a logic is used to find the line height.

If it is the title line (n=0), then if USETITLESIZE=YES or not in callback mode, it will search for the maximum height among the titles of all columns. Finally if the conditions are not true or the maximum height of the line is 0, then the line of column titles is hidden.

If it is a regular line (n > 0), then if USETITLESIZE=YES, then it will use the height of the title of the line. Finally if the condition is not true or the height of the title of the line is 0, then the default value HEIGHTDEF is used.

Number of Cells Attributes

Mark Attributes

Action Attributes

Text Editing Attributes

Canvas Attributes (inheritable)


For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:

Interaction Callbacks

Drawing Callbacks

Editing Callback

Callback Mode

The following canvas callbacks are also supported on IUP::Matrix

Utility Functions

These functions can be used to help set and get attributes from the matrix.


 # setting attribute value
 $matrix->MatAttribute($name, $lin, $col, $value);
 # getting attribute value
 $value = $matrix->MatAttribute($name, $lin, $col);

They work just like the respective traditional set and get functions. But the attribute string is complemented with the L and C values.

For example:

 $matrix->MatAttribute("BGCOLOR", 30, 10, $value) ~~ $matrix->SetAttribute("BGCOLOR30:10", $value)
 $matrix->MatAttribute("ALIGNMENT", 10, $value) ~~ $matrix->SetAttribute("ALIGNMENT10", $value)
 $v = $matrix->GetAttribute("BGCOLOR30:10") ~~ $v = $matrix->MatAttribute("BGCOLOR", 30, 10)

But these functions are faster than the traditional functions because they do not need to parse the attribute name string and the application does not need to concatenate the attribute name with the id.


 # setting value
 MatCell($lin, $col, $value);
 # getting value
 $value = MatCell($lin, $col);

It is equivalent to the traditional set and get functions:

  $matrix->MatCell(30, 10, $value) ~~ $matrix->SetAttribute("30:10", $value)
  $v = $matrix->MatCell(30, 10) ~~ $v = $matrix->GetAttribute("30:10")


The element IUP::Matrix is used in the following sample scripts:



The original doc: iupmatrix.html

syntax highlighting: