Definition: |
include pGUI.e
sequence res = IupGetParam(string title, cbfunc action, atom user_data, string fmt, sequence param_data={}) |
Description: |
Shows a modal dialog for capturing parameter values using several types of controls.
title: dialog title. action: 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. fmt: string describing all the parameters, see Notes. param_data: list of initial values for the parameters. Returns: args plus a status code 1 in res[$] if the button 1 was pressed, 0 if the button 2 was pressed or if an error occurred. IupGetParam should now be used instead of IupScanf. |
Notes: |
The function will abort if there are errors in the format string such as the number of parameters.
The format string must have the following format, notice the "\n" at the end "text%x[extra]{tip}\n", where:
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. 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. Its default value is 10240 for multiline strings, 4096 for file names, and 512 for other strings. [Phix: The above sizes are hard coded but otherwise easily modified. If you need your app to be robust, you must implement that callback.] There are 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. Note that IupGetParam is quietly ignored by Edix/Tools/Layout Designer - instead I might suggest making a copy of demo/pGUI/getparam.exw (as reproduced below) to experiment with the layout or construct the first draft of the dialog, and to do so all directly on the plain text source. |
Utility Functions: |
Both functions bellow are used internally in IupGetParam. But they can be used to integrate the IupGetParam contents in other dialogs.
Ihandle ih = IupParamf(const char* format); 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:
Ihandle ih = IupParamBox(Ihandle parent, Ihandles params, int count) 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. |
Attributes: | (inside the callback) For the dialog: |
Attributes: |
(inside the callback) For a parameter:
|
Callbacks: |
function param_cb(Ihandle dialog, integer param_index, atom pUserData) dialog: dialog handle param_index: current parameter being changed. Can have negative values to indicate specific situations:
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 = IupGetAttributeHandle(dialog, "PARAM2") int value2 = IupGetInt(param2, IUP_VALUE) Ihandle param5 = IupGetAttributeHandle(dialog, "PARAM5") Ihandle ctrl5 = IupGetAttributeHandle(param5, "CONTROL") if value2 == 0 then IupSetAttribute(param5, IUP_VALUE, "New Value") IupSetAttribute(ctrl5, IUP_VALUE, "New Value") end if 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". |
Example: |
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.
-- -- demo\pGUI\getparams.exw -- include pGUI.e IupOpen() integer pboolean = 1; integer pinteger = 3456; atom preal = 3.543 integer pinteger2 = 192; atom preal2 = 0.5; atom pangle = 90; string pstring = "string text"; integer poptions = 1, plist = 2 string file_name = "test.jpg"; string pcolor = "255 0 128"; string pfont = "Courier, 24"; string pstring2 = "second text\nsecond line"; constant fmt=""" _____________Boolean: %b[No,Yes] Integer: %i Real 1: %r Sep1 %t Integer2: %i[0,255] Real 2: %r[-1.5,1.5,0.05] Sep2 %t Angle: %a[0,360] String: %s Sep3 %t Options: %o|item0|item1|item2| List: %l|item0|item1|item2|item3|item4|item5|item6| Sep4 %t File: %f[OPEN|*.bmp;*.jpg|CURRENT|NO|NO] Color: %c{Color Tip} Font: %n Sep5 %t Multiline: %m Bt %u[, MyCancel, Help!] """ IupOpen() sequence res = IupGetParam("Title", NULL, 0, fmt, {pboolean, pinteger, preal, -- (sep1) pinteger2, preal2, -- (sep2) pangle, pstring, -- (sep3) poptions, plist, -- (sep4) file, pcolor, pfont, -- (sep5) pstring2}) string msg = "" for i=1 to length(res) do msg &= sprint(res[i])&'\n' end for IupShow(IupDialog(NULL)) -- show an empty dialog [otherwise IupMessage fails, fixed in SVN] IupMessage("results",msg) IupClose() (I have added a couple of separators not shown on the following image) ![]() |
See Also: | IupGetColor, IupValuator, IupDial, IupList, IupFileDlg |