NAME

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

DESCRIPTION

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.

USAGE

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.

Storage

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.

Titles

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 through the matrix cells outside the edition mode is done by using the following keys:

Arrows: Moves the focus to the next cell, according to the arrows direction.
Page Up and Page Down: Moves a visible page up or down.
Home: Moves the focus to the fist column in the line.
Home Home: Moves the focus to the upper left corner of the visible page.
Home Home Home: Moves the focus to the upper left corner of the first page of the matrix.
End: Moves the focus to the last column in the line.
End End: Moves the focus to the lower right corner of the visible page.
End End End: Moves the focus to the lower right corner of the last page in the matrix.
F2, Enter or Space: enters editing mode.
Del: remove the selected cells contents.

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:

Left, Right, Up and Down arrows: if the caret is at the extremes of the text being edited then leave the edition mode and moves the focus accordingly. The value is confirmed.
Ctrl + arrows: leave the edition mode and moves the focus accordingly independent of caret position. The value is confirmed.
Enter: leave the edition mode. The value is confirmed. Moves the focus to the cell below.
Esc: leave the edition mode. The new value is ignored and the old value remains.

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.

Marks

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.

ATTRIBUTES

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

General Attributes

CURSOR

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".

EDIT_MODE

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".

EDITNEXT

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;

FOCUS_CELL

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".

HIDEFOCUS

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

HIDDENTEXTMARKS

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)

LIMITEXPAND

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

ORIGIN

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.

ORIGINOFFSET

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)

READONLY

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.

RESIZEMATRIX

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).

USETITLESIZE

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

The following common attributes are also accepted:

ACTIVE, EXPAND, FONT, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE

Cell Attributes (no redraw)

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

(L):(C)

Text of the cell located in line L and column C, where L and C are integer numbers. Example $m->GetAttribute("12:15")

(L):0

Title of line L. Example $m->GetAttribute("12:0")

0:(C)

Title of column C. Example $m->GetAttribute("0:15")

0:0

Title of the area between the line and column titles.

These are valid only in normal mode.

BGCOLOR

Background color of the matrix. (inheritable)

BGCOLOR*:(C)

Background color of column C. Example $m->GetAttribute("BGCOLOR*:15")

BGCOLOR(L):*

Background color of line L. Example $m->GetAttribute("BGCOLOR12:*")

BGCOLOR(L):(C)

Background color of the cell in line L and column C. Example $m->GetAttribute("BGCOLOR12:15")

When more than one attribute are defined, the background color will be selected following this priority: BGCOLOR(L):(C), BGCOLOR(L):*, BGCOLOR*:(C), and last BGCOLOR. (L or C >= 0)

Default BGCOLOR is the global attribute TXTBGCOLOR for cells and the parent's BGCOLOR for titles.

Since the matrix control can be larger than the matrix itself, the empty area will always be filled with the parent's BGCOLOR.

FGCOLOR

Text color. (inheritable)

FGCOLOR*:(C)

Text color of column C. Example $m->GetAttribute("FGCOLOR*:15")

FGCOLOR(L):*

Text color of line L. Example $m->GetAttribute("FGCOLOR12:*")

FGCOLOR(L):(C)

Text color of the cell in line L and column C. Example $m->GetAttribute("BGCOLOR12:15")

When more than one attribute are define, the text color of a cell will be selected following this priority: FGCOLOR(L):(C), FGCOLOR(L):*, FGCOLOR*:(C), and last FGCOLOR. (L or C >= 0)

Default FGCOLOR is the global attribute TXTFGCOLOR for cells or the global attribute DLGFGCOLOR for titles.

FONT

Character font of the text. (inheritable)

FONT(L):*

Text font of the cells in line L.

FONT*:(C)

Text font of the cells in column C.

FONT(L):(C)

Text font of the cell in line L and column C.

This attribute must be set before the control is showed. It affects the calculation of the size of all the matrix cells. The cell size is always calculated from the base FONT attribute.

