IupGetParam
8
IupGetParam
@serial = 809
dialog
Description
Shows a modal dialog for capturing parameter values using several types of controls.
Include
iup.e
Namespace
iup
Signature
public function IupGetParam(object title = NULL, atom action, atom user_data, sequence param_data = {})
Creation
title: dialog title. action: user callback to be called whenever a parameter value was changed, and when the user pressed the OK button. It can be NULL. user_data: user pointer passed to the user callback. format: string describing all the parameters, see Notes. ...: list of variables address with initial values for the parameters.
Returns: a status code 1 if the button 1 was pressed, 0 if the button 2 was pressed or if an error occurred.
The function will abort if there are errors in the format string as in the number of the expected parameters.
Callback
int function(Ihandle* dialog, int param_index, void* user_data); [in C] luafunction(dialog: ihandle, param_index: number) -> (ret: number) [in Lua]
dialog: dialog handle param_index: current parameter being changed. Can have negative values to indicate specific situations: IUP_GETPARAM_BUTTON1 (-1) = if the user pressed the button 1; IUP_GETPARAM_INIT (-2) = after the dialog is mapped and just before it is shown. Not called for IupParamBox; IUP_GETPARAM_BUTTON2 (-3) = if the user pressed the button 2; IUP_GETPARAM_BUTTON3 (-4) = if the user pressed the button 3, if any; IUP_GETPARAM_CLOSE (-5) = if the user clicked on the dialog close button. Not called for IupParamBox; (since 3.13) user_data: a user pointer that is passed in the function call.
Returns: You can reject the change or the button action by returning 0 in the callback, otherwise you must return 1. By default button 1 and button2 will close the dialog.
Internally the callback is stored as a regular callback with the "PARAM_CB" name.
You should not programmatically change the current parameter value during the callback. On the other hand you can freely change the value of other parameters.
Use the dialog attribute "PARAMn" to get the parameter "Ihandle*", where "n" is the parameter index in the order they are specified starting at 0, but separators and button names are not counted. Notice that this is not the actual control, use the parameter attribute "CONTROL" to get the actual control. For example: Ihandle* param2 = (Ihandle*)IupGetAttribute(dialog, "PARAM2"); int value2 = IupGetInt(param2, IUP_VALUE);
Ihandle* param5 = (Ihandle*)IupGetAttribute(dialog, "PARAM5"); Ihandle* ctrl5 = (Ihandle*)IupGetAttribute(param5, "CONTROL");
if (value2 == 0) { IupSetAttribute(param5, IUP_VALUE, "New Value"); IupSetAttribute(ctrl5, IUP_VALUE, "New Value"); }
Since parameters are user controls and not real controls, you must update the control value and the parameter value.
Be aware that programmatically changes are not filtered. The valuator, when available, can be retrieved using the parameter attribute "AUXCONTROL". The valuator is not automatically updated when the text box is changed programmatically. The parameter label is also available using the parameter attribute "LABEL".
Attribute
(Inside the callback) For the dialog:
"PARAMn" - returns an IUP Ihandle* representing the nth parameter, indexed by the declaration order, not counting separators or button names. "BUTTON1" - returns an IUP Ihandle*, the button 1. "BUTTON2" - returns an IUP Ihandle*, the button 2. "BUTTON3" - returns an IUP Ihandle*, the button 3.
For a parameter:
"LABEL" - returns an IUP Ihandle*, the label associated with the parameter. "CONTROL" - returns an IUP Ihandle*, the real control associated with the parameter. "AUXCONTROL" - returns an IUP Ihandle*, the auxiliary control associated with the parameter (only for Valuators). "INDEX" - returns an integer value associated with the parameter index. IupGetInt can also be used. "VALUE" - returns the value of the parameter. IupGetFloat and IupGetInt can also be used. For the current parameter inside the callback contains the new value that will be applied to the control, to get the old value use the VALUE attribute for the CONTROL returned Ihandle*.
In Lua, to retrieve a parameter you must use the following function: iup.GetParamParam(dialog: ihandle, param_index: number)-> (param: ihandle) [in Lua]
dialog: Identifier of the dialog. param_index: parameter to be retrieved.
In Lua, to retrieve a parameter control, auxiliary control or button you must use the following function: iup.GetParamHandle(param: ihandle, name: string)-> (control: ihandle) [in Lua] (since 3.16)
param: Identifier of the parameter. name: name of the parameter.
Notes
The format string must have the following format, notice the "\n" at the end
"text%x[extra]{tip}\n", where:
text is a descriptive text, to be placed to the left of the entry field in a label. It can contains any string, but to contain a '%' must use two characters "%%" to avoid conflict with the type separator (since 3.6). If it is preceded by n '\t' characters then the parameter will be indented by the same number (since 3.13).
x is the type of the parameter. The valid options are:
b = boolean (shows a True/False toggle, use "int" in C) i = integer (shows a integer number filtered text box, use "int" in C) r = real (shows a real number filtered text box, use "float" in C) R = same as r but using "double" in C (since 3.11.1) a = angle in degrees (shows a real number filtered text box and a dial [if IupControlsOpen were called], use "float" in C) A = same as a but using "double" in C (since 3.11.1) s = string (shows a text box, use "char*" in C, it must have room enough for your string) m = multiline string (shows a multiline text box, use "char*" in C, it must have room enough for your string) l = list (shows a dropdown list box, use "int" in C for the zero based item index selected) o = list (shows a list of toggles inside a radio, use "int" in C for the zero based item index selected) (since 3.3) t = separator (shows a horizontal line separator label, in this case text can be an empty string, not included in parameter count) f = string (same as s, but also show a button to open a file selection dialog box) c = string (same as s, but also show a color button to open a color selection dialog box) n = string (same as s, but also show a font button to open a font selection dialog box) (since 3.3) h = Ihandle* (a control handle that will be managed by the application, it will be place after the parameters and before the buttons.) (since 3.9) u = buttons titles (allow to redefine the default button titles (OK and Cancel), and to add a third button, use [button1,button2,button3] as extra data, can omit one of them, it will use the default name, not included in parameter count) (since 3.1)
extra is one or more additional options for the given type
[min,max,step] are optional limits for integer and real types. The max and step values can be omitted. When min and max are specified a valuator will also be added to change the value. To specify step, max must be also specified. step is the size of the increment. [false,true] are optional strings for boolean types to be displayed after the toggle. The strings can not have commas ',', nor brackets '[' or ']'. mask is an optional mask for the string and multiline types. The dialog uses the MASK attribute internally. In this case we do no use the brackets '[' and ']' to avoid conflict with the specified mask.
item0 | item1 | item2,... | are the items of the list. At least one item must exist. Again the brackets are not used to increase the possibilities for the strings, instead you must use ' | '. Items index are zero based start. [dialogtype | filter | directory | nochangedir | nooverwriteprompt] are the respective attribute values passed to the IupFileDlg control when activated. All ' | ' must exist, but you can let empty values to use the default values. No mask can be set. |
tip is a string that is displayed in a TIP for the main control of the parameter. (since 3.0)
The number of lines in the format string (number of '\n') will determine the number of required parameters. But separators will not count as parameters. There is no maximum number of parameters (since 3.13).
A integer parameter always has a spin attached to the text to increment and decrement the value. A real parameter only has a spin in a full interval is defined (min and max), in this case the default step is (max-min)/20. When the callback is called because a spin was activated then the attribute "SPINNING" of the dialog will be defined to a non NULL and non zero value.
The default precision for real value display is given by the global attribute DEFAULTPRECISION. But inside the callback the application can set the param attribute "PRECISION" to use another value. It will work only during interactive changes. The decimal symbol will used the DEFAULTDECIMALSYMBOL global attribute. (since 3.13)
The function does not allocate memory space to store the text entered by the user. Therefore, the string parameter must be large enough to contain the user input. If you want to set a maximum size for the string you can set the param attribute MAXSTR, inside the callback when param_index=IUP_GETPARAM_INIT (since 3.6). Its default value is 10240 for multiline strings, 4096 for file names, and 512 for other strings.
There is no extra parameters for the color string. The mask is automatically set to capture 3 or 4 unsigned integers from 0 to 255 (R G B) or (R G B A) (alpha is optional).
The dialog is resizable if it contains a string, a multiline string or a number with a valuator. All the multiline strings will increase size equally in both directions.
When the "s" type is used the size can be controlled using the VISIBLECOLUMNS attribute at the param element. (since 3.16)
The dialog uses a global attribute called "PARENTDIALOG" as the parent dialog if it is defined. It also uses a global attribute called "ICON" as the dialog icon if it is defined. utility = Both functions bellow are used internally in IupGetParam. But they can be used to integrate the IupGetParam contents in other dialogs. Ihandle* IupParamf(const char* format); [in C] iup.Paramf(format: string) -> elem: ihandle [in Lua]
Creates an IupUser element to be used in the IupParamBox bellow. Each parameter format follows the same specifications as the IupGetParam function, including the line feed.
The IupUser element can be directly used if the internal attributes are set. Here are the respective attributes according to the IupGetParam format specification:
TITLE: text of the parameter, used as label. INDENT: number of indentation levels.
TYPE: can be BOOLEAN, LIST, OPTIONS, REAL, STRING, INTEGER, FILE, COLOR, SEPARATOR, BUTTONNAMES and HANDLE. And describe the type of the parameter. DATATYPE: can be INT (int), FLOAT (float), DOUBLE (double), STRING (char*), HANDLE (Ihandle*) or NONE (when buttons and separators are used). And describe the C data type that must be passed to IupGetParam to initialize and receive parameter values. MULTILINE: can be Yes or No. Defines if the edit box can have more than one line. ANGLE: can be Yes or No. defines if the REAL type is an angle.
TRUE, FALSE: boolean names. INTERVAL (Yes/No), MIN, MAX, STEP, PARTIAL (Yes/No): optional limits for integer and real types. DIALOGTYPE, FILTER, DIRECTORY, NOCHANGEDIR, NOOVERWRITEPROMPT: used for the FILE parameter dialog. See IupFileDlg. BUTTON1, BUTTON2, BUTTON3: button titles. Default is "OK/Cancel/Help" for regular IupGetParam, and "Apply/Reset/Help" for IupParamBox. 0, 1, 2, 3, ... : list items. MASK: mask for the edit box input.
TIP: text of the tip.
VALUE: the parameter value. STATUS: set to 1 when button1 is activated, and set to 0 when button2 is activated or the dialog close button is clicked. Ihandle* IupParamBox(Ihandle* parent, Ihandle params, int count); [in C]
Creates the IupGetParam dialog contents with the array of parameters. This includes the button box at the bottom.
The buttons of the button box can be retrieved using the BUTTON1, BUTTON2, BUTTON3 attribute at the button box. They will directly return the control handle not the button titles as in a IupParamf.
The PARAM_CB callback will receive the box handle instead of the IupGetParam dialog handle. Buttons 1 and 2 will still close the dialog as in IupGetParam (by returning IUP_CLOSE internally), so to change that behavior return 0 in the callback. The USERDATA attribute will hold the user data passed to the callback.
The PARAMCOUNT attribute contains the number of parameters not counting separators and button names.
Example
'c' example shown
Here is an example showing many of the possible parameters. We show only one for each type, but you can have as many parameters of the same type you want.
int pboolean = 1; int pinteger = 3456; float preal = 3.543f; int pinteger2 = 192; float preal2 = 0.5f; float pangle = 90; char pstring[100] = "string text"; char pfont[100] = "Courier, 24"; char pcolor[100] = "255 0 128"; int plist = 2, poptions = 1; char pstring2[200] = "second text\nsecond line"; char file_name[500] = "test.jpg"; if (!IupGetParam("Title", param_action, 0, "Bt %u[, MyCancel, Help!]\n" "Boolean: %b[No,Yes]\n" "Integer: %i\n" "Real 1: %r\n" "Sep1 %t\n" "Integer: %i[0,255]\n" "Real 2: %r[-1.5,1.5,0.05]\n" "Sep2 %t\n" "Angle: %a[0,360]\n" "String: %s\n" "Options: %o|item0|item1|item2|\n" "List: %l|item0|item1|item2|item3|item4|item5|item6|\n" "File: %f[OPEN|*.bmp;*.jpg|CURRENT|NO|NO]\n" "Color: %c{Color Tip}\n" "Font: %n\n" "Sep3 %t\n" "Multiline: %m\n", &pboolean, &pinteger, &preal, &pinteger2, &preal2, &pangle, pstring, &poptions, &plist, file_name, pcolor, pfont, pstring2, NULL)) return;
See Also
IupFileDlg | IupMessageDlg | IupFontDlg | IupProgressDlg | IupAlarm | IupGetFile | IupGetColor | IupGetParam | IupGetText | IupListDialog | IupMessage | IupScanf | IupLayoutDialog | IupElementPropertiesDialog |
Not Categorized, Please Help
|