Example: Creating a scripted Pushbutton control in a form

VWorks Software User Guide : Creating forms for protocol operators : Example: Creating a scripted Pushbutton control in a form

To create or edit forms, you must be an administrator or technician. You should also have an understanding of how to create protocols in the VWorks software.

This topic provides an example of the Pushbutton and File Browsing controls in the Form Designer. For more details, see Adding form controls that allow editing or runtime data display.

About the script for the example

The example presented in this topic uses the following script:

runset.appendProtocolFileToRunset (file01, numRunTimes, "", "myform1.VWForm");

This script appends the contents of a protocol file to the Runset Manager, specifies the number of times the protocol should run, and passes the file name of the form (.VWForm) to be associated with the protocol.

The following table describes the arguments for the appendProtocolFileToRunset method used in the example script.

Argument	Example	Descriptions
string ProtocolPath	file01	The protocol file path. In this example, the variable file01 is used for the file path.
int RunTimes	numRunTimes	The number of times (integer) to run the protocol. In this example, we use the variable numRunTimes so that the form users can edit this value.
string ProtocolNotes	""	An empty string. Although the third argument is not used in this case, the empty string is required as a placeholder.
string formToUse	"myform1.VWForm"	The file name of the form to be associated with the protocol once the protocol starts running. The argument must specify the file name (not the path) of the form that contains the pushbutton.

For details on other runset object methods that can be used with forms, see runset object.

Creating the example pushbutton

The following example describes how to create a pushbutton that enables the form’s user to select which protocol to run.

To create the example pushbutton:

1 In the VWorks window, choose File > New > Form.

2 In the Form Designer window, click Save As and save the form with the name myform1.VWForm.

3 To configure the File Browsing control, drag File Browsing from General Controls to the Form Canvas. Enter the following settings under File Browsing Properties:

Property	Value
Storage Type	Select the storage type for your VWorks edition: • Shared Service Repository — Content Management • Local Storage (HDD) — local file storage
Mode File Open\|Save	Select File Open.
JavaScript variable	Enter file01.
Start Path	Enter the file path for the file that this control will open, for example, [olssvr]:VWorks Projects/VWorks/Protocols.
Always use global context	Select the check box.
Data entry	Select the check box.

Use the default selections for the remaining properties.

4 Optional. To provide a caption for the File Browsing control, drag Static from General Controls to the Form Canvas.

a Under Static Properties, in the Control Name field, type a functionally descriptive name for the control.

b In the Display string field, type the following caption: Select the protocol file:

5 To configure an Edit control that allows users to enter the number of runs, drag Edit control from General Controls to the Form Canvas. Enter the following settings under Edit control Properties:

Property	Value
JavaScript variable	numRunTimes
Always use global context	Select the check box.
Data entry	Select the check box.
Mandatory	Select the check box.

Note: The Mandatory setting causes the software to display an error message If the form’s user forgets to enter the number of runs.

You can also enter a Default value that the software will use unless the form user changes the value.

6 Optional. Repeat step 4 to create the following caption for the number-of-runs control: Number of times to run:

7 To configure the pushbutton, drag Pushbutton from General Controls to the Form Canvas. Enter the following settings under Pushbutton Properties:

a Click the Script field, and then click the

button that appears. In the Input Text dialog box, type the following script:

runset.appendProtocolFileToRunset (file01, numRunTimes, "", "myform1.VWForm");

Note: If you copy this example, make sure to use straight quotation marks instead of curly quotation marks or smart quotes.

b Select Always use global context and Disable when running.

The global context is required for the variables in the Pushbutton script, the File Browsing control, and the Edit control because at the time the button is pressed the form is not yet associated with a protocol. Without a protocol association, there is no protocol from which to get an associated protocol's context.

c Type the Caption that will appear on the pushbutton, for example, Run Selected Protocol.

d To select an icon for the Pushbutton control, click the Image field, and then click the

button that appears. In the Open File dialog box, select the following icon file (.*ico) for the run button. This example uses 24b_start_icon_up.ico.

Note: Image files must be imported into the VWorks file storage system before they are available for use in the VWorks software. To import an image file, see Importing and exporting miscellaneous files.

8 Click OK to close the Form Designer and save the changes.

Figure Example form in full screen view with the logs included

Testing the example pushbutton

To test the example pushbutton:

1 Ensure myform1.VWForm is open in the VWorks window.

2 In the form, click

and then select the protocol file (.pro).

3 In the Number of times to run box, type a value.

4 Click the custom pushbutton that you created, for example, Run Selected Protocol.

Related information

For information about...	See...
Workflow for creating or editing a form	Workflow for creating or editing a form
Controls under General Controls in the Form Designer window	Adding form controls that allow editing or runtime data display
Controls under Specialized Buttons in the Form Designer window	Overview of the specialized buttons
Controls under Specialized Display Controls in the Form Designer window	Adding indicators for elapsed time and progress to a form
Form properties in the Form Designer window	Setting the form properties
Creating a basic protocol	Workflow for creating a basic protocol
Using JavaScript	Creating a protocol: advanced topics