Expand/Shrink

IupMatrix

Definition: include pGUI.e

Ihandle ih = IupMatrix(string attributes="", dword_seq args={})
Description: Creates a matrix of alphanumeric fields. Therefore, all values of the matrix fields are strings.
The matrix is not a grid container like many systems have. It inherits from IupCanvas.

For more information on the attributes and args parameters see IupSetAttributes.


This is an additional control that depends on the CD library. It is included in the IupControls library.

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.

Returns the identifier of the created matrix.
pwa/p2js: Not supported, consider using IupTable() instead.
See Also: IupCanvas, IupImage, IupMatrixEx
Utility Functions: These functions can be used to help set and get attributes from the matrix:

IupMatSetAttribute(Ihandle ih, string name, integer lin, col, atom_string v) [same as IupSetAttributeId2]
IupMatStoreAttribute(Ihandle ih, string name, integer lin, col, string val, dword_seq args={}) [same as IupSetStrAttributeId2]
string res = IupMatGetAttribute(Ihandle ih, string name, integer lin, col) [same as IupGetAttributeId2]
integer res = IupMatGetInt(Ihandle ih, string name, integer lin, col) [same as IupGetIntId2]
atom res = IupMatGetFloat(Ihandle ih, string name, integer lin, col) [same as IupGetFloatId2]
You can also use IupSetIntId2 and IupSetFloatId2 (in lieu of IupMatSetInt and IupMatSetFloat).

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

When only one value is needed then use the Iup*AttributeId functions. For example:

IupSetAttribute(ih, "30:10", value) => IupSetAttributeId2(ih, "", 30, 10, value)
IupSetAttribute(ih, "BGCOLOR30:10", value) => IupSetAttributeId2(ih, "BGCOLOR", 30, 10, value)
IupSetAttribute(ih, "ALIGNMENT10", value) => IupSetAttributeId(ih, "ALIGNMENT", 10, value)

When one of the indices is the asterisk, use IUP_INVALID_ID as the parameter. For example:

IupSetAttribute(ih, "BGCOLOR30:*", value) => IupSetAttributeId2(ih, "BGCOLOR", 30, IUP_INVALID_ID, value)

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.

Note that the C function IupMatSetfAttribute is not wrapped, however that functionality is covered by the optional parameter of IupMatStoreAttribute.

IupMatrixSetFormula and IupMatrixSetDynamic are not supported at this time.
Notes: 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 can use the callback mode to store the cell values at the application, and not at the internal matrix storage. The idea is the following:

1 - Register the VALUE_CB callback
2 - No longer set the value of the cells. Store the cell value at the application. They will be retrieved one by one by the callback.
3 - If the matrix can be edited, set the VALUE_EDIT_CB callback.
4 - When the matrix display must be updated, 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 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.

Edition Mode
When READONLY=NO and there is no EDITION_CB callback or the callback return is IUP_DEFAULT, the matrix cell values can be edited.

Editing starts automatically when the user press a character key when the focus is at a cell, then the old cell value 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.
And double-clicking a cell enters the edition mode (in Motif the user must click again to the edit control get the focus).

The new value will be accepted if the user press Enter during edition mode. Pressing Esc will cancel the editing and the 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 new value will be automatically accepted.
But the value confirmation still depends on the EDITION_CB callback return code.

Keyboard Navigation
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 first 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.

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.
Also while pressing together the Shift key and marks are enabled with MARKMULTIPLE=Yes then a continuous area will be selected (since 3.9).

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.

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.
This can be controlled using the EDITNEXT attribute.

Marks (Selected Cells)
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.

When there are cells marked, pressing the Del key remove the selected cells contents.

