Scripting UI Devices
Scripting involves a number of dialogs, menus, and controls. Here is an illustrated overview, with links to more information. Click any framed image to see it full size.
|Train Script Menu||Right-click a train or choose Train > Script from
the main menu to get a set of commands for operating train scripts.
See Train Script Menu below.
|Script Toolbar||Button-based version of the menu. See Script Toolbar below.|
|Script Editor||For editing, playing, and watching train scripts in action. See Script Editor.|
|Junction Action Editor||For editing and setting parameters of junction actions. See Junction Action Editor.|
|Script Central||Five-tab dialog provides access to all scripts, plus reference material. See Script Central.|
|Schedule Window||Displays output from running scripts. See Schedule Window.|
|Insert Here menu||When a script editor window is up, right-click a junction and get commands to insert special text into the script. See Insert Here Menu below.|
|Note Window||Comes up when a Note command is executed in a script. Can be manipulated by user or by script. See Note Window below.|
|Input Box||Comes up when Input command is executed. Prompts for value and returns in named variable.|
|Script Command Prompt||Special input dialog for entering and executing script commands one at a time. Called up from main menu View > Windows > Script Command or toolbar button. Details below.|
|Interactive Command Box||Special window in Script Central for entering script commands and executing them line by line. Called up from context menu in Script Central; see description on Scripts tab page.|
Train Script Menu
Commands on the Script context menu apply to the script attached to the right-clicked train. If the train has no script, only Edit is enabled. If the train has no engine, none of the commands is available -- you cannot create a script on a train unless it has an engine.
Buttons from left to right:
Insert Here menu
A special context menu comes up when you right-click a junction when one of the script editor windows is on display and focus is in the text box. The commands on this menu insert different junction-based items into the text box at the position of the cursor.
The Note Window is a special window used by a script to display text. There is only one such window, shared by all scripts and all layouts. The user can adjust its size, position, and style, and the settings will stick until changed, but the script author also has some control over these settings and may override user choices.
Behind the scenes, the note window is a floating window containing a rectangular scenery object which supplies the style. By default it has a thin resizing border -- drag an edge or corner to resize the window, or press and drag anywhere inside to move it. Right-click for the context menu with these commands:
Managing the window from a script involves these commands:
|note <string>||bring up Note Window and display the string. May be a multi-line string if quoted; see Display Strings|
|note||with no argument => take down Note Window|
|set NoteWndRect <t,l,b,r>||specify size and position to apply at next showing. Coordinates are relative to main app window|
|set NoteWndAutoFit <0/1>||turn off/on auto-fit at next showing|
|set NoteWndTextPos <L/C/R>||set text position for next showing|
In some scripts, the Note Window is used as a sort of modal dialog. It provides a prompt and the script waits for a reply (e.g., a certain key to be pressed). In these situations you are expected to provide a response, and not use Hide to avoid doing so.
Script Command Prompt
The Script Command Prompt (SCP) is a one-line dialog for entering and executing script commands one at a time.
Call up the SCP from the menu View > Windows > Script Command or the toolbar button (shown above).
Enter any script command, then click OK or press Return. The dialog goes down and the command begins to execute immediately.
You may enter a command by typing, or choose from the drop-down most-recently-used (MRU) list. The size of this list can be adjusted in the Script Central Settings tab.
The SCP is useful for various purposes: testing statements while developing scripts, carrying out one-time actions, etc. Another way to execute statements one at a time is the Interactive Command Box in Script Central. In that window you enter commands not in a one-line box but on a sort of scratch pad.
To enter multiple commands, separate them with semicolons. Another way to run multiple commands is to create a subroutine and just enter a call here.
When you press Enter or click OK, the command is "launched," i.e., converted to a special little script and started. It runs until it is finished, then stops and self-destructs. This mechanism allows you to include wait conditions along with executable statements.
If you enter a train action command, it is applied to the selected train.