Tutorial

Getting Started with Macros

Macro Editor

User Interface

Editing Macro Statements

Expression Editor

How To

Using variables

Finding and modifying objects

Creating new page content

Asking for user input

Sorting objects

Macro Logging

Sample Macros

Concepts

Expressions

Objects

Properties

Variables

Data Types

Arrays

Functions

Literals

Operators

Comments

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 provide it in the DialogBox_Create function:

DialogBox_Show(DialogBox_Create("Requested text was not found"))

Reference

Statements

ForEach

If

Else

While

Expression

Comment

Break

Continue

Hierarchy Objects

NotebookRoot

Notebook

SectionGroup

Section

Page

Page Objects

Title

Outline

Table

Column

Row

Cell

Paragraph

Text

Image

EmbeddedFile

Tag

Other Objects

DialogBox

Functions

Array Functions

Date/Time Functions

Dialog Box Functions

Macro Execution Functions

Object Functions

String Functions