FRAMECOLOR

Sets the color to be used in the frame lines. (inheritable)

FRAMEVERTCOLOR(L):(C)

Color of the vertical right frame of the cell. When not defined the FRAMECOLOR is used. For a title cell defines right and left frames. If value is "BGCOLOR" the frame line is not drawn.

FRAMEVERTCOLOR*:(C)

same as FRAMEVERTCOLORL:C but for all the cells of the column C. (since 3.5)

FRAMEHORIZCOLOR(L):(C)

Color of the horizontal bottom frame of the cell. When not defined the FRAMECOLOR is used. For a title cell defines bottom and top frames. If value is "BGCOLOR" the frame line is not drawn.

FRAMEHORIZCOLOR(L):*

same as FRAMEHORIZCOLORL:C but for all the cells of the line L. (since 3.5)

VALUE

Allows setting or verifying the value of the current cell. Is the same as obtaining the current cell from FOCUS_CELL value and using it as the attribute name for "L:C". But when updated or retrieved during cell editing, the edit control will be updated or consulted instead of the matrix cell. When retrieved inside the EDITION_CB callback when mode is 0, then the return value is the new value that will be updated in the cell.

CELLOFFSET(L):(C)

(read-only) Returns the cell computed offset in pixels from the top-left corner of the matrix, in the format "XxY" or "%dx%d" in C. Returns undef if the cell does not exists, or it is not visible, or the element is not mapped. It will only return a valid result if the cell has already been displayed. They are similar to the parameters of the DRAW_CB callback but they do NOT include the decorations. (since 3.5)

CELLSIZE(L):(C)

(read-only) Returns the cell computed size in pixels, in the format "WxH" or "%dx%d" in C. Returns undef if the cell does not exists, or the element is not mapped. It will only return a valid result if the cell has already been displayed. They are similar to the parameters of the DRAW_CB callback but they do NOT include the decorations. (since 3.5)

Column Attributes (no redraw)

ALIGNMENT(C): Alignment of the cells in column C (C >= 0). Possible values: "ALEFT", "ACENTER" or "ARIGHT". Default: "ALEFT" for n=0 and "ACENTER" for n > 0. Not used for the column title. The 0:0 corner is always ACENTER, and the other column titles are also centered but if they do not fit in the cell then the alignment is changed to ALEFT. Before checking the default value it will check the "ALIGNMENT" attribute value.
SORTSIGN(C): Shows a sort sign (up or down arrow) in the column C title. Possible values: "UP", "DOWN" and "NO". Default: NO.

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.

RASTERWIDTH(n): Same as WIDTHn but in pixels. Has lower priority than WIDTHn.
WIDTH(n): Width of column n in SIZE units, where n is the number of the column (n >= 0). If the width value is 0, the column will not be shown on the screen. It does not includes the decoration size occupied by the frame lines.
WIDTHDEF: Default column width in SIZE units. Not used for the title column. Default: 80 (width corresponding to 20 characters).

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.

HEIGHT(n): Height of line n in SIZE units, where n is the number of the line (n >= 0). If the height value is 0, the line will not be shown on the screen. It does not includes the decoration size occupied by the frame lines.
HEIGHTDEF: Default line height in SIZE units. Not used for the title line. Default: 8 (height corresponding to 1 line).
RASTERHEIGHT(n): Same as HEIGHTn but in pixels. Has lower priority than HEIGHTn.

Number of Cells Attributes

