Scripting commands with a menu

Adding an empty script command

1. Right-click a folder in the Toolbox and select New command.
2. Select Script and click OK.

You should now have a new command named Script in your folder. You can now right-click it, select edit and start scripting.

An empty script command in edit mode

Principles of using regular commands

A command is a primary functionality when performing a task in Geocap. Here are some issues that are important to know about before starting to create your own commands:

• The command is executed on a dataset or a folder in the project.
• If the command is executed on a dataset, that specific dataset is input to the execute procedure in the script. The dataset is placed in active workspace as active data. All shell commands which works on active data can now be applied to perform the task.
• If the command is executed on a folder, all datasets in the folder are executed sequentially following the rules described above for a single dataset.
• During execution the logic of the script will tell what is happening. New derived data can be saved in workspace or it can be written to the project.

A scripted command contains these tabs:

• Prestep: To be run before any datasets are involved. Only to be used for commands that are executed on a folder.
• Main: Will be executed upon each dataset in the folder or the single dataset. Should contain all execution statements.
• Poststep: To be run after all datasets are executed. Only to be used for commands that are executed on a folder.
• Comments: Used for description and comments.

and the buttons:

• OK: Menu closes and all parameters that are blocktraced are saved. The command will remember this parameters next time.
• Execute: The command will run according to the described rules.
• Cancel Menu closes and no parameters are saved.

Example: Display a dataset.

The simplest way to program this is to apply the shell command dis and put it into the Main part of a scripted command.

When pushing Execute the following happens:

1. The selected dataset in the project is made active.
2. The display command dis is executed.

This simple example has no parameters and no need for a menu front.

Creating a menu front

Assume we want to display and select colors and create a menu for doing that. The menu is programmed in QTcl. The script looks like this:

This script gives us this menu:

Simple display menu with color selection

Explanation of Pragma

Pragma is a message to the project how to handle the scripted commands. You can control visibility and the type of datasets the CO is allowed to activate. In practical progamming one does Copy and Paste of the Pragma collection and edit in a few changes where necessary.

Explanation of the Pragma statements

# Commandtype and commandname shall be the same as the file name of this script without the .tcl extension.
Geocap::pragma commandtype {Display Line}
Geocap::pragma commandname {Display Line}

# Execution mode can be interactive or direct
Geocap::pragma executionmode interactive

# Protected namespacemode means that this CO will have a menu
Geocap::pragma namespacemode protected

# Which operation mode shall it belong to
Geocap::pragma operationmode "Examples" active

# It is a shared command
Geocap::pragma sharedcommand 1

# Filter for execution is on
Geocap::pragma filterexecution 1

# Filter for visibility is on
Geocap::pragma filtervisibility 1

# Systemfilter for what to execute
Geocap::pragma systemfilter types category_generic vtk_poly_data

# Version number and text
Geocap::pragma version 1.0 "Generated menu. May 2011"

# The CO will be part of the overall prototype list of command objects
Geocap::pragma prototype 1

# Name of iconfile that shall appear with the CO
Geocap::pragma iconfile {display_line.png}

# Place the text in documentation that shall appear when the ? icon is pressed.
# The first line in the text could tell briefly what this command object is doing.
# Will draw the graphical window when pushing Execute.
Geocap::pragma documentation { }

# If the CO is activated on a folder, Prestep will be executed first.
# Then Main will be executed for each dataset in the folder.
# Then Poststep will be executed finally.

# Place statements in Prestep that shall be executed in Prestep.
# If the CO is executed on a folder, it will first execute Prestep.
# In Prestep one can use global variables (::var) which will be known all over.
Geocap::pragma prestep { }

# Place statements in Poststep that shall be executed in Poststep.
# Will run after all datasets are executed in Main.
Geocap::pragma poststep { }

# The main step that will be executed for all datasets in a folder or the single dataset.
# Will be executed for activated dataset.
Geocap::pragma mainstep { }