option_add

option_add adds an option to the Tools=>More Options dialog box. The option data is saved in the Windows registry or an INI file.

bool = option_add(ssCategory, ssName, ssSection, ssKey, ssDefault, ssDataType, ssHelpText, ssType)

Return Value

bool is TRUE (1) if the functions was successful and otherwise FALSE (0).

Parameters

ssCategory

ssCategory is the category name displayed in the left list box control of the option dialog box. If the category does not exits it will be added to the list.

ssName

ssName is the option name displayed in the left column of the right list box.

ssSection

ssSection is the section name used to save the data in the Windows registry or INI file. See also WriteProfileString and WriteProfileInt.

ssKey

ssKey is the key name used to save the data in the Windows registry or INI file. See also WriteProfileString and WriteProfileInt.

ssDefault

ssDefault is the default value (alwasy a string even for integer values.) This value is used if the value does not exists in the Windows registry.

ssDataType

ssDataType is the string “string” or “int”.

ssHelpText

ssHelpText is the Help text displayed int the text box at the bottom of the dialog box.

ssType

ssType is the option type or a type string with a callback function name. ssType can be one the following values:

edit	Edit control (no callback function)
checkbox	Check box (no callback function)
buttonedit	Edit control with button. If a callback function is necessary it can be added to the type value as following: “buttonedit@_opt_my_callback”
buttonstatic	Text with button. A callback function must be specified.
combo	Combo Listbox control. A callback function must be specified.

Callback function parameter list:

def callback(svInit, iControl, iRow, iCol)
{
    // svInit: Vektor with the contents of all dialogbox controls.
    // iControl: Index of the control
    // iRow: Row index in the list control
    // iCol: Column index in the list contol
    return val;
}

The function returns a scalar sting.

Example

Example for a combo box callback function:

def __opt_ncfiletype(svInit, iControl, iRow, iCol)
{
    svValue = ["netCDF","netCDF (PC-Byteorder)","netCDF-up","netCDF-up (compressed)"]
    if (nargsin() == 2) {
        if (iControl == 1) {
            idx = strtod(svInit[1])+1;
            if (idx[1] >= 1 && idx[1] <= len(svValue)) {
                return svValue[idx];
            }
            return svValue[1];
        } else if (iControl == 2) {
            return sprintf("%d", find(svInit[1] == svValue)-1);
        } else {
            return TRUE;
        }
    }
    <ssMat, svSel> = GetListBoxText(svInit[iControl], FALSE);
    smMat = ReportControl_GetMatrix(ssMat);
    return CreateListBoxText(svValue, smMat[iRow; iCol]);
}
ssHelp = _s("Specifies the type of the netCDF file.\n\n" + ....
            "netCDF: Standard netCDF File\n" + ....
            "netCDF (PC-Byte order): netCDF file with little-endian byte order\n" + ....
            "netCDF-up: New file format for data files (UniPlot 5.6).\n" + ....
            "netCDF-up (compressed): Same as netCDF-up, but with better compression (a bit slower)\n\n" + ....
            "Find more information in the help system: \"Overview netCDF Files\"");
option_add(_s("Import and Data Browser"), ..
    _s("netCDF Filetype"), ..
    "Settings", "standard-netcdf-files", "1", "int", ..
    ssHelp, "combo@__opt_ncfiletype");

Example for a button callback function to select a path name:

// Die Option kann wie folgt in Ihrem Skript erfragt werden:
// ssPath = GetProfileString("Settings", "My-directory");

def __opt_my_directory(svInit, iControl, iRow, iCol)
{
    if (nargsin() == 2) {
       ssDir = svInit[1];
       if (iControl == 3) {
          if (ssDir == "") {
             return TRUE;
          }
          nAttrib = GetDirectoryWriteAccess(ssDir);
          if (nAttrib == -1) {
             return sprintf(_s("The directory \"%s\" does not exist."), ssDir);
          } else if (nAttrib == 0) {
             return sprintf(_s("The directory \"%s\" is write protected."), ssDir);
          }
          return TRUE;
       }
       if (ssDir == "") {
          return "";
       }
       return _MakePathComplete(ssDir);
    }

    <smMat, smSel, rmSelRow> = ReportControl_GetMatrix(svInit[iControl]);
    ssDir = GetDirectoryDialog(smMat[iRow; iCol]);
    if (ssDir == "DLG_CANCEL") {
       return svInit;
    }
    nAttrib = GetDirectoryWriteAccess(ssDir);
    if (nAttrib == -1) {
       MessageBoxError(_s("The directory \"%s\" does not exist."), ssDir);
       return FALSE;
    } else if (nAttrib == 0) {
       MessageBoxError(_s("The directory \"%s\" is write protected."), ssDir);
       return FALSE;
    }
    smMat[iRow; iCol] = ssDir;
    svInit[iControl] = ReportControl_GetInit(smMat, TRUE, rmSelRow);
    return svInit;
 }

Option_AddCategory("My Options");

ssHelp = "Please choose the directory.\n" + ....
            "The directory should contain Excel files";
option_add("My Options", ..
    "My directory", ..
    "Settings", "My-directory", "", "string", ..
    ssHelp, "buttonstatic@__opt_my_directory");

Comment

The function is written in UniScript. The source code is found in the file script\uniplot\tools-options.ic.

History

Version	Description
5.6.0	New

See also

Overview Application Object, Tools=>More Options, GetProfileString, GetProfileInt, WriteProfileString, WriteProfileInt

_id-783960