IupMatrixEx
For more features, like Import/Export, Clipboard, Undo/Redo, Search, Sort, Column Visibility, Numeric Columns, Numeric, Context Menu and others, see the IupMatrixEx extension library.
Attributes:
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 "IupMatrixCrossCursor".
DROPIMAGE drop image name. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. By default an internal image will be used. (since 3.16)
FOCUSCELL 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".
Note that setting FOCUSCELL does not automatically trigger a corresponding ENTERITEM_CB.
FLAT removes the 3D appearance from the matrix. (since 3.25)
FLATSCROLLBAR enable the flat scrollbars. Can be set only before map. SCROLLBAR is set to NO. Can be Yes, Vertical or Horizontal. Default: not defined. (since 3.22)
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.
HLCOLOR (non inheritable) the overlay color for the selected cells. Default: TXTHLCOLOR global attribute. If set to "" will only use the attenuation process. The color is composited using HLCOLORALPHA attribute as alpha value (default is 128). (since 3.16)
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 "X:Y" or "%d:%d" in C.
When changing this attribute must change also ORIGIN right after. (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. (since 3.0)
SHOWFILLVALUE enable the display of the numeric percentage in the cell when TYPE* is FILL. Default: NO. (since 3.9)
TOGGLECENTERED center the toggle and use the cell value in place of TOGGLEVALUEL:C. No text will be drawn. (since 3.16)
TOGGLEIMAGEON,
TOGGLEIMAGEOFF
sort sign image name. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. By default an internal image will be used. (since 3.16)
TYPECOLORINACTIVE when inactive the color of the cell for TYPE*=COLOR will be attenuated as everything else. Default: Yes. (since 3.19)
also ACTIVE, EXPAND, FONT, NAME, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE: also accepted.
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.
L:0 Title of line L.
0:C Title of column C.
0:0 Title of the area between the line and column titles.

These are valid only in normal mode.
ALIGNL:C Alignment of the cell value in line L and column C.
Values are in the format "linalign:colalign", where linalign can be "ATOP", "ACENTER" or "ABOTTOM", and colalign can be "ALEFT", "ACENTER" or "ARIGHT".
Default will use ALIGNMENT* and LINEALIGMENT*. (Since 3.16)
TYPEL:C Type of the cell value in line L and column C. (Since 3.9)
TYPE*:C Type of column C. (Since 3.9)
TYPEL:* Type of line L. (Since 3.9)

Can be TEXT, COLOR, FILL, or IMAGE.
When type is COLOR the cell value is interpreted as a color and a rectangle with the color is drawn inside the cell instead of the text (the FGCOLOR of the cell is ignored).
When type is FILL the cell value is interpreted as percentage and a rectangle showing the percentage in the FGCOLOR is drawn like in IupProgressBar.
When type is IMAGE the cell value is interpreted as an image name, and if an image exist with that name is drawn (the name can NOT be of a Windows resource or GTK stock image).
Only TEXT and IMAGE are affected by alignment attributes. Default: TEXT. (Since 3.9)
BGCOLOR Background color of the matrix. (inheritable)
BGCOLOR*:C Background color of column C.
BGCOLORL:* Background color of line L.
BGCOLORL:C Background color of the cell in line L and column C.

When more than one attribute are defined, the background color will be selected following this priority: BGCOLORL:C, BGCOLORL:*, 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.
FGCOLORL:* Text color of line L.
FGCOLORL:C Text color of the cell in line L and column C.

When more than one attribute are define, the text color of a cell will be selected following this priority: FGCOLORL:C, FGCOLORL:*, 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)
FONTL:* Text font of the cells in line L.
FONT*:C Text font of the cells in column C.
FONTL:C Text font of the cell in line L and column C.

