Example: Creating a scripted Pushbutton control in a form

About this topic

To create or edit forms, you must have VWorks Technician- or Administrator-level access. 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 users to select which protocol to run.

To create the example pushbutton:

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

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

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

 

a	In the JavaScript variable field, type file01.

b	Select Always use global context and Data entry.

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

Under Static Properties, in the Display string field, type the following caption: Select the protocol file:

 

4	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:

 

a	In the JavaScript variable field type numRunTimes.

b	Select Always use global context and Data entry.

c	Select Mandatory. If the users forget to enter the number of runs, the software will display an error message after the user selects the protocol and clicks the pushbutton.

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

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

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

IMPORTANT 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	Click the Image field, and then click the button that appears. In the Open dialog box, select the following:

…\Program Files\Agilent Technologies\VWorks\clipart\24b_start_icon_up.ico

7	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	Configuring a run button and other specialized buttons in a form
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 or editing a form
Using JavaScript	Creating a protocol: advanced topics