ADDCOL: (write-only) Adds a new column to the matrix after the specified column. To insert a column at the top of the spreadsheet, value 0 must be used. To add more than one column, use format "C-C", where the first number corresponds to the base column and the second number corresponds to the number of columns to be added. It is valid only in normal operation mode. Can NOT add a title column. Ignored if set before map.
ADDLIN: (write-only) Adds a new line to the matrix after the specified line. To insert a line at the top of the spreadsheet, value 0 must be used. To add more than one line, use format "L-L", where the first number corresponds to the base line and the second number corresponds to the number of lines to be added. It is valid only in normal operation mode. Can NOT add a title line. Ignored if set before map.
DELCOL: (write-only) Removes the given column from the matrix. To remove more than one column, use format "C-C", where the first number corresponds to the base column and the second number corresponds to the number of columns to be removed. It is valid only in normal operation mode. Can NOT remove a title column, (C) > 0. Ignored if set before map.
DELLIN: (write-only) Removes the given line from the matrix. To remove more than one line, use format "L-L", where the first number corresponds to the base line and the second number corresponds to the number of lines to be removed. It is valid only in normal operation mode. Can NOT remove a title line, (L) > 0. Ignored if set before map.
NUMCOL: Defines the number of columns in the matrix. Must be an integer number. Default: "0". It does not include the title column. If changed after map will add empty cells or discard cells at the end.
NUMCOL_VISIBLE: When set defines the number of visible columns to be counted when calculating the Natural size, not counting the title column. Not used elsewhere. The Natural size will always include the title column if any. Can be greater than the actual number of columns, so room will be reserved for adding new columns without the need to resize the matrix. Also it will always use the first columns of the matrix, except if NUMCOL_VISIBLE_LAST=YES then it will use the last columns. The remaining columns will be accessible only by using the scrollbar. IMPORTANT: When retrieved returns the current number of visible columns, not including the non scrollable columns. Default: "4".
NUMCOL_NOSCROLL: Number of columns that are non scrollable, not counting the title column. Default: "0". It does not affect the NUMCOL_VISIBLE attribute behavior nor Natural size computation. It will always use the first columns of the matrix. The cells appearance will be the same of ordinary cells, and they can also receive the focus and be edited. Must be less than the total number of columns. (since 3.5)
NUMLIN: Defines the number of lines in the matrix. Must be an integer number. Default: "0". It does not include the title line. If changed after map will add empty cells or discard cells at the end.
NUMLIN_VISIBLE: When set defines the number of visible lines to be counted when calculating the Natural size, not counting the title line. Not used elsewhere. The Natural size will always include the title line if any. Can be greater than the actual number of lines, so room will be reserved for adding new lines without the need to resize the matrix. Also it will always use the first lines of the matrix, except if NUMLIN_VISIBLE_LAST=YES then it will use the last lines. The remaining lines will be accessible only by using the scrollbar. IMPORTANT: When retrieved returns the current number of visible lines, not including the non scrollable lines. Default: "3".
NUMLIN_NOSCROLL: Number of lines that are non scrollable, not counting the title line. Default: "0". It does not affect the NUMLIN_VISIBLE attribute behavior nor Natural size computation. It will always use the first lines of the matrix. The cells appearance will be the same of ordinary cells, and they can also receive the focus and be edited. Must be less than the total number of lines. (since 3.5)

Mark Attributes

MARKAREA: Defines if the area to be interactively marked by the user must be continuous or not, valid only if MARKMULTIPLE=YES. Possible values: "CONTINUOUS" or "NOT_CONTINUOUS". Default: "CONTINUOUS".
MARKMODE: Defines the entity that can be marked: none, lines, columns, (lines or columns), and cells. Possible values: "NO", "LIN", "COL", "LINCOL" or "CELL". Default: "NO" (no mark).
MARKI(L):(C): marks a cell, a line or a column depending on MARKMODE, and returns cell, line or column mark state according to MARKMODE. Can be "1" or "0". If MARKMODE=LIN,COL,LINCOL use 0 to mark only the other element (ex: "0:3" set/get for column 3). Even when MARKMODE=LIN,COL,LINCOL you can specify a single cell address. (since 3.0)
MARKED: String of '0' or '1' characters, informing which cells are marked (indicated by value '1'). Use undef to clear all marks, returns undef if no marks. The format of this character vector depends on the value of the MARKMODE attribute: if its value is CELL, the vector will have NUMLIN x NUMCOL positions, corresponding to all the cells in the matrix starting with all the cells of the first line, then the second line and so on. If its value is LIN, the vector will begin with letter 'L' and will have further NUMLIN positions, each one corresponding to a line in the matrix. If its value is COL, the vector will begin with letter 'C' and will have further NUMCOL positions, each one corresponding to a column in the matrix. If its value is LINCOL, the first letter, which can be either 'L' or 'C', will indicate which of the above formats is being used. If you change the other mark attributes the marked cells are cleared. When setting the attribute the LIN and COL notation can be used even if MARKMODE=CELL. MULTIPLE and AREA are NOT considered when setting MARKED or MARKL:C.
MARKMULTIPLE: Defines if more than one entity defined by MARKMODE can be interactively marked. Possible values: "YES" or "NO". Default: "NO".