This attribute must be set before the control is shown.
It affects the calculation of the size of all the matrix cells.
The cell size is always calculated from the base FONT attribute.
FONTSTYLEL:C and FONTSIZEL:C can also be used to set FONT changing only the font style or size (since 3.21).
FRAMECOLOR Sets the color to be used in the frame lines. (inheritable)
FRAMEVERTCOLORL:C Color of the vertical right frame line of the cell. When not defined the FRAMECOLOR is used.
For a title column cell (col=0) 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)
FRAMEVERTCOLORL:* same as FRAMEVERTCOLORL:C but for all the cells of the line L. When not defined the FRAMECOLOR*:C is used. (since 3.28)
FRAMETITLEVERTCOLORL:0 color of the vertical left frame line of the cell. When not defined the FRAMEVERTCOLORL:0 is used. "L" can also be "*" (since 3.22)
FRAMEHORIZCOLORL:C Color of the horizontal bottom frame line of the cell. When not defined the FRAMECOLOR is used.
For a title line cell (lin=0) defines bottom and top frames. If value is "BGCOLOR" the frame line is not drawn.
FRAMEHORIZCOLORL:* same as FRAMEHORIZCOLORL:C but for all the cells of the line L. (since 3.5)
FRAMEHORIZCOLOR*:C same as FRAMEHORIZCOLORL:C but for all the cells of the column C. When not defined the FRAMECOLORL:* is used. (since 3.28)
FRAMETITLEHORIZCOLOR0:C color of the horizontal top frame line of the cell. When not defined the FRAMEHORIZCOLOR0:C is used. "C" can also be "*". (since 3.22)
FRAMETITLEHIGHLIGHT by default the title cells will have a bright line at left and top to configure a raise appearance. Can be Yes or No. Default: Yes. (since 3.9)
FRAMEBORDER show a fixed border (non scrollable) of 1 pixel around the matrix visible area using FRAMECOLOR.
It is drawn after the matrix cells are drawn. Drawn only when the scrollbars are visible, and only up to matrix total size. Default: No. (since 3.20)
RESIZEMATRIXCOLOR color used by the column resize feedback. Default: "102 102 102". (Since 3.9)
TOGGLEVALUEL:C value of the toggle inside the cell. The toggle is shown only if the DROPCHECK_CB returns IUP_CONTINUE for the cell.
When the toggle is interactively change the TOGGLEVALUE_CB callback is called. (Since 3.9)
VALUE Allows setting or verifying the value of the current cell.
Is the same as obtaining the current cell line and column from FOCUSCELL attribute, and then using them to access the "L:C" attribute.
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.
CELLL:C (read-only) Returns the displayed cell value. Returns NULL if the cell does not exists, or it is not visible, or the element is not mapped. (since 3.14)
CELLBGCOLORL:C (read-only) Returns the actual cell background color, including mark and active state modifications.
Returns NULL if the cell does not exists, or it is not visible, or the element is not mapped. (since 3.6)
CELLFGCOLORL:C (read-only) Returns the actual cell foreground color, including mark state modifications.
Returns NULL if the cell does not exists, or it is not visible, or the element is not mapped. (since 3.6)
CELLFONTL:C (read-only): Returns the actual cell font, including lin and col variations, callback returned values.
Returns NULL if the cell does not exists, or it is not visible, or the element is not mapped. (since 3.23)
CELLTYPEL:C (read-only): Returns the actual cell type, including lin and col variations, callback returned values.
Returns NULL if the cell does not exists, or it is not visible, or the element is not mapped. (since 3.23)
CELLFRAMEHORIZCOLORL:C (read-only): Returns the actual cell frame horizontal color, including lin and col variations.
Returns NULL if the cell does not exists, or it is not visible, the element is not mapped, or the color is transparent. (since 3.23)
CELLFRAMEVERTCOLORL:C (read-only): Returns the actual cell frame vertical color, including lin and col variations.
Returns NULL if the cell does not exists, or it is not visible, the element is not mapped, or the color is transparent. (since 3.23)
CELLALIGNMENTL:C (read-only): Returns the actual cell text aligment, including lin and col variations.
Returns NULL if the cell does not exists, or it is not visible, or the element is not mapped. (since 3.23)
CELLOFFSETL: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 NULL 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)
CELLSIZEL:C (read-only) Returns the cell computed size in pixels, in the format "WxH" or "%dx%d" in C.
Returns NULL 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/Line Only Attributes (no redraw)
ALIGNMENTC Horizontal alignment of the cells in column C (C >= 0) for lines>0.
Can be: "ALEFT", "ACENTER" or "ARIGHT". Default: "ALEFT" for C=0 and "ACENTER" for C>0.
Before checking the default value it will check the "ALIGNMENT" attribute value.
If the text does not fit in the cell then the alignment is changed to ALEFT.
ALIGNMENTLIN0 Horizontal alignment of all the cells in line 0. Default is "ACENTER". (since 3.9)
LINEALIGNMENTL Vertical alignment of the cells in line L (L >= 0) for all columns.
Can be: "ATOP", "ACENTER" or "ABOTTOM". Default is "ACENTER". (since 3.16)
SORTSIGNC Shows a sort sign (up or down arrow) in the column C (C >= 0) title.
Possible values: "UP", "DOWN" and "NO". Default: NO.
SORTIMAGEDOWN,
SORTIMAGEUP
sort sign image name. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. By default an internal image will be used. (since 3.16)
Size Attributes (no redraw)
LIMITEXPAND limit expansion to the maximum size that shows all cells.
This will set the MAXSIZE attribute to match the natural size of the matrix when all cells are visible.
When the scrollbars have *AUTOHIDE=Yes, the maximum size will not include the scrollbars (since 3.9). (since 3.5)
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).
RESIZEDRAG Resize the column while dragging.
By default the column is resized only when the mouse button is released, the resize feedback is a simple vertical line.
Works only when RESIZEMATRIX=Yes. Default: NO. (since 3.25)
USETITLESIZE Use the title size to define the cell size if necessary. See WIDTHn and HEIGHTn. Default: NO. (since 3.0)
Column Size Attributes For all columns if WIDTHn is not defined, then RASTERWIDTHn is used, otherwise the following logic is used:
If it is the title column (n=0), then if USETITLESIZE=YES or not in callback mode, it searches 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.
RASTERWIDTHn Same as WIDTHn but in pixels. Has lower priority than WIDTHn. The returned value is the actual computed size.
WIDTHn 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.
The returned value is the actual computed size.
WIDTHDEF Default column width in SIZE units. Not used for the title column. Default: 80 (width corresponding to 20 characters).
MINCOLWIDTHid when the column is interactively resized controls the minimum width of the given column. If not defined MINCOLWIDTHDEF is used. (since 3.26)
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.
HEIGHTn 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.
The returned value is the actual computed size.
HEIGHTDEF Default line height in SIZE units. Not used for the title line. Default: 8 (height corresponding to 1 line).
RASTERHEIGHTn Same as HEIGHTn but in pixels. Has lower priority than HEIGHTn. The returned value is the actual computed size.
Number of Cells Attributes When lines or columns are added or removed the existing cell, line and column attributes are preserved, except custom application 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 can be used in normal operation mode or in callback mode, but in callback mode will not update cell values this must be done by the application.
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 can be used in normal operation mode or in callback mode, but in callback mode will not update cell values this must be done by the application.
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 can be used in normal operation mode or in callback mode, but in callback mode will not update cell values this must be done by the application.
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 can be used in normal operation mode or in callback mode, but in callback mode will not update cell values this must be done by the application.
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)
NOSCROLLASTITLE Non scrollable lines and columns to look and behave as title cells. Can be Yes or No. Default: No. (since 3.24)
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".
MARKATTITLE a click at a title will mark a full line or a full column if they can be marked. Default: "Yes". (since 3.16)
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).
MARKL:C (no redraw) marks a cell, a line or a column depending on MARKMODE, and returns cell, line or column mark state also 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 NULL to clear all marks, returns NULL 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".
Merge Attributes (since 3.23)
MERGEL:C merge a range of cells starting from the given "lin:col" (in id), and ending at the given "lin:col" (in value).
Title cells can also be merge but only among them, i.e. in the line of column titles (L=0) can only merge columns, and in the column of line titles (C=0) can only merge lines.
The corner cell (0:0) can not be merged with any other cell.
Only cells that are not already merged can be merged into a range.
Returns if the given cell belongs to a merged range, can be "Yes" or "No".
MERGESPLIT (write-only): split a merged range. value is a cell "lin:col" than belongs to the range, any cell of the range can be used.
MERGEDSTARTL:C (read-only): returns the start cell of the range given a cell that belongs to the range, any cell of the range can be used.
MERGEDENDL:C (read-only): returns the end cell of the range given a cell that belongs to the range, any cell of the range can be used.
Action Attributes
CLEARATTRIB (write-only) Clear all cell attributes if ALL, all attributes except titles if CONTENTS, and all selected cell attributes if MARKED.
When ALL is specified, all lines and column attributes are also cleared. (since 3.6)
CLEARATTRIBL:C (write-only) Clear all cell attributes in an interval starting at the specified cell.
Its value defines the end cell in the "L:C" format, the default is the last cell. (since 3.6)
CLEARATTRIBL:* (write-only) the cell attributes in line L. Its value defines a column inclusive interval in the "C1-C2" format. The default is 0 and the last column.
When a full line is specified, all line attributes are also cleared. (since 3.6)
CLEARATTRIB*:C (write-only) the cell attributes in column C. Its value defines a line inclusive interval in the "L1-L2" format. The default is 0 and the last line.
When a full column is specified, all column attributes are also cleared, including ALIGNMENT and SORTSIGN. (since 3.6)

