Tutorial

Last updated on: September 02, 2024
Also available as a single HTML file

Onetastic Macro Documentation > How To > 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 Dialog Box functions. Following demonstrates an example:

// Create a new dialog box $dialog_box = DialogBox_Create("") // Now add some controls // Text box with label "Find what", stored at $dialog_box.controls["Search"], // initial value empty string ("") and it is NOT OK for user to leave it empty DialogBox_AddTextBox($dialog_box, "&Find what", "Search", "", false) // Text box with label "Replace with", stored at $dialog_box.controls["Replace"], // initial value empty string ("") and it is OK for user to leave it empty DialogBox_AddTextBox($dialog_box, "&Replace with", "Replace", "", true) // Drop down with label "Scope", stored at $dialog_box.controls["Scope"], // initial value of "Current section" with a two other possible options $Options = Array("Current page", "Current section", "Current notebook") DialogBox_AddDropDown($dialog_box, "&Scope", "Scope", "Current section", $Options) // Check box with label "Match case", stored at $dialog_box.controls["MatchCase"], // initially unchecked (false) DialogBox_AddCheckBox($dialog_box, "Match &case", "MatchCase", false) // Now show the dialog box DialogBox_Show($dialog_box) // We can now use the values for the controls using $dialog_box.controls $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 of strings.

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 unchecked.

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

Displaying messages

If you wish to only display a message, you can use ShowMessage function:

ShowMessage("No instances of the search term is found")

Task dialogs

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.