Onetastic Macro Documentation >
Asking for user input
Asking for user input
You can ask user for input during macro execution to modify behavior of the macro or
you can display a message box to the user. For instance if you are building a macro
that will search for some text (e.g. Search & Replace) you may ask the user for the
search term or use a message box to display the number of words in a Word Count macro.
To do so, you can use . Following demonstrates an example:
$dialog_box = DialogBox_Create("")
DialogBox_AddTextBox($dialog_box, "&Find what", "Search", "", false)
DialogBox_AddTextBox($dialog_box, "&Replace with", "Replace", "", true)
$Options = Array("Current page", "Current section", "Current notebook")
DialogBox_AddDropDown($dialog_box, "&Scope", "Scope", "Current section", $Options)
DialogBox_AddCheckBox($dialog_box, "Match &case", "MatchCase", false)
$Search = $dialog_box.controls["Search"]
This is part of the Search & Replace macro and it will display the following dialog box:
Here the DialogBox_Create function creates a new dialog box object. Then we
add some controls to it. Text boxes, drop down controls
and check boxes can be added. Finally DialogBox_Show function
displays the dialog box.
Labels for the controls
Here we are adding some labels to each of these controls. "Find what", "Replace with"
and "Scope" are displayed to the left of the text box and drop down controls. "Match case"
is displayed to the right of the check box control. The ampersand (&) character specifies
the shortcut key for the corresponding control. For instance Alt+F in the dialog will focus
on the "Find what" text box, Alt+R will focus on the "Replace with" text box and so on.
Providing possible values
For drop down controls, you can specify a set of possible values in the form of an array
Providing initial values
You can provide an initial value to each of these controls. An initial value for the
text box will show as text in the text box as string. An intial value for the drop down control
must be one of the provided possible values and will show as the selected value for it.
An initial value for a check box must be a bool value, true for checked and false for
Making text boxes required
You can make a text box required, such that the user cannot leave it empty. For instance
in this dialog above, the "Find what" text box is made required, by providing false on the last
parameter. If user leaves it empty the OK button on the dialog will remain disabled.
Reading the values the user has provided
The values the user has provided in the dialog box is being stored in the "controls" member
of the dialog box object. This member will be empty until the DialogBox_Show
function is called and after that it will be an array that contains the values provided by the user
If you wish to only display a message, you can use ShowMessage function:
ShowMessage("No instances of the search term is found")
If you want user to pick form a few actions and no other input is required, a task dialog may be
a suitable option.
See ShowTaskDialog API for example usage.