Action Attributes

FITTOSIZE

(write-only) force lines and/or columns sizes so the matrix visible size fit in its current size. NUMCOL_VISIBLE and NUMLIN_VISIBLE are considered when fitting and they are not changed, only the RASTERWIDTHn and RASTERHEIGHTn attributes are changed. But if any of the RASTERWIDTHn and RASTERHEIGHTn attributes where already set, then they will not be changed. If the matrix is resized then it must be set again to obtain the same result, but before doing that set to undef all the RASTERWIDTHn and RASTERHEIGHTn attributes that you want to be changed. Can be LINES, COLUMNS or YES (meaning both). (since 3.3)

FITTOTEXT

(write-only) set the RASTERWIDTHn or the RASTERHEIGHTn attribute for the given column or line, so that it will fit the largest text in the column or the highest text in the line. The number of the column or line must be preceded by a character identifying its type, "C" for columns and "L" for lines. For example "C5"=column 5 or "L3"=line 3. If FITMAXWIDTHn or FITMAXHEIGHTn are set for the column or line they are used as maximum limit for the size. (since 3.4)

SHOW

(write-only) If necessary scroll the visible area to make the given cell visible. To scroll to a line or a column, use a value such as "(L):*" or "*:(C)" (where L > 0 and (C) > 0).

REDRAW

(write-only) The user can inform the matrix that the data has changed, and it must be redrawn. Values:

"ALL": Redraws the whole matrix.
"L%d": Redraws the given line (e. g.: "L3" redraws line 3)
"L%d:%d": Redraws the lines in the given region (e.g.: "L2:4" redraws lines 2, 3 and 4)
"C%d": Redraws the given column (e.g.: "C3" redraws column 3)
"C%d:%d": Redraws the columns in the given region (e.g: "C2:4" redraws columns 2, 3 and 4)

No redraw is done when the application sets the attributes: L:C, ALIGNMENTn, BGCOLOR*, FGCOLOR*, FONT*, VALUE, FRAME*COLOR. Global and size attributes always automatically redraw the matrix.

Text Editing Attributes

CARET: Allows specifying and verifying the caret position of the text box in edition mode.
MASK(L):(C): Defines a mask that will filter text input. The MASK auxiliary attributes are also available adding the line and column at the end of the attribute name.
MULTILINE: allows the edition of multiple lines. Use Shift+Enter to add lines. Enter will end the editing.
SELECTION: Allows specifying and verifying selection interval of the text box in edition mode.

Canvas Attributes (inheritable)

BORDER: Changed to NO.
SCROLLBAR: Changed to YES.

CALLBACKS

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

Interaction Callbacks

ACTION_CB

Action generated when a keyboard event occurs.

Callback handler prototype:

sub action_cb_handler {
  my ($self, $key, $lin, $col, $edition, $value) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) where the user typed something

$key: Identifier of the typed key. Please refer to the IUP::Manual::06_HandlingKeyboard and IUP::Constants for a list of possible values.

$lin, $col: Coordinates of the selected cell.

$edition: 1 if the cell is in edition mode, and 0 if it is not.

