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.

• Start: start playing script at current line.
• Stop: stop train and script.
• Rewind: rewind script to starting line, reposition trains to rewind point.  Can be undone using Edit > Undo from the main menu.
• Edit: brings up Script Editor showing train's script.  If train has no script, a new, empty one is created with a header stamped with the current time.
• Remove: remove and delete script from train.  This is not undoable, but does not become permanent until layout file is saved.

Script Toolbar

Buttons from left to right:

• Record button / Run light: click to begin recording, creating a script on the selected train.  Button lights red while recording; green while any train script is playing. 
• Rewind:  click to rewind all scripts to start, and all trains to rewind point.  Can be undone using Edit > Undo from the main menu.  For more, see Rewind Point.
• Stop: click to stop all scripts and trains.
• Play:  click to start all train scripts.
• Edit:  click to bring up Script Editor for the selected train, creating script if train has none.
• Pause:  click to pause running scripts; brings up a modal alert, which requires a click to dismiss and continue playing the scripts
• SC:  click to bring up Script Central

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. 

• Insert Junction Number (any junction): insert the junction number prefixed by J.  This is typically used when entering an AT or AFTER condition to cause an action at the junction.
• Insert Throw Here (for switches only): insert a Throw statement with the clicked junction number and a value matching the current switch position.  In other words, cause the script to throw the switch to the same position it is now showing.
• Insert Throw Alternate (for switches only): insert a Throw statement to the next position.  For a two-way switch, this throws to open the route which is currently closed.

Note Window

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:

• Hide: take down the window.  To bring it back, a script must execute another Note command.
• Framed: if checked, the window gets a title bar with close box, as shown above.  Default is a thin resizing border.
• Auto-Fit: if checked, causes the window to resize automatically when its text changes.  The width of the window is unchanged, height is adjusted so text will just fit.  Default is off, meaning the window size remains unchanged regardless of text.
• Properties: brings up the Scenery Properties dialog where you can set text and background styles.

Managing the window from a script involves these commands:

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. 

Instructions:

1. Call up the SCP from the menu View > Windows > Script Command or the toolbar button (shown above). 

2. 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.

Notes:

• 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.