In all cases, attributes are set to NULL.
Only the attributes FONT*, BGCOLOR*, FGCOLOR*, FRAMEHORIZCOLOR*, FRAMEHORIZCOLOR*, ALIGNMENT* and SORTSIGN* are affected.
In callback mode will not call the user callbacks.
CLEARVALUE (write-only) Clear all values if ALL, all values except titles if CONTENTS, and all selected cell values if MARKED. (since 3.6)
CLEARVALUEL:C (write-only) Clear all values in an interval starting at the specified cell. Its value defines the end cell in the "L:C" format, the default is the last cell. (since 3.6)
CLEARVALUEL:* (write-only) the values in line L. Its value defines a column inclusive interval in the "C1-C2" format. The default is 0 and the last column. (since 3.6)
CLEARVALUE*:C (write-only) the values in column C. Its value defines a line inclusive interval in the "L1-L2" format. The default is 0 and the last line. (since 3.6)

In all cases, values are set to NULL. Works also in callback mode.
COPYCOLC (write-only) copy the values and attributes from column C to the given column (value is the number of a column). (Since 3.9)
COPYLINL (write-only) copy the values and attributes from line L to the given line (value is the number of a line). (Since 3.9)
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 NULL 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) Fit 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)
MOVECOLC (write-only) move the values and attributes from column C to the given column (value is the number of a column).
Internally will use ADDCOL+COPYCOL+DELCOL to perform the move so it is limited to those attributes restrictions.
It can be used in normal operation mode or in callback mode, but in callback mode will not update cell values, this must be done by the application. (Since 3.9)
MOVELINL (write-only) move the values and attributes from line L to the given line (value is the number of a line).
Internally will use ADDLIN+COPYLIN+DELLIN to perform the move so it is limited to those attributes restrictions.
It can be used in normal operation mode or in callback mode, but in callback mode will not update cell values, this must be done by the application. (Since 3.9)
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, ALIGNMENTc, BGCOLOR*, FGCOLOR*, FONT*, VALUE, FRAME*COLOR, MARKL:C.
Global and size attributes always automatically redraw the matrix.
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). (since 3.0)
Editing Attributes
EDITMODE When set to YES, programmatically puts the current cell in edition mode, allowing the user to modify its value.
When consulted informs if the editing control is visible (text or dropdown). Possible values: "YES" or "NO".
EDITALIGN sets the text box alignment to the column alignment when editing a cell value. Default: No. (since 3.14)
EDITCELL (read-only) returns the current cell being edited ("L:C"), or NULL if none.
Can also be used during interaction while editing is being performed and EDITHIDEONFOCUS=NO. (since 3.14)
EDITFITVALUE enable a text box larger than the cell size of necessary, according to the cell font and cell current value.
While editing if more room is necessary it will grow to the right. (since 3.14)
EDITHIDEONFOCUS when editing a cell if text box loses its focus, then editing ends. Default: Yes.
When set to NO editing will continue and the matrix can be scrolled, also when pressing Esc or Enter if the focus is at the matrix it has the same effect as if pressed at the text box. (since 3.14)
EDITING (read-only) returns Yes if the editing process is active for text or dropdown.
It is set to Yes after EDITION_CB, after MENUDROP_CB, before DROP_CB and before the editing control is made visible.
Set to NO when editing is about to end, after EDITION_CB and after the value has been updated, but before the editing control is made invisible. (since 3.13)
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;
NONE - stay in the same cell. (since 3.6)
EDITTEXT (read-only) returns Yes if the editing is being done by a text box. (since 3.14)
EDITVALUE (read-only) returns Yes if the display cell value being consulted will be used for a text box initial value.
Useful for being consulted inside the translate and numeric callbacks. (since 3.14)
Text Editing Attributes
CARET Allows specifying and verifying the caret position of the text box in edition mode.
INSERT inserts a text at the caret position of the text box in edition mode. (since 3.14)
MASKL:C or
MASKL:* or
MASK*:C
Defines a mask that will filter text input. The MASK auxiliary attributes are also available by 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:
Interaction
ACTION_CB Action generated when a keyboard event occurs.

