iupMask

IUP - Portable User Interface

iupMask

Functions to associate an input mask to a IupText or a IupMatrix element.

These functions are included in the Controls Library.

See the Pattern Specification for information on patterns.

Functions

int iupMaskSet(Ihandle *h, char *mask, int autofill, int casei);
int iupMaskMatSet(Ihandle *h, char *mask, int autofill, int casei, int lin, int col);

These functions are responsible for setting the mask to be used.

h: Ihandle of IupText or IupMatrix
mask: Mask to be used
autofill: When 1, turns the auto-fill mode on. In auto-fill mode, whenever possible, literal characters will be automatically added to the field
casei: When 1, uppercase or lowercase characters will be treated indistinctly 
lin, col
: Line and column numbers in the matrix

They return 1 if the mask is set, or 0 if there is an error (e.g., invalid mask).

int iupMaskSetInt(Ihandle *h, int autofill, int min, int max);
int iupMaskSetFloat(Ihandle *h, int autofill, float min, float max);
int iupMaskMatSetInt(Ihandle *h, int autofill, int min, int   max, int lin, int col);
int iupMaskMatSetFloat(Ihandle *h, int autofill, float min, float max, int lin, int col);

These functions set a mask that defines a limit to a number. Works only for integers and floats. Limitations: since the validation process is performed key by key, the user cannot type intermediate numbers (even inside the limit) if they are not following the mask rules.

h: Ihandle of IupText or IupMatrix
autofill: When 1, turns the auto-fill mode on. In auto-fill mode, whenever possible, literal characters will be automatically added to the field
min: Minimum value accepted in the field
max: Maximum value accepted in the field
lin, col: Line and column numbers in the matrix

They always return 1.

int iupMaskRemove(Ihandle *h);
int iupMaskMatRemove(Ihandle *h, int lin, int col);

These functions are responsible for removing the mask from the control.

h: Ihandle of IupText or IupMatrix
lin, col: Line and column numbers in the matrix

int iupMaskCheck (Ihandle *h);
int iupMaskMatCheck(Ihandle *h, int lin, int col);

These functions verify if what was typed by the user is valid for the defined mask.

h: Ihandle of IupText or IupMatrix
lin, col: Line and column numbers in the matrix

They return 1 if the text satisfies the mask, or 0 otherwise.

int iupMaskGet(Ihandle *h, char **val);
int iupMaskGetFloat(Ihandle *h, float *fval);
int iupMaskGetInt(Ihandle *h, int *ival);
int iupMaskMatGet(Ihandle *h, char **val, int lin, int col);
int iupMaskMatGetFloat(Ihandle *h, float  *fval, int lin, int col);
int iupMaskMatGetDouble(Ihandle *h, double *dval, int lin, int col);
int iupMaskMatGetInt(Ihandle *h, int *ival, int lin, int col);

These functions check if the text satisfies the mask, and they retrieve the fields value in only one call.

h: Ihandle of IupText or IupMatrix
val, fval, ival: Pointers used to complete the return value
lin, col: Line and column numbers in the matrix.

They return 1 if the text satisfies the mask, or 0 otherwise.

Callbacks

MATCH_CB: Action generated when the state of an item in the multiple selection list is changed. But it is called only when the interaction is over.

int function (Ihandle *self); [in C]
elem:match_cb() -> (ret: number) [in Lua]

This callback is called only when the text satisfies the mask.

Notes

IMPORTANT: The iupmaskSet functions will replace the application keyboard callback. The previous callback will be called only if the text satisfies the mask. So you must set the application callback prior to calling the iupmaskSet functions. When using IupSetAttribute, must also call IupSetFunction before setting the mask.

To make the use of masks simpler, the following predefined masks were created:

IUPMASK_FLOAT - Float number
IUPMASK_UFLOAT - Unsigned Float number
IUPMASK_EFLOAT - Float number with exponential notation
IUPMASK_INT - Integer number
IUPMASK_UINT - Unsigned Integer number

Examples

Browse Example Files