A number of dialog boxes can be triggered by commands within macro scripts. These may be used to get text or numerical information from a user, select a location to save a file, or to display a message to the user. These dialog box triggers are described in the following section.
MessageBox ( Message Text , Dialog Box Title )
The MessageBox command simply displays information to the user. The message text may take the form of pre-defined text or display a project variable or user variable's value.
SaveDialogBox ( Result Variable , Save Filter , Add Extension, Default Filename )
The SaveDialogBox command triggers a traditional Windows 'Save As' dialog box as pictured below. The user may navigate to a directory of choice and enter their desired filename. Once the Save button is clicked the resultant complete file path is stored in the Result Variable. This user variable can then be used as a input parameter for another procedure such as StartPrintToFile.
The Save Filter text indicates the file type that the user is saving and is displayed in the Save as type combobox. The Add Extension variable ensures that the extension entered is added onto the filename (if not already present).
EXAMPLE
SaveDialogBox(&HMSFile,"HEC-HMS Project (*.hms)",".hms","")
This example will bring up the save dialog box with HEC-HMS Project (*.hms) written in the Save as type combobox and will ensure the complete path that is saved to the user variable &HMSFile has the extension .hms.
InputBox ( Result Variable , User Prompt , Dialog Box Title , Default Text )
The InputBox command triggers a dialog box that request data from the user. If the user chooses the Cancel button, the Default Text is stored in the Result Variable. If the user chooses the OK button, the user entered text is stored in the Result Variable.
A InputBox should be used when the script author wishes to use a default value when the user chooses the Cancel button (or presses Esc) to exit the dialog. If the script should abort when Cancel is selected then the InputQueryBox should be used instead.
InputQueryBox ( Result Variable , User Prompt , Dialog Box Title , Default Text )
The InputQueryBox operates similarly to the InputBox, however, selecting Cancel in an InputQueryBox will abort the script operation whereas this action will simply store the default text in the Result Variable in the case of an InputBox.
YesNoBox ( Result Variable , User Prompt , Dialog Box Title )
The YesNoBox command triggers a dialog box that presents the user with a yes or no button in response to a User Prompt message. If the user selects the Yes button then 'True' is stored in the Result Variable otherwise 'False' is stored in the Result Variable.
Progress Bar
SetupProgressBar ( Description , NumberOfSteps )
UpdateProgressBar ( )
CloseProgressBar ( )
The 3 procedures listed above govern the use of the progress bar which can be used to report the progress of long processes such as complex loops. SetupProgressBar initiates the progress bar and sets the description. The NumberOfSteps variable is the number times the UpdateProgressBar command is expected to be called before the progress bar should show 100%. CloseProgressBar should be called after the process is finished.
EXAMPLE
SetupProgressBar("Processing Subcatchments",%Catchment.NumberOfSubCatchments)
LOOP(i|1|%Catchment.NumberOfSubCatchments|
{Time Consuming functions here}
UpdateProgressBar()
)
CloseProgressBar()
Check List Box
SetupCheckListBox ( Description , Title )
AddCheckListBoxItem ( Item Description , Item Checked)
DisplayCheckListBox ( Array Type User Variable )
The 3 procedures listed above govern the use of Check List Boxes in CST Macro Scripts. SetupCheckListBox initiates the checklist box and sets the description label and title. AddCheckListBoxItem can be called any number of times to add an item (Item Description) and check or do not check the associated check box in accordance with the True / False type variable in Item Checked. DisplayCheckListBox designated the end of addition of items and will display the Check List Box. After the user selects OK the Item Description(s) that were checked are stored in the Array Type User Variable.
EXAMPLE
SetupCheckListBox("Description","Title")
AddCheckListBoxItem("Item 1",True)
AddCheckListBoxItem("Item 2",False)
AddCheckListBoxItem("Item 3",True)
DisplayCheckListBox(&ArrayCLBResults)
This example was the code used to generate the screen capture illustrated above. The DisplayCheckListBox procedure would have created the array variable &ArrayCLBResults, set its length to two and stored Item 1 and Item 2 in the array since these were the items that were checked. However, the user could have changed the items that were checked before clicking OK and this would effect the length and content of the &ArrayCLBResults array variable.
ComboBox
SetupComboBox ( Description , Title )
AddComboBoxItem ( Item Description , Default Item)
DisplayComboBox (User Variable )
The 3 procedures listed above govern the use of ComboBoxes in CST Macro Scripts. SetupComboBox initiates the checklist box and sets the description label and title. AddComboBoxItem can be called any number of times to add an item (Item Description) and designate if it should be the default item (ie., only one item should have this labelled as True). DisplayComboBox designated the end of addition of items and will display the ComboBox. After the user selects OK the Item Description that was selected is stored in the user variable.
EXAMPLE
SetupComboBox("Select your option","Combo Title")
AddComboBoxItem("Item 1",False)
AddComboBoxItem("Item 2",True)
AddComboBoxItem("Item 3",False)
DisplayComboBox(&Result)
This example was the code used to generate the screen capture illustrated above.
Radio Group
SetupRadioGroup ( Description , Title )
AddRadioButton ( Item Description , Default Item)
DisplayRadioGroup (User Variable )
The 3 procedures listed above govern the use of the Radio Group in CST Macro Scripts. SetupRadioGroup initiates the checklist box and sets the description label and title. AddRadioButton can be called any number of times to add an item (Item Description) and designate if it should be the default item (ie., only one item should have this labelled as True). DisplayRadioGroup designated the end of addition of items and will display the Radio Group. After the user selects OK the Item Description that was selected is stored in the user variable.
EXAMPLE
SetupRadioGroup("Radio Group Title","Form Title")
AddRadioButton("Line 1",True)
AddRadioButton("Line 2",False)
AddRadioButton("Line 3",False)
DisplayRadioGroup(&Answer)
This example was the code used to generate the screen capture illustrated above.
The radio group operates similarly to the ComboBox dialog. In general, the ComboBox should be used when selecting between a large number of options whereas the Radio Group may be more appropriate for a small number of options.
ImageBox ( Result Variable , User Prompt , Dialog Box Title , Default Text, DoResize, ImagePath )
The ImageBox operates similarly to the InputBox, however, a picture (specified by ImagePath) is displayed to the user. If DoResize is True then the image will be scaled to the size of the form, otherwise the form will be scaled to the size of the form.