function action_cb(Ihandle ih, integer key, lin, col, edition, atom pValue)

ih: identifier of the element that activated the event.
key: Identifier of the typed key. Please refer to the Keyboard Codes table 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.
pValue: (a char*) When EDITMODE=NO is the cell current value, but if the type key is a valid character then contains a string with that character.
When EDITMODE=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 NULL 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.
When EDITHIDEONFOCUS=NO and editing is on going the callback EDITCLICK_CB with the same parameters will also be called right before this one (since 3.14).

function click_cb(Ihandle ih, integer lin, col, atom pStatus)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell where the mouse button was pressed.
pStatus: (a char*) 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.
COLRESIZE_CB Action generated when a column is interactively resized.

function colresize_cb(Ihandle ih, integer col)

ih: identifier of the element that activated the event.
col: Column that had its size changed.
RELEASE_CB Action generated when any mouse button is released over a cell.
This callback is always called after other callbacks.
When EDITHIDEONFOCUS=NO and editing is on going the callback EDITRELEASE_CB with the same parameters will also be called right before this one (since 3.14).

function release_cb(Ihandle ih, integer lin, col, atom pStatus)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell where the mouse button was pressed.
pStatus: Status (char*) 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.
RESIZEMATRIX_CB Action generated after the element size has been updated but before the cells have been actually refreshed.

