IupMatrix
Creates a matrix of alphanumeric fields. Therefore, all values of the matrix’s fields are strings. The matrix is not a grid container like many systems have. It inherits from IupCanvas.
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.
Parameters/Return
Ihandle* IupMatrix(char *action); [in C] iupmatrix{} -> (elem: iuplua_tag) [in IupLua3] iup.matrix{} -> (elem: iuplua_tag) [in IupLua5] matrix(action) [in LED]action: Name of the action generated when the user types something.
Returns the identifier of the created matrix, or NULL if an error occurs.
Attributes
Cell Attributes
Line and Column Attributes
Mark Attributes
Action Attributes
General Attributes
Callbacks
ACTION - Action generated when a keyboard event occurs.
BGCOLOR_CB - Action generated to retrieve the background color of a cell when it needs to be redrawn.
CLICK_CB - Action generated when any mouse button is pressed over a cell.
DROP_CB - Action generated to determine if a text field or a dropdown will be shown.
DROPCHECK_CB - Action generated to determine if a dropdown feedback should 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.
ENTERITEM_CB - Action generated when a matrix cell is selected, becoming the current cell.
FGCOLOR_CB - Action generated to retrieve the foreground color of a cell when it needs to be redrawn.
LEAVEITEM_CB - Action generated when a cell is no longer the current cell.
MOUSEMOVE_CB - Action generated to notify the application that the mouse has moved over the matrix.
SCROLL_CB - Action generated when the matrix’ visualization surface is changed.
VALUE_CB - Action generated to verify the value of a cell in the matrix when it needs to be redrawn.
VALUE_EDIT_CB - Action generated to notify the application that the value of a cell was changed.
Additional Functions in IupLua
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.
Notes
The IupMask control can be used to create a mask and filter the text entered by the user in each cell.
In Motif, when start editing a cell using a double click, the user must click again to the edit control get the focus.
Titles
A matrix might have titles for lines and columns. This must be defined before the matrix is mapped, and cannot be changed afterwards. A matrix will have line titles if, before it is mapped, an attribute of the “L:0” type is defined. It will have column titles if, before being mapped, an attribute of the “0:C” type is defined. The size of a line title is given by attribute “WIDTH0”, if it is defined. Otherwise, it is given by the size of the largest title defined when the matrix is mapped.
Titles (for lines or columns) can be generated with more that one text line. For such, the title value must contain a “\n”. The matrix does not by itself change the line’s height to fit titles with multiple lines. The user must change the line’s size manually, by using attribute HEIGHTn. In IUP’s size definition, a line with height 8 will fit one text line, a line with height 16 will fit two text lines, and so on.
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, the matrix never verifies attributes of type “%d:%d”. Therefore, it also does not verify line and column titles (which must be given by the callback). The result is that, at the moment the matrix is created, it resorts solely to the existence of attributes WIDTH0 and HEIGHT0 to find out if it will have line or column titles. That is, for such matrices to have titles, the WIDTH0 and HEIGHT0 attributes must be defined. This problem is not serious, because with IUP’s definition of SIZE, HEIGHT0=8 will always produce a column title in the size desired.
Another important reminder: if VALUE_CB is defined and VALUE_EDIT_CB is not, it is absolutely necessary that the application does not allow the user to edit any cell. This must be done by returning IUP_IGNORE in the IUP_EDITION_CB callback. (In the future, this will be done inside the matrix.)
Utility Functions
These functions can be used to help set and get attributes from the matrix:
void IupMatSetAttribute (Ihandle *n, char* a, int l, int c, char* v); void IupMatStoreAttribute(Ihandle *n, char* a, int l, int c, char* v); char* IupMatGetAttribute (Ihandle *n, char* a, int l, int c); int IupMatGetInt (Ihandle *n, char* a, int l, int c); float IupMatGetFloat (Ihandle *n, char* a, int l, int c); void IupMatSetfAttribute (Ihandle *n, char* a, int l, int c, 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 (n, "" , 30, 10, v) = IupSetAttribute(n, "30:10", v) IupMatSetAttribute (n, "BGCOLOR" , 30, 10, v) = IupSetAttribute(n, "BGCOLOR30:10", v) IupMatSetAttribute (n, "ALIGNMENT" , 10, 0, v) = IupSetAttribute(n, "ALIGNMENT10:0", v) (*)(*) noticed that in this case the second value will be ignored.
Navigation
Navigating through the matrix cells outside the edition mode is done by using the following keys:
- Arrows: Shift from the current cell to the next one, according to the arrow’s direction.
- Page Up and Page Down: Scroll a spreadsheet up or down one page.
- Home: Shifts from the current cell to the fist column in the line.
- Home Home: Shifts from the current cell to the upper left corner of the visible page.
- Home Home Home: Shifts form the current cell to the upper left corner of the first page of the matrix.
- End: Shifts from the current cell to the last column in the line.
- End End: Shifts from the current cell to the lower right corner of the visible page.
- End End End: Shifts from the current cell to the lower right corner of the last page in the matrix.
- Del: Deletes the contents of all selected cells.
Inside the edition mode, the following keys are used for a text field:
- Up and down arrows: Shift the current key, leaving the edition mode.
- Left and right arrows: If they are on the extremes of the text being edited, they shift the current key, leaving the edition mode.
- Ctrl + Arrows: Shift the current cell, leaving the edition mode.
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 Enter or Space is pressed, the current cell enters the edition mode. If Del is pressed, the whole contents of the cell will be deleted. Double-clicking a cell also enters the edition mode.
When the matrix is in the edition mode, to confirm the entered value, press Enter. By pressing Esc, the previous value is restored. If the cell leaves the edition mode for any other reason (for instance, the user shifted the current cell, or the user clicked in another control), the value will be confirmed. After 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.
Examples
Creates a simple matrix with the values and layout shown in the image below. There is also a menu that allows making some changes to the matrix.