$value: When EDIT_MODE=NO is the cell current value, but if the type key is a valid character then contains a string with that character. When EDIT_MODE=Yes depends on the editing field type. If a dropdown, then it is an empty string (""). If a text, and the type key is a valid character then it is the future value of the text field, if not a valid character then it is the cell current value. Notice that this value can be undef if the cell does not have a value and the key pressed is not a character.

Returns: IUP_DEFAULT validates the key, IUP_IGNORE ignores the key, IUP_CONTINUE forwards the key to IUPs conventional processing, or the identifier of the key to be treated by the matrix.

CLICK_CB

Action generated when any mouse button is pressed over a cell. This callback is always called after other callbacks.

Callback handler prototype:

sub click_cb_handler {
  my ($self, $lin, $col, $status) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell where the mouse button was pressed. They can be -1 if the user click outside the matrix but inside the canvas that contains it.

$status: Status of the mouse buttons and some keyboard keys at the moment the event is generated. The same macros used for BUTTON_CB can be used for this status.

Returns: To avoid the display update return IUP_IGNORE.

RELEASE_CB

Action generated when any mouse button is released over a cell. This callback is always called after other callbacks.

Callback handler prototype:

sub click_cb_handler {
  my ($self, $lin, $col, $status) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell where the mouse button was pressed. They can be -1 if the user click outside the matrix but inside the canvas that contains it.

$status: Status of the mouse buttons and some keyboard keys at the moment the event is generated. The same macros used for BUTTON_CB can be used for this status.

Returns: To avoid the display update return IUP_IGNORE.

MOUSEMOVE_CB

Action generated to notify the application that the mouse has moved over the matrix.

Callback handler prototype:

sub mousemove_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell that the mouse cursor is currently on.

ENTERITEM_CB

Action generated when a matrix cell is selected, becoming the current cell. Also called when matrix is getting focus.

Callback handler prototype:

sub enteritem_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the selected cell.

LEAVEITEM_CB

Action generated when a cell is no longer the current cell. Also called when the matrix is losing focus.

Callback handler prototype:

sub leaveitem_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell which is no longer the current cell.

Returns: IUP_IGNORE prevents the current cell from changing, but this will not work when the matrix is losing focus. If you try to move to beyond matrix borders the cell will lose focus and then get it again, so leaveitem_cb and enteritem_cb will be called.

SCROLLTOP_CB

Action generated when the matrix is scrolled with the scrollbars or with the keyboard. Can be used together with the ORIGIN and ORIGINOFFSET attributes to synchronize the movement of two or more matrices.

Callback handler prototype:

sub scrolltop_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell currently in the upper left corner of the matrix.

Drawing Callbacks

BGCOLOR_CB

Action generated to retrieve the background color of a cell when it needs to be redrawn.

Callback handler prototype:

sub bgcolor_cb_handler {
  my ($self, $lin, $col) = @_;
  my ($red, $green, $blue, $ret);
  #...
  return ($red, $green, $blue, $ret);  
}
#ZZZ-test-this

$self: reference to the element (IUP::Matrix) where the user typed something

$lin, $col: Coordinates of the cell.

$red, $green, $blue: the cell background color.

Returns: If IUP_IGNORE, the values are ignored and the attribute defined background color will be used. If returns IUP_DEFAULT the returned values will be used as the background color.

FGCOLOR_CB

Action generated to retrieve the foreground color of a cell when it needs to be redrawn.

Callback handler prototype:

sub fgcolor_cb_handler {
  my ($self, $lin, $col) = @_;
  my ($red, $green, $blue, $ret);
  #...
  return ($red, $green, $blue, $ret);   
}
#ZZZ-test-this

$self: reference to the element (IUP::Matrix) where the user typed something

$lin, $col: Coordinates of the cell.

$red, $green, $blue: the cell foreground color.

Returns: If IUP_IGNORE, the values are ignored and the attribute defined foreground color will be used. If returns IUP_DEFAULT the returned values will be used as the foreground color.

FONT_CB

Action generated to verify the font of a cell. Called both for common cells and for line and column titles. (since iup-3.0)

Callback handler prototype:

sub value_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell.

Returns: Must return a font or undef to use the the attribute defined font.

DRAW_CB

Action generated before a cell is drawn. Allows to draw a custom cell contents. You must use the IUP::Canvas methods. The clipping is set for the bounding rectangle. The callback is called after the cell background has been filled with the background color. The focus feedback area is not included in the decoration size.

Callback handler prototype:

sub draw_cb_handler {
  my ($self, $lin, $col, $x1, $x2, $y1, $y2, $cnv) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the current cell.

$x1, $x2, $y1, $y2: Bounding rectangle of the current cell in pixels, excluding the decorations.

$cnv: reference to IUP::Cavnas object used to draw the matrix

Returns: If IUP_IGNORE the normal text drawing will take place.

DROPCHECK_CB

Action generated before the current cell is redrawn to determine if a dropdown feedback should be shown. If this action is not registered, no feedback will be shown.

Callback handler prototype:

sub dropcheck_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell.

Returns: IUP_DEFAULT will show a dropdown field feedback, or IUP_IGNORE to NOT draw the dropdown feedback.

Editing Callback

DROP_CB

Action generated before the current cell enters edition mode to determine if a text field or a dropdown will be shown. It is called after EDITION_CB. If this action is not registered, a text field will be shown. Its return determines what type of element will be used in the edition mode. If the selected type is a dropdown, the values appearing in the dropdown must be fulfilled in this callback, just like elements are added to any list (the drop parameter is the handle of the dropdown list to be shown). You should also set the lists current value ("VALUE"), the default is always "1". The previously cell value can be verified from the given drop Ihandle via the "PREVIOUSVALUE" attribute.

Callback handler prototype:

sub drop_cb_handler {
  my ($self, $drop, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$drop: reference to dropdown list element (IUP::List) which will be shown to the user.

$lin, $col: Coordinates of the current cell.

Returns: IUP_IGNORE to show a text-edition field, or IUP_DEFAULT to show a dropdown field.

DROPSELECT_CB

Action generated when an element in the dropdown list is selected. If returns IUP_CONTINUE the value is accepted as a new value and the matrix leaves edition mode, else the item is selected and editing remains.

Callback handler prototype:

sub dropselect_cb_handler {
  my ($self, $lin, $col, $drop, $t, $i, $v) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the current cell.

$drop: reference to the dropdown list element (IUP::List) shown to the user.

$t: Text of the item whose state was changed.

$i: Number of the item whose state was changed.

$v: Indicates if item was selected or unselected (1 or 0).

EDITION_CB

Action generated when the current cell enters or leaves the edition mode. Not called if READONLY=YES.

Callback handler prototype:

sub edition_cb_handler {
  my ($self, $lin, $col, $mode, $update) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the current cell.

$mode: 1 if the cell has entered the edition mode, or 0 if the cell has left the edition mode.

$update: used when mode=0 to identify if the value will be updated whe the callback returns with IUP_DEFAULT.

Returns: can be IUP_DEFAULT, IUP_IGNORE or IUP_CONTINUE.

When mode=1 editing is allowed if the callback returns IUP_DEFAULT, so to make the cell read-only return IUP_IGNORE.

When mode=0 the new value is accepted only if the callback returns IUP_DEFAULT. The VALUE attribute returns the new value that will be updated in the cell. If the callback returns IUP_CONTINUE the edit mode is ended and the new value will not be updated, so the application can set a different value during the callback (usefull to format the new value). If the callback returns IUP_IGNORE the editing is not ended.

If the callback does not exists the value can always be edited and it is always accepted.

If the control loses its focus the edition mode will be ended always even if the callback return IUP_IGNORE. In this case update is 0.

This callback is also called if the user cancel the editing with Esc (in this case update is 0), and when the user press Del to validate the operation for each cell been cleared (in this case is called only with mode=1).

Callback Mode

VALUE_CB

Action generated to verify the value of a cell. Called both for common cells and for line and column titles.

Callback handler prototype:

sub value_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell.

Returns: the string to be redrawn.

IMPORTANT: The existance of this callback defines the callback operation mode of the matrix when it is mapped.

VALUE_EDIT_CB

Action generated to notify the application that the value of a cell was edited. Since it is a notification, it cannot refuse the value modification (which can be done by the "EDITION_CB" callback). Not called if READONLY=YES. This callback is usually set in callback mode, but also works in normal mode.

Callback handler prototype:

sub value_edit_cb_handler {
  my ($self, $lin, $col, $newval) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell.

$newval: String containing the new cell value

IMPORTANT: if VALUE_CB is defined and VALUE_EDIT_CB is not defined when the matrix is mapped it will be read-only.

MARK_CB

Action generated to verify the selection state of a cell. Called only for common cells, only when MARKMODE=CELL and only in callback mode.

Callback handler prototype:

sub mark_cb_handler {
  my ($self, $lin, $col) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell.

Returns: the selection state (marked=1, not marked 0). If not defined the attribute "MARKL:C" will be returned.

MARKEDIT_CB

Action generated to notify the application that the selection state of a cell was changed. Since it is a notification, it cannot refuse the mark modification. Called only for common cells, only when MARKMODE=CELL and only in callback mode.

Callback handler prototype:

sub markedit_cb_handler {
  my ($self, $lin, $col, $marked) = @_;
  #...
}

$self: reference to the element (IUP::Matrix) interacting with the user

$lin, $col: Coordinates of the cell.

$marked: selection state (marked=1, not marked 0).

If not defined the attribute "MARKL:C" will be updated. So if you define the MARKEDIT_CB the "MARKL:C" will NOT be updated and the callback MARK_CB must return the selection state of the cell. If you do not want to implement the MARK_CB callback then set the "MARKL:C" attribute inside the MARKEDIT_CB callback.

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

ACTION, SCROLL_CB, KEYPRESS_CB, MOTION_CB, MAP_CB
RESIZE_CB and BUTTON_CB cannot be changed from perl IUP bindings.

Use ConvertXYToPos to convert (x,y) coordinates in the cell position: pos = lin * numcol + col

See IUP::Canvas.

Utility Functions

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

MatAttribute()

# 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.

MatCell()

# 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")

EXAMPLES

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

0-basic/cbox.pl - IUP::Cbox example
0-basic/mask_matrix.pl - IUP::Matrix + MASK example
0-basic/matrix_basic.pl - IUP::Matrix example
0-basic/matrix_cbmode.pl - IUP::Matrix (callback mode) example

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

USAGE

CREATION - new() method

Storage

Callback Mode

Number of Cells

Titles

Natural Size

Virtual Size

Keyboard Navigation

Marks

ATTRIBUTES

General Attributes

Cell Attributes (no redraw)

Column Attributes (no redraw)

Column Size Attributes

Line Size Attributes

Number of Cells Attributes

Mark Attributes

Action Attributes

Text Editing Attributes

Canvas Attributes (inheritable)

CALLBACKS

Interaction Callbacks

Drawing Callbacks

Editing Callback

Callback Mode

Utility Functions

MatAttribute()

MatCell()

EXAMPLES

SEE ALSO

NAME

DESCRIPTION

USAGE

CREATION - new() method

Storage

Callback Mode

Number of Cells

Titles

Natural Size

Virtual Size

Keyboard Navigation

Marks

ATTRIBUTES

General Attributes

Cell Attributes (no redraw)

Column Attributes (no redraw)

Column Size Attributes

Line Size Attributes

Number of Cells Attributes

Mark Attributes

Action Attributes

Text Editing Attributes

Canvas Attributes (inheritable)

CALLBACKS

Interaction Callbacks

Drawing Callbacks

Editing Callback

Callback Mode

Utility Functions

MatAttribute()

MatCell()

EXAMPLES

SEE ALSO

Module Install Instructions