function resizematrix_cb(Ihandle ih, integer width, height)

ih: identifier of the element that activated the event.
width: the width of the internal element size in pixels not considering the BORDER size (client size)
height: the height of the internal element size in pixels not considering the BORDER size (client size)
TOGGLEVALUE_CB Action generated when a toggle button is pressed.

function togglevalue_cb(Ihandle ih, integer lin, col, status)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell where the mouse button was pressed.
status: Value of the toggle. Can be 1 or 0.
VALUECHANGED_CB Called after the value was interactively changed by the user or after a group of values where programmatically changed in a single operation.
When it was interactively changed the temporary attribute CELL_EDITED will be set to Yes during the callback (since 3.13).

function valuechanged_cb(Ihandle ih)

ih: identifier of the element that activated the event.
MOUSEMOVE_CB Action generated to notify the application that the mouse has moved over the matrix.
When EDITHIDEONFOCUS=NO and editing is on going the callback EDITMOUSEMOVE_CB with the same parameters will also be called right before this one (since 3.14).

function mousemove_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
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. Also called when focus is changed because lines or columns were added or removed (since 3.9).

function enteritem_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
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.

function leaveitem_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
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.

function scrolltop_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell currently in the upper left corner of the matrix.
Drawing
BGCOLOR_CB Action generated to retrieve the background color of a cell when it needs to be redrawn.

