Tutorial

Getting Started with Macros

Macro Editor

User Interface

Menus and Toolbar

Editing Macro Statements

Expression Editor

Macro Debugging

How To

Using variables

Finding and modifying objects

Creating new page content

Asking for user input

Storing persistent data

Using binary data

Sorting objects

Macro menus

Bulleted and numbered lists

Sample Macros

Concepts

Expressions

Objects

Properties

Variables

Data Types

Arrays

Functions

Literals

Operators

Comments

Last updated on: March 19, 2023
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:

User Prompt

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")
Message Box

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.

Task Dialog

See ShowTaskDialog API for example usage.

Reference

Statements

For

ForEach

If

Else If

Else

Switch

Case

Default

While

Expression

Comment

Break

Continue

Return

Hierarchy Objects

NotebookRoot

Notebook

SectionGroup

Section

Page

Page Objects

Title

Outline

Table

Column

Row

Cell

Paragraph

Text

Image

EmbeddedFile

Tag

Other Objects

DialogBox

MacroMenu

Window

Functions

Array Functions

Color Functions

Data Store Functions

Date/Time Functions

Dialog Box Functions

Macro Execution Functions

Macro Menu Functions

Object Functions

String Functions

Window Functions