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 inherits from IupCanvas.
This is an additional control that depends on the CD library. It is included in the Controls 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 existance of this callback defines the mode the matrix will operate.
Ihandle* IupMatrix(char *action_cb); [in C] iup.matrix{} -> (elem: ihandle) [in Lua] matrix(action_cb) [in LED]
action_cb: Name of the action generated when the user types something.
Returns the identifier of the created matrix, or NULL if an error occurs.
ACTION_CB -
Action generated when a keyboard event
occurs.
CLICK_CB -
Action generated when any mouse button is
pressed over a cell.
RELEASE_CB -
Action generated when any mouse button is
released over a cell.
MOUSEMOVE_CB -
Action generated to notify the application
that the mouse has moved over the matrix.
ENTERITEM_CB -
Action generated when a matrix cell is
selected, becoming the current cell.
LEAVEITEM_CB -
Action generated when a cell is no longer
the current cell.
SCROLLTOP_CB -
Action generated when the matrix is scrolled
with the scrollbars or with the keyboard.
BGCOLOR_CB -
Action generated to retrieve the background
color of a cell when it needs to be redrawn.
FGCOLOR_CB -
Action generated to retrieve the foreground
color of a cell when it needs to be redrawn.
FONT_CB -
Action generated to retrieve the font
of a cell when it needs to be redrawn.
DRAW_CB -
Action generated before the cell is drawn.
Allow a custom cell draw.
DROPCHECK_CB -
Action generated to determine if a dropdown
feedback should be shown.
DROP_CB -
Action generated to determine if a text
field or a dropdown will be shown.
DROPSELECT_CB -
Action generated when an element in the
dropdown list is selected.
EDITION_CB -
Action generated when the current cell
enters or leaves the edition mode.
VALUE_CB -
Action generated to verify the value of a
cell.
VALUE_EDIT_CB -
Action generated to notify the application
that the value of a cell was edited.
MARK_CB -
Action generated to verify the selection
state of a cell.
MARKEDIT_CB -
Action generated to notify the application
that the selection state of a cell was changed.
elem:setcell(lin, col: number, value: string)
Modifies the text of a cell.
elem:getcell(lin, col: number) -> (cell: string)
Returns the text of a cell.
These functions can be used to help set and get attributes from the matrix:
void IupMatSetAttribute(Ihandle*h, const char* a, int l, int c, char* v); void IupMatStoreAttribute(Ihandle* ih, const char* a, int l, int c, char* v); char* IupMatGetAttribute(Ihandle* ih, const char* a, int l, int c); int IupMatGetInt(Ihandle* ih, const char* a, int l, int c); float IupMatGetFloat(Ihandle* ih, const char* a, int l, int c); void IupMatSetfAttribute(Ihandle* ih, const char* a, int l, int c, const char* f, ...);
They work just like the respective tradicional set and get functions. But the attribute string is complemented with the L and C values. For ex:
IupMatSetAttribute(ih, "" , 30, 10, v) = IupSetAttribute(n, "30:10", v) IupMatSetAttribute(ih, "BGCOLOR" , 30, 10, v) = IupSetAttribute(n, "BGCOLOR30:10", v) IupMatSetAttribute(ih, "ALIGNMENT" , 10, 0, v) = IupSetAttribute(n, "ALIGNMENT10:0", v) (*) (*) noticed that in this case the second value will be ignored.
These functions are not available in Lua, since you can simply write:
elem["bgcolor"..l..":"..c] = v or elem["bgcolor30:10"] = v
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 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 mapped in callback mode cell values stored in the hash table are ignored.
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.
If you do not plan to set SIZE or RASTERSIZE, then set NUMCOL_VISIBLE and NUMLIN_VISIBLE so the Natural size will give better results. 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), or line 0 plus the sum from line NUMLIN-NUMLIN_VISIBLE to NUMLIN if NUMLIN_VISIBLE_LAST is defined. The natural width is the sum of the column width from column 0 to NUMCOL_VISIBLE (inclusive), or column 0 plus the sum from column NUMCOL-NUMCOL_VISIBLE to NUMCOL if NUMCOL_VISIBLE_LAST is defined. 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 heighest 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.
When the scrollbars are enabled if the matrix area is greatter than the visible area then scroolbars will be displayed so the cells can be scrolled to be visible area. But the scrooling position is not free, the first cell at the top right corner is always aligned at the begining of the cell. So the scroll increment is a cell and it can not be broken. One problem that raises from this policy is that depending on the visible size the last cell may never be completely visible. So solve the matrix size must be ajusted so all the last cells are visible within the visible area, or the natural size can be computed using the last cells instead of the first cells using the attributes NUMCOL_VISIBLE_LAST and NUMLIN_VISIBLE_LAST.
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.
A matrix might have titles for lines and columns. Titles are not 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. It will have a column of titles if an attribute of the "0:C" type is defined, where C is a column number.
When allowed the width of a column can be changed holding and dragging its title right border, see RESIZEMATRIX.
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 VALUE_CB is defined and VALUE_EDIT_CB is not defined when the matrix is mapped then READONLY will be set to YES.
Keyboard navigation through the matrix cells outside the edition mode is done by using the following keys:
When the matrix is outside the edition mode, pressing any character key makes the current key to enter in the edition mode, the old text is replaced by the new one being typed. If F2, Enter or Space is pressed, the current cell enters the edition mode with the current text of the cell. Double-clicking a cell also enters the edition mode (in Motif the user must click again to the edit control get the focus).
When using the keyboard to change the focus cell if the limit of the visible area is reached then the cells are automatically scrolled. Also if a cell partially visible is edited then first it is scrolled to the visible area.
Inside the edition mode, the following keys are used for a text field:
The cell will also leave the edition mode if the user clicked in another cell or in another control, then the value will be confirmed. When pressing Enter to confirm the value the focus goes to the cell bellow the current cell, if at the last line then the focus goes to the cell on the left. The value confirmation depends on the EDITION_CB callback return code.
When a mark mode is set the cells can be marked using mouse.
A marked cell will have its background attenuated to indicate that it is marked. A title cell appears marked only when MARKMODE=LIN, COL or LINCOL.
Cells can be selected individually or can be restricted to lines or columns. Also multiple cells can be marked simultaneously in continuous or in segmented areas. Lines and columns are marked only when the user clicks in their respective titles, if MARKMODE=CELL then all the cells of the line or column will be marked. Continuous areas are marked holding and dragging the mouse or holding the Shift key when clicking at the end of the area. Segmented areas are marked or unmarked holding the Ctrl key, the mark state is inverted. Clicking on the cell 0:0 will select all the items depending on MARKMODE, except for LINCOL.