function bgcolor_cb(Ihandle ih, integer lin, col, atom pRed, pGreen, pBlue)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.
pRed, pGreen, pBlue: (int*) 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.

function fgcolor_cb(Ihandle ih, integer lin, col, atom pRed, pGreen, pBlue)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.
pRed, pGreen, pBlue: (int*) 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 retrieve the font of a cell when it needs to be redrawn.
Called both for common cells and for line and column titles. (since 3.0)

function funtion_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.

Returns: Must return a font (char*, see IupRawStringPtr) or NULL to use the the attribute defined font.
TYPE_CB Action generated to retrieve the type of a cell value.
Called both for common cells and for line and column titles. (since 3.9)

function type_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.

Returns: Must return "TEXT", "COLOR", "FILL" or "IMAGE" (as a char*, see IupRawStringPtr).
DRAW_CB Action generated before a cell is drawn. Allows the drawing of custom cell contents.
You must use the CD library primitives. 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.

CD control functions like cdCanvasActivate, cdCanvasDeactivate, cdCanvasFlush, cdCanvasClear, can NOT be called.
Since IUP 3.25, the OLD CD functions declared in "cd_old.h" can not be used anymore.

function draw_cb(Ihandle ih, integer lin, col, x1, x2, y1, y2, cdCanvas cnv)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the current cell.
x1, x2, y1, y2: Bounding rectangle of the current cell in pixels, excluding the decorations.
cnv: internal canvas CD 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/popup menu feedback or a toggle should be shown.
If this action is not registered, no feedback will be shown.
If the callback is defined and return IUP_DEFAULT for a cell, to show the dropdown/popup menu the user can simply do a single click in the drop feedback area of that cell.

function dropcheck_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.

Returns: IUP_DEFAULT will show a drop feedback, IUP_CONTINUE will show and enable the toggle button, or IUP_IGNORE to draw nothing.
TRANSLATEVALUE_CB Action generated to translate the value of a cell during display and size computation.
Called both for common cells and for line and column titles. (since 3.13)

function(Ihandle ih, integer lin, col, atom pValue)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.
pValue: original cell value (a char*)

Returns: the string to be drawn (as a char*, see IupRawStringPtr).
Editing
DROP_CB Action generated before the current cell enters edition mode to determine if a text field or a dropdown list 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.

function drop_cb(Ihandle ih, Ihandle drop, integer lin, col)

ih: identifier of the element that activated the event.
drop: Identifier of the dropdown 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.
MENUDROP_CB Action generated before the current cell enters edition mode to determine if a popup menu will be shown instead of a text field or a dropdown.
If this action is registered and retunr IUP_DEFAULT the DROP_CB callback is not called, and the popup menu is shown.
Like DROP_CB, it is called after EDITION_CB.
The values appearing as menu items in the popup menu must be fulfilled in this callback, like elements are added to a list
(the drop parameter is the handle of the popup menu to be shown, but the actual items will be added later by the internal processing).
You could also set the "VALUE" attribute that will add a mark to the menu item with the same number.
If IMAGEid is set then an IMAGE attribute will be set at the correspondent menu item.
The previously cell value can be verified from the given drop Ihandle via the "PREVIOUSVALUE" attribute. (since 3.6)

