Custom Command Pages

Intro

It can be accessed at: Window-->Custom Commands.

This GUI provides a convenient shortcut for running common commands. This GUI can show multiple pages (tabs) of commands. Each command provides a custom set of inputs. Clicking in an input field will show auto-complete options, if available. Hovering over the run button will allow you to preview the command that will be sent to the server.

Command Page Management

The panel can show multiple pages of commands. Additional pages can be loaded by choosing File-->Load... from the file menu. You can also choose File-->Reset Tabs to reset the opened tabs to a predetermined state set by the instrument admin. This default state can be set, by an admin, by simply loading the desired, default, set of pages and choosing File--> Set Reset State.

Command Page Creation

Basic

New command pages can be created in the Editor Panel with File-->New Command.  Each command page is composed of a list of commands (left section). A command list can be given a custom title by filling in the "Title" text input. To add a command, to the command list choose a command from the drop-down list (on the left) and press Add. It will appear in the command list where it can be copied, removed, or reordered (via drag/drop). Selecting a command in the list will allow it to be edited (center section).

Each command can be given a custom title by filling in the "Title" text input. A command is composed by a series of inputs, each of which corresponds to an input to the command, at the command line (standard input), or is a special customized input.  To add a standard command input choose one from the drop-down list and press "Add". Inputs can be reordered or removed from the list, like commands. Selecting a command allows its inputs to be edited and will show a live preview at the bottom of the editor panel.

Note: You can add custom input by typing any name you want. Details of this choice are discussed in the Advanced section.

How a command string is generated from its inputs and how auto-complete options are determined, is highly customizable. If all inputs are standard, then sensible default behavior will be present by default. If default behavior is desired then only the following should be edited:

• Title - the name of the input that will appear in command GUI
• Default Value - Will be reset to this value every time the client starts (this may be changed in the future)
• Width - Determine how wide the input is in the GUI

• Show as checkbox - Useful for flag command arguments. Flag arguments are optional boolean arguments which are either present (true) or absent (false).

• Visible - Should the input be shown?

Advanced

Highly customized, command inputs can be created through scripting. Using scripting you can describe how an arbitrary, custom set of inputs are converted to command strings. Behind the scenes, all command processing occurs in a special javascript namespace. Every time an input is modified, the following process occurs to generate the command string:

1. The javascript namespace is reset back to a default state. Among other things, the variable cmd is set to a string containing the name of the command.
2. Each command's Command Text script is evaluated. The result is stored in the variable cmd.
3. When complete the the variable cmd contains the command string which will be queued if the run button is pressed.

Typically, each input appends some text to the cmd variable by evaluating to something like: cmd + <some expression>. In this way , a command string is progressively built by running each input's script. However, its also possible for the last input to simply calculate and assign the entire command string to cmd (in this case its often made invisible and simply serves as a final processor).

Namespace

To effectively script its important to know what functions and variable are available. For example, the cmd variable, is initialized to the command's name, and must contain the full command string by the time the last input's Command Text script is run. Here is a description of what is available:

• cmd - The current value of the generated command string. This is overwritten by evaluation of each input's Command Text script
• current - The current input being processed
  • .value - The value, for this input, entered by the user. This is typically a string, but could be another data type such as boolean for check box inputs (or other types of inputs created in the future).
  • .argData - Information about the argument this input represents (not all information is present for custom inputs).
    • .isRequired()  - The command requires this argument.
    • .displayName() - The official long-name of the argument.
    • .getArgString(value) - Generates an argument string, for the given input value, appropriate for use in a command string. For example:
      • optional arguments would look like: --option <optionValue>
      • positional arguments would look like: <posValue>
      • flags would be <empty string>, if false
  • .isFlag() - Is a flag argument (absence implies false)
  • .argString() - A shortcut for current.getArgString(current.value).
• inputs.<inputName> - Can be used to access the current or any previously processed input.

Auto-complete

To display auto-complete options:

1. The command processing javascript namespace is cleared back to a default state.
2. Each input's Command Text script is evaluated, up to and including the input being auto-completed.
3. The input's Permitted Values script is evaluated. This should return an array of strings. A useful function, for this, is: autoComplete(partialCommandString). It returns a list of strings, representing possible auto-complete options, as if partialCommandString had been typed at the console followed by tab. This can also simply return a hard-coded array of string: ["Auto1","Auto2","etc"] or any piece of code that evaluates to a list of strings.