Synoptic Scripts

The scripts that you can create and run with synoptic views are essentially the same as those you create and run with the script editor. However, synoptic scripts have a couple of extra features: special variables and the ability to easily include external files. There is no limit on the size of synoptic scripts.

Special Variables in Synoptic Script Procedures

Procedures in synoptic scripts have special variables that let you determine the object on which the synoptic is applied, as well as the mouse button and key modifiers used when clicking the link.

NoteIf you are updating an older synoptic property that supports only in_obj and you want to use the new function signatures, you must open the corresponding .htm file in a text editor and change <body> to <body version="2">.

in_obj

The in_obj variable is a string containing the name of the scene object to which the synoptic property is applied, and is set automatically. This means that you can use in_obj to access anything on the scene object, and reuse the synoptic file on other objects. For example:

myVis = GetValue (in_obj & ".visibility.viewvis")

You can also get a pointer to the object with the synoptic property:

set oObj = GetValue (in_obj)

There are a few things you should know when using in_obj in your synoptic script procedures:

in_obj is always the name of the object on which the synoptic property is applied. This could be either the scene object itself, or a parent if the object inherits a synoptic property applied in branch mode.
If a primary synoptic view opens secondary ones, the value of in_obj does not change. You can still use in_obj to refer to the scene object in secondary synoptic views, even if those views are not directly applied on anything in the scene.
If there are multiple synoptic properties on the same scene object, you can cycle through the views using the up and down arrow keys. When you do this, the value of in_obj can change if, for example, one synoptic property is applied directly on the object and another one is inherited from a parent.
The value of in_obj is displayed in square brackets on the title bar of synoptic views.

in_mousebutton

The in_mousebutton variable is an integer that indicates which mouse button was used to click the hotspot. You can use this variable in your script to perform different operations based on the mouse button.

0 indicates the left mouse button.
1 indicates the middle mouse button.
2 indicates the right mouse button.

in_keymodifier

The in_keymodifier variable is an integer that indicates which key modifiers were pressed when the hotspot was clicked. You can use this variable in your script to perform different operations based on the Shift, Ctrl, or Alt keys were pressed.

0 indicates no modifier keys were pressed.
1 indicates that the Shift key was pressed.
2 indicates that the Ctrl key was pressed.
4 indicates that the Alt key was pressed.
Combinations of keys are indicated by the sum of the key values. For example, 5 indicates that Shift+Alt was pressed.

Turning Off Command Logging

Normally, scripts run from a synoptic view log every command line to the command history. However, you can turn off command logging temporarily in a script by getting the current value of the scripting.cmdlog preference, setting it to false, performing the main block of your script, and finally restoring the original preference value. This can speed up the performance of synoptic scripts. See Preferences [SDK Guide].

Including External Files

You can include external files in synoptic scripts using the #include statement. This lets you easily reuse a library of helper functions that you have created. There is no limit to the number of files you can include.

The external files must either be in the same directory as the synoptic (HTML) file that includes them, or at an absolute path you specify. To include an external file, use one of the following forms:

#include "myFile.vbs"
#include "<absolute_path>/myFile.vbs"

When you include a file, it's as if the entire contents of the external file were typed into the synoptic file at the position of the #include statement. Be careful not to accidentally put the #include statement inside a subroutine if you want the procedures and functions defined in the external file to be available at a global level.

NoteIf you reopen the synoptic file in the synoptic editor, the #include statements are expanded. Use a text editor to modify the synoptic file if you want your helper functions to be maintained as external references.

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License