function menudrop_cb(Ihandle ih, Ihandle drop, integer lin, col)

ih: identifier of the element that activated the event.
drop: Identifier of the popup menu which will be shown to the user.
lin, col: Coordinates of the current cell.

Returns: IUP_IGNORE to not show the menu for the given cell, DROP_CB will then be called.
DROPSELECT_CB Action generated when an element in the dropdown list or the popup menu is selected.
For the dropdown, 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. For the popup menu the returned value is ignored.

function dropselect_cb(Ihandle ih, integer lin, col, Ihandle drop, atom pTxt, integer i, v)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the current cell.
drop: Identifier of the dropdown list or the popup menu shown to the user.
pText: Text (char*) 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). Always 1 for the popup menu.
EDITION_CB Action generated when the current cell enters or leaves the edition mode. Not called if READONLY=YES.

function edition_cb(Ihandle ih, integer lin, col, mode, update)

ih: identifier of the element that activated the event.
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 when the callback returns with IUP_DEFAULT. (since 3.0)

Returns: can be IUP_DEFAULT, IUP_IGNORE or IUP_CONTINUE.

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

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

When editing ends, mode=0 and update can be 0 or 1. The new value is accepted only if the callback returns IUP_DEFAULT.
The VALUE attribute when consulted inside the callback returns the new value that will be updated to the cell.
update=0 only when the user cancel the editing by pressing the Esc key.
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 (useful to format the new value).
If the callback returns IUP_IGNORE the editing is not ended, with several exceptions:
the Esc key was used;
the matrix size, scroll or visibility was changed during edition mode;
a click in another cell; or
the edit control loses its focus.

This callback is also called when the user press Del to clear the cell contents or other multiple cell editing.
The callback will simply validate the operation for each cell been cleared by checking if the matrix is read-only or if the cell is read-only.
In this situation it is called with mode=1 and update=1. When in normal mode (not callback mode) the new value can not be refused,
but you can use the VALUE_EDIT_CB to reset a new value or use the VALUECHANGED_CB to check all the new values after they where changed.
Callback Mode
VALUE_CB Action generated to retrieve the value of a cell. Called both for common cells and for line and column titles.

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

function value_cb(Ihandle ih, integer lin, col) -- returns an atom (aka char*)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.

Returns: a pointer to memory containing the string to be drawn.
NOTE: the return value must outlive the callback. See IupRawStringPtr for an example.
VALUE_EDIT_CB Action generated to notify the application that the value of a cell was changed.
Never called when READONLY=YES.
This callback is usually set in callback mode, but also works in normal mode.
When in normal mode, it is called after the new value has been internally stored, so to refuse the new value simply reset the cell to the desired value.
When it was interactively changed the temporary attribute CELL_EDITED will be set to Yes during the callback (since 3.13).

function value_edit_cb(Ihandle ih, integer lin, col, atom pNewval)

ih: identifier of the element that activated the event.
lin, col: Coordinates of the cell.
pNewval: String (char*) 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 retrieve the selection state of a cell. Called only for common cells, only when MARKMODE=CELL and only in callback mode.

function mark_cb(Ihandle ih, integer lin, col)

ih: identifier of the element that activated the event.
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.

function markedit_cb(Ihandle ih, integer lin, col, marked)

ih: identifier of the element that activated the event.
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.
also MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.

The IupCanvas callbacks ACTION, SCROLL_CB, KEYPRESS_CB, MOTION_CB, FOCUS_CB, RESIZE_CB and BUTTON_CB can be changed
but you should save and call the original definition from inside your own callback, or the matrix will not work correctly.

Use IupConvertXYToPos() to convert (x,y) coordinates in the cell position, then use IupTextConvertPosToLinCol() to convert pos into (lin,col),
or use the formula "pos=lin*(NUMCOL+1) + col". Here lin and col starts at 0, pos starts at 0.