Using the Scripter

The scripter window will look something like figure 1 below:

The white text area on this window contains an example script (starting inputs:...). The three buttons above this text area are used to start the execution of this script (left button), stop the execution of a running script (middle button) and to browse any errors produced by a script (right button). The current example script does not do anything useful without the creation of any components to control, so you shouldn't run it. Instead, the example section of this document will demonstrate how to build a simple example to show how the Scripter works.

1. Create an instance of the TestingTextFieldInput component through the capability browser.
2. In the graph component editor, select this new component, drag it down to the editor pane, then right click on the top section of the component in the editor pane, and select the "Settings" option on the pop-up menu.
3. Using the Component Settings dialog that appears, change the name of the component to something shorter (eg TextInput), then close the dialog.
4. Using the same procedure, create an instance of the TestingTextFieldOutput, and change its name to something shorter (eg TextOutput)
5. Now delete the existing example script in the Scripter window, and replace it with the following:

   inputs:
     TextInput.value as String in
   outputs:
     TextOutput.value as String out
   state:
   status:
   on in:
     out = in;
   

6. Click the run button on the scripter window. A message should appear on the bottom of the window indicating that the script is now running
7. associated with the TestingTextFieldInput component should be a window containing a text input field, and with the TestingTextFieldOutput component should be a window which can output text. Locate these windows, type some text into the input field and press return. If the script is running properly, you should find that the text is copied by the script to the output window, without you having to add an edge between these components in the graph editor.

inputs section

This section is used to define the component properties that are to be used as inputs to the script. In the example script above, this section only has one line:

inputs:
  TextInput.value as String in

This line means that property value on a component named TextInput will be considered as an input to the script, and that this property will be referable to using the variable in throughout the rest of the script.

Users can add as many different properties as they wish to the inputs section, providing that each is given a different variable name.

outputs section

This section is used to define the component properties to which this script will output values, and in the example script above, this section also only has one line:

outputs:
  TextOutput.value as String out

In this case, this means that property value of component TextOutput will be used as an output of the script, and will be referable to through the variable out

on in section

This section specified what actions should occur when the value in variable in changes. Since this variable refers to property value of the component named TextInput, then this allows a user to specify an action to be performed when this property changes. In this case, the action that is to be performed is to set the variable out to the value of the variable in:

on in:
  out = in;

Since variable out refers to property value of the component named TextOutput, then this has the effect of setting this property to the value of the value property of the TextInput component.

Note that the text in this section, ie the line that says out = in; is called a scriptlet. Scriptlets can consist of multiple lines of BeanShell code, but please ensure that these lines are seperated by a semi-colon, eg

on in:
  in = in/2;
  out = in;

How do scripts appear in the Graph Editor

After having started the script running, take a look at the graph editor window, which might look something like figure 2 below:

The component labelled ScripterGUI.main has been created by the Scripter application, and you can see that it has properties which correspond to variables defined in the input and output sections of the script, as described above. These properties are connected to the properties of other components from which they take input, and to which they provide output, and these connections have also been created automatically by the Scripter application.

Adding a new input/output to a script

TextInput.value as String in

to a script by directly typing it, the Scripter provides graphical features that can assist. Move your cursor to the place where you want a new line to be added, and select either Input... or Output... from the Insert menu. You will then be shown a dialog that looks something like figure 3 below:

This displays a selection of lines that might be added. Click on one, and click OK, and this line will be added at the position where your cursor is. If you add any components to your graph whilst viewing this dialog, then you might have to click Refresh for any properties you have to appear in the dialog.

Viewing script variables

Whilst the script is running, you can view the status of any variables that it defines. To do this, select the Variables option from the View menu, which will launch a dialog looking something like figure 4 below:

In this case, this indicates that the script has two variables named in and out, gives their values, indicates that they are linked to a component (ie their Link Status is given as OK) and gives the name of the property of the component to which they are linked.