HOW TO DEFINE AND USE MACROS

Define and Use Macros

INTRODUCTION
Advanced users of EnSight often find themselves performing repetitive tasks. EnSight’s macro facility lets you save a
sequence of commands and then assign a keyboard key to those commands such that they are executed when the
key is pressed.
Pressing a key assigned to a macro causes the associated command file to be read and executed. Depending on
how it is set up, a macro can execute it’s file in one of three ways:
1. The command file is executed once for each key press. This mode is useful for one-time operations such as cut-
ting flipbook animation on/off or saving an image.
2. The command file repeatedly executes as long as the key is held down. This is useful for operations that are con-
tinuous in nature, such as rotating around the Y axis by 5 degrees.
3. Multiple command files execute in a cycle for each keystroke.
Keystroke macros are defined in a text file, macro.define. Macros can be defined at a site or local level, with local
macros overriding site macros that might be defined for the same key. The macro.define file (if any) that resides
in the %CEI_HOME%/ensight100/site_preferences/macros directory defines site-level macros, while the
macro.define file (if any) under the user’s EnSight defaults directory (located at
%HOMEDRIVE%%HOMEPATH%\(username)\.ensight100 commonly located at C:\Users\username\.ensight100 on
Vista and Win7, C:\Documents and Settings\yourusername\.ensight100 on older Windows, and ~/.ensight100 on
Linux, and in ~/Library/Application Support/EnSight100 on the Mac) will define that user’s local macros. Any
command files referenced by macros must be located in these directories as well.
Most of the functions needed to define and edit macros can be found under the Macros tab of the Command Dialog
(File > Command from the Main Menu).

BASIC OPERATION
Creating Macro Command Files
The first step in creating macros is to save the various command sequences that perform the desired actions. This
can be done in several ways.

One way to save commands for a macro is to save off a command file from an Ensight session. See How To Record
and Play Command Files for more information. Be careful as you perform the operations that are saved to the
command file. Superfluous or errant commands will slow down macro operation or cause errors. You may wish to
view the resulting command files with a text editor and possibly make changes.

A second way to create the command file for a macro is to copy commands from the Command Dialog history
window:
1. Mark the desired commands by clicking
and dragging in the history window, or by
any combination of clicking and dragging
while holding down the CTRL key.

2. With the cursor over the marked

commands, click the right mouse button to
bring up the action menu, then select
"Copy".
This will copy the commands to the system
clipboard.

3. Bring up a text editor and insert the

commands using "Paste".

4. When you are finished building your

macro command file, be sure you save it in
the site or local macros directory (see
above).

Page 403
 HOW TO DEFINE AND USE MACROS

A third way to create a macro command file is by writing/appending them directly to a file from the Command Dialog
history window:
1. Mark the desired commands by clicking
and dragging in the history window, or by
any combination of clicking and dragging
while holding down the CTRL key.

2. With the cursor over the marked

commands, click the right mouse button
to bring up the action menu, then select
"Write/append" to file.

3. A File Selection dialog opens. Select or

enter the desired file to save commands
to and click Save. If the file already exists,
the selected commands will be appended,
if it does not, it will be created with the
selected commands.

Linking macro command files to keys

To link a command file in the macros directory to a key or mouse button:

1. In the Command Dialog "Macros" tab (File >

Command from the Main Menu), click "New".

The New Macro dialog opens.

2. Select or type a key,

3. Check "Repeatable" if you want the macro to

be repeated while the key is held down.

4. Select any modifier keys such as CTRL or

ALT.

5. Enter a brief description of what the macro

does.

6. Click "Add" to add a command file for the

macro.

6. OR click “Add Menu” to add the functionality

from an existing EnSight menu to the macro.

A File Selection dialog opens.

7. Select the desired file and click Save.

Note: you can select a file anywhere on your

system, and if it is not already in the local .macros
directory, it will be copied there.

8. Repeat steps 6 and 7 for macros with

multiple command files.

Page 404
 HOW TO DEFINE AND USE MACROS

To change an existing macro definition:

1. In the Command Dialog "Macros" tab (File >

Command from the Main Menu), click "Edit".

2. The Edit Macro dialog opens. Change any of

the values in this dialog, then click "Close".

Your changes will not be written to the

macro.define file until you either click "Save
Changes" in the Command dialog Macros tab, or
close the command dialog and answer "Yes" to the
Save Changes query message.

OTHER NOTES
A common use of tying more than one command file to the same key is to create a toggle. Make the first command
file turn the option on, and the second command file turn the option off. Then tie both of these to the same key. You
will now cycle through the two command files, effectively creating a toggle situation.

SEE ALSO
How To Record and Play Command Files

User Manual: Macros Tab

Page 405