IupMatrix Attributes (all non inheritable with exceptions)

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

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;
NONE   - stay in the same cell. (since 3.6)

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. This will set the MAXSIZE attribute to match the natural size of the matrix. (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. (since 3.0)

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. (since 3.0)


ACTIVE, EXPAND, FONT, 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.

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 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)
FRAMEVERTCOLORL: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)
FRAMEHORIZCOLORL: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.
FRAMEHORIZCOLORL:*: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 line and column from FOCUS_CELL 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.


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)

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 Attributes (no redraw)

ALIGNMENTC : 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.

SORTSIGNC : Shows a sort sign (up or down arrow) in the column C (C >= 0) 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.

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

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

MARKL:C: 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".

Action Attributes

CLEARATTRIB (write-only): Clear all cell attributes if ALL, and all attributes except titles if CONTENTS. When ALL is specified, all lines and column attributes are also cleared. (since 3.6)
CLEARVALUEL: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. Action only works if the matrix is mapped and NOT in callback mode.

CLEARVALUE (write-only): Clear all values if ALL, and all values except titles if CONTENTS. (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. Action only works if the matrix is mapped and NOT in callback mode.

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)

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)

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

MASKL: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.