The snap manager program uses a scripting language to define menu options. This can be customised as required. This page defines the user interface components (menus and dialog boxes) that can be used in scripts.
The functions Message, Ask, GetOpenFilename, and GetSaveFileName also run standard dialog boxes providing user interface components.
Constants
Variables
Function calls
Expressions
Statements
User defined functions
Menu items
Dialog boxes
System variables
Built-in functions
Regular expression syntax
Menu items are added to the snap manager menus to provide additional functionality. The menu item defines preconditions for the menu item to be valid, and actions to run if it is chosen. If the preconditions are not met the menu item will be greyed out and unavailable to the user.
Menu items are formatted as
menu_item menu_label description
requirements
statements
actions
statements
end_menu_item
Here menu_label is the label used in the menu for the item, and description is the description of the item. The label can define the main menu and sub-menus, each level is separated by a vertical bar character. For example "&Adjust|&Run" is the label for the Run item in the Adjust menu. Note that the & character is used to identify a shortcut key for the menu item .. it is not required.
The requirements and actions sections are effectively parameterless functions that are run by the menu item.
The requirements function is optional. It is run before the menu is displayed, and if it evaluates to false then the menu item is disabled. This is often a simple statement, for example:
requirements $job_valid
The actions function is required, and defines what happens when the menu item is selected
Menus can be deleted with the DeleteMenu function
The script can define dialog boxes to get input from the user. The syntax is
dialog title $variable buttons dialog_controls end_dialog
The dialog will be displayed with the specified title and controls, and with an Ok and Cancel button. When the user exits the variable will be set to true if the user pressed Ok, or false if the user pressed cancel. The variable can be omitted .. in this case the script will exit if the user presses cancel. If buttons is specified it can be one of "none", "ok", "cancel", "ok+cancel". The default is "ok+cancel".
Each dialog control defines an element that appears on the dialog, for example a text entry field, check box, or whatever. Most define a variable which will be used to populate the control when the dialog is started, and will hold the final value of the control when the dialog is closed.
Controls are organised vertically in the order that they are defined. The dialog can specify that a new column of controls is to be started, and that a new row of columns is to be started.
The dialog can include the following controls
label text
Write the label text on the dialog.
textbox $variable label specification
Defines a text field. The specification is optional and consists of a string organised as "width:height:validation", any part is optional. Width width of the text field in characters, height is the height (if more than one then the text box will accept multiple rows of text. Validation defines rules about data entry and is structured as ~chars~regexp~message, where ~ is any character, chars is a list of valid characters that may be entered into the list box, regexp is a regular expression defining valid entries, and message is a message that will be displayed if the data entered is invalid. Alternatively validation can be just "readonly", to specify that data may not be edited.
listbox $variable label valuelist options
Creates a list box selector for selecting one or more values from a list of strings. The valuelist is supplied as a strings separated by a delimiter. The first character of the string is used as the delimiter. When the dialog exits the selected strings are saved in the variable separated by the same delimiter. options can include one of "single", "multiple", and "extended". "single" permits selection of only one string at a time. "multiple" and "extended" allow more than one string, with "extended" allowing many strings to be selected easily. The default is "single". The options can also include a string widthxheight which specifies the width and height of the list box (in characters). An example of options would be "extended 50x15".
dropdown_selector $variable label options_list
Defines list from which a user can select a value. The options_list is a string organised as ~value1~display~value2~display2... where ~ is any character, value1, value2, ... are the values assigned to the variable, and display1, display2, ... are the corresponding options displayed to the user.
radio_selector $variable label options_list
Defines a set of radio button options from which the user can select a value. The options_list is a string organised as ~value1~display~value2~display2... where ~ is any character, value1, value2, ... are the values assigned to the variable, and display1, display2, ... are the corresponding options displayed to the user.
checkbox $variable label
Defines a check box that the user can select as true or false.
open_file_selector $variable label filter_list message
Adds a field for specifying the name of an existing file. The filter_list string defines wildcard file values and descriptions formatted as "Listing files (*.lst)|*.lst|All files (*.*)|*.*". The message is optional .. if it is included then the file name is required, and the corresponding message is displayed if it is not selected.
save_file_selector $variable label filter_list message
Adds a field for specifying the name of a new file to create. The filter_list string defines wildcard file values and descriptions formatted as "Listing files (*.lst)|*.lst|All files (*.*)|*.*". The message is optional .. if it is included then the file name is required, and the corresponding message is displayed if it is not selected.
button label statements
Places a button on the dialog. When the button is pressed the following statements are executed. These can use the values of the other dialog controls (that is, the values of the corresponding variables. If a return or exit statement is run, the dialog will close.
validator statements
The validator is not displayed on the dialog box, but when the dialog exits (if it is not cancelled), then the statements will be run. If they return a false value then the dialog will remain open. For example:
open_file_selector $filename "Select a command file" "Command files (*.snp)|*.snp"
validator
if not FileExists($filename) then
Message("You must choose a valid command file","Input error")
return false
endif
return true
spacer
Adds a spacer before the next control
new_column
Starts a new column of controls
new_row
Starts a new row of columns of controls