Adding form controls that allow editing or runtime data display

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 and define JavaScript variables in the VWorks software.

This topic describes the General Controls in the Form Designer window and how to configure them:

•	About the General Controls

•	Configuring the General Controls

Figure. Form Designer window General Controls and example form

 

For more details on creating forms, see Workflow for creating or editing a form.

About the General Controls

The controls available under General Controls can be assigned JavaScript variables to allow users to edit data or to display runtime data on the form. For example, you might want the form to display the volume dispensed or to allow the form’s user to enter the number of mix cycles. The JavaScript variable assigned to the control must also be assigned to the given task parameter value.

The general controls include the following:

 

Control	Description
Static text	Displays read-only text. Use this control to create: • Captions for other controls on the form, such as drop-down lists, progress bars, sliders, and edit controls. • Read-only displays for runtime data. The JavaScript variable must be assigned in the Static control properties and in the corresponding task parameter in the protocol. The following figure shows an example that consists of two Static text controls in combination with a Slider control. A Static text control (left) provides the caption, Mix cycles, and a Static text control (right) displays the value of the current slider setting.
Edit control	Allows form users to enter or edit data. The JavaScript variable must be assigned in the Edit control properties and in the corresponding task parameter in the protocol. The following figure shows an Edit control (right) that allows the form users to edit the volume. This control has an assigned JavaScript variable (vol), which is also assigned in the corresponding task parameter in the protocol. Note: A Static text control (left) provides the caption, Volume (uL).
Droplist	Provides a drop-down list of choices. In the following figure the Droplist control has an assigned JavaScript variable (BCside) that is also specified in the protocol task parameter for defining the barcode side of the labware. Note: A Static text control provides the caption for the Droplist control.
Dropdown controls	Provides a drop-down list of choices and allows users to type arbitrary text into the edit field. The Dropdown control in the figure has an assigned JavaScript variable (time) that is also specified in the protocol task parameter for defining the incubation time. Note: A Static text control provides the caption for the Dropdown control.
Slider	Enables users to set a value on a continuous range of possible values. The following figure shows a horizontal and vertical slider, where the position of the slider is coordinated with a Static text control (left) or Edit control (right). In the horizontal example (left), the user moves the slider to set the Mix task parameter value, while the value updates in the display. In the vertical example (right), the user can type a number in the box or move the slider to set the Mix task parameter value.
Progress bar	Provides a visual indication of task progress. The JavaScript variable must be assigned in the control properties and in the corresponding task parameter in the protocol. In the following figure, the gray bar shows how much of the task has been completed. Note: A Static text control provides the caption, Progress. Note: To display the progress for the entire protocol or runset that the form is running, use the Overall Progress bar under Specialized Display Controls.
Pushbutton	Allows you to write your own script for the action that the button will perform. The following figure shows a form with a custom pushbutton for running a protocol that the form’s user selects in a File Browsing control. The script specified in the Pushbutton Properties calls the file path defined as the JavaScript variable for the File Browsing control. Note: For more details on how to set up this example, see Example: Creating a scripted Pushbutton control in a form.
File Browsing	Allows users to locate and select the specified file type. In the following figure, the File Browsing control has an assigned JavaScript variable for the file path (full file name and type), which is called by the script associated with the custom pushbutton that runs the selected protocol. Note: A Static text control provides the caption, Select the protocol file.
Checkbox	Allows users to enable or disable the corresponding actions. The JavaScript variable must be assigned in the Checkbox control properties and in the corresponding task parameter in the protocol. The following figure shows two examples. If the user selects the check box, the assigned JavaScript variable is set to 1. If the user clears the check box, the assigned JavaScript variable is set to 0.
Radio button	Presents choices from among several items. Each Radio button control has a JavaScript variable that is also assigned in the corresponding protocol task parameter. If a user selects an option, the assigned JavaScript variable is set to 1. If the user clears the option, the assigned JavaScript variable is set to 0.
Date and Time	Displays a preset date and time or a date that the user can set. To correspond with a given task, the JavaScript variable must be assigned in the control properties and in the corresponding task parameter in the protocol. Note: You can use the Elapsed Time indicator for the entire run. See Adding indicators for elapsed time and progress to a form.
Group box	Displays a rectangle that can be resized and labeled to visually group other controls together. To correspond with a given task, the JavaScript variable must be assigned in the control properties and in the corresponding task parameter in the protocol.
Image	Allows you to place a static image on the form. To correspond with a given task, the JavaScript variable must be assigned in the control properties and in the corresponding task parameter in the protocol.
Line	Provides a vertical or horizontal line that you can use to visually separate items on the form.
Tab Control	Displays tabbed pages in the form. You can add different controls and information in each tabbed page. Figure. Tabbed pages By default, when you drag a Tab Control onto the Form Canvas, the software displays two tabbed pages. To add another tabbed page, right-click the tab area, and select Add tab. To remove a tabbed page, right-click the tab, and then select Remove tab. To change the tab names, see Setting Tab Control properties. Figure. Adding or removing tabbed pages
Panel	Displays a container in which you can add controls and information. You can add one or more panels in a form to group or categorize different controls. Figure. Panel containing different controls

Configuring the General Controls

To add a control to the form:

1	Under Available Controls, click General Controls, and then drag the desired control to the Form Canvas area.

An invisible autogrid assists you in aligning the control in the form. To turn off the autogrid, press ALT while dragging the control into position.

2	In the Form Canvas area, click the control that you want to set up, so that a resizing box appears around the border. To resize the control, drag one of the sizing handles.

Note that the corresponding properties appear for the selected control as the following figure shows.

Figure. Form Designer window displaying properties for the selected control

 

Note: Click Preview to display the image that the form’s user will see.

3	Edit the Properties for the control. The properties can include a combination of the following depending on the control:

•	Setting properties common to the general controls

•	Setting Static text control properties

•	Setting Droplist and Dropdown properties

•	Setting Slider properties

•	Setting Progress bar properties

•	Setting Pushbutton control properties

•	Setting File Browsing properties

•	Setting Checkbox properties

•	Setting Radio Button properties

•	Setting Image (static) control properties

•	Setting Date and Time properties

•	Setting Group Box properties

•	Setting Tab Control properties

•	Setting Panel properties

The Line control does have any properties that you can set.

Note: If you want one control to overlap another control on the form, select the control that you want on top, and then click Bring selected control to front.

Setting properties common to the general controls

The following table lists the properties for all controls. A given control might use only a subset of the properties listed.

 

Properties	Description
JavaScript variable	The JavaScript variable that will be associated with the focused control. Type any string that qualifies as valid syntax for a JavaScript variable name. In the protocol, type the variable name for the corresponding Task Parameters property. For example, if you want the form’s user to enter the aspirate volume for a given task, you could use an Edit control that has a JavaScript variable of vol. In the protocol, you would specify the Aspirate Properties for Volume as = vol. For more details on using JavaScript variables in the Task Parameters area, see Using simple variables.
Always use global context	If the form’s Use global context for variables check box is selected, you can ignore this setting. If the form’s Use global context for variables check box is not selected, specify which context to use for the control’s JavaScript variable: • Global context. Select this check box. For example, if the variable in question will be acted on before the protocol is running or is scheduled to run, use the global context. IMPORTANT Any protocol that uses the global context and has JavaScript variables of the same name will be affected by changes you make to this variable, even if this form’s Use global context for variables check box is not selected. • Context of the running protocol. Clear this check box. For example, if the variable in question will communicate with the protocol once the protocol is running or is scheduled to run, you may not need to use the global context. For more details on JavaScript context, see Understanding JavaScript context in form design.
Read only	The state that determines whether the form's user can edit the contents of the control. • Select the check box to prevent users from editing the control contents. • Clear the check box to allow users to edit the control contents.
BorderStyle	The border surrounding the control. You can specify one of the following border styles: • FixedSingle. Adds a single line that encloses the control. • Fixed3D. Adds a 3-dimensional effect to the border’s appearance.
BackgroundImage	The image displayed as the background for the control. The selected image is displayed on top of the selected background color. Click the browse button to locate and select the desired image.
BackgroundImageLayout	How the selected image is displayed. Select one of the following display methods: • Center. Center-aligns the image on the control. • Stretch. Stretches the image to fit the size of the control. The dimensional ratio of the image is not maintained. • Tile. Uses multiple copies of the image to cover the entire control area. The images are in their original sizes and are placed adjacent to one another. • Zoom. Magnifies the image such that the width or length covers the width or length of the control. The dimensional ratio of the image is maintained.
Background_Color	The color of the control. Click the field, and then select the desired color.
Data entry	The option to allow the user to edit the value in the control when the protocol is paused. • Select the check box to allow form users to edit the value when a protocol is not running and when a running protocol is paused. • Clear the check box to allow users to edit the value only when a protocol is not running. For the data entry controls, you can also provide the Print, Reset, and Save data entry buttons from the Specialized Buttons area. For details, see Configuring a run button and other specialized buttons in a form. Note: The Data entry property is not available if the Read only check box is selected.
Mandatory	The option to require the form’s user to enter a value for this field before starting the associated protocol or runset. Select the check box to require the user to enter a value for the field. Clear the check box if the user can start the protocol or runset without entering a value for the field. Available if the Data entry check box is selected.
Default value	The value the form should display when the user resets the field. Type the default value in the box. Special conditions apply for some controls, such as check boxes and radio buttons. For details, see the property description for the specific control.
Min value, Max value	A range of permitted values. The value saved to the associated JavaScript variable will be a number. Type the minimum and maximum value to define the range of values. If the form’s user types a value outside this range, an error message appears. To allow the user to type any value in an Edit control, leave the Min and Max value properties blank. The value saved to the associated JavaScript variable will be a number, unless the value appears to be something other than a number. In which case, the value will be saved as a string. Special conditions apply for some controls, such as sliders. For details, see the property description for the specific control.
Dock	The option to anchor the control to a position on the Form Canvas. Select one of the following positions: • None. You can move the control freely on the canvas. Select None if you want to manually position the control, and you prefer to set the size of the control using the Width and Height properties. • Top. The top side of the control is adjacent to the top of the Form Canvas. The control’s width is increased to match the width of the canvas. Although the width is fixed, you can change the Height value. • Left. The left side of the control is adjacent to the left side of the Form Canvas. The control’s height is increased to match the height of the canvas. Although the height is fixed, you can change the Width value. • Bottom. The bottom side of the control is adjacent to the bottom of the Form Canvas. The control’s width is increased to match the width of the canvas. Although the width is fixed, you can change the Height value. • Right. The right side of the control is adjacent to the right side of the Form Canvas. The control’s height is increased to match the height of the canvas. Although the height is fixed, you can change the Width value. • Fill. The control’s size is increased so that it completely covers the Form Canvas area. The width and height of the control are fixed.
Font size	The font size of the text that appears in the control. To change the font size, type a new number in the field. Any controls that you create subsequently will use the new font size. Default: 10
Font color	The color of the text that appears in the control. To change the color for the selected control and subsequently created controls, click the field, and then click the that appears. Click the color in the palette list, or click Custom Color to open the Select Color dialog box and create a custom color. Default font color: Web Black Default background color: 240, 240, 240

Setting Static text control properties

The Static text control has the following properties in addition to the properties common to the other general controls.

 

Properties	Description
Display string	Type the text that you want to appear on the form, for example, a caption for another control on your form. The following figure shows an example of a Static text control with a display string that provides the label, Volume (uL) for an Edit control. Note: Display string is enabled only if the JavaScript variable property is blank. Note: To use the symbol µ, copy the characters to the Microsoft Clipboard from other software. Right-click the field and choose Paste to insert the character into the field.
Border	To add a border around the control, ensure the check box is selected (default). For example, a border is useful if you want to provide a display of runtime data. To remove the border, clear the check box. For example, if you are creating a caption for one of the other controls, a border is unnecessary. The following figure shows an example of two Static text controls combined with a Slider control. The caption on the left is a Static control with no border. The display on the right is a Static control with a border.

To coordinate the Static text control with a protocol task parameter, both the control and the task parameter must use the same JavaScript variable.

To coordinate the Static text control with another control, for example, the slider, both controls must have the same assigned JavaScript variable and both controls must specify the global JavaScript context so that they can communicate with each other.

Setting Droplist and Dropdown properties

The Droplist and Dropdown controls have the following properties in addition to the properties common to the other general controls.

Note: You might want to use these controls in combination with a Static text control to display a caption for your drop-down list or drop-down combo box.

 

Properties	Description
Items	Type the list of items that will appear in the list of the Droplist or Dropdown control, where each item is separated by a semicolon with no spaces. For example, type 3;6;9;12 to provide the form’s user with the choices 3, 6, 9, 12.
Default value	Type the item from Items list that will display in the form by default. IMPORTANT Make sure that the default value is also in the Items list. Otherwise, the Droplist control will display the first list item by default. The Dropdown control will display the default value even if the value is not included in the Items list.
Disable when running	Select the check box to prevent the operator from changing the selected Dropdown item while the protocol is running. Clear the check box to enable the operator to change the selected Dropdown item during the protocol run time. This property is available only when the Read only check box is cleared. If the Read only property is selected, the Disable when running property is not available.

Figure. Dropdown Properties example

 

Setting Slider properties

The Slider control has the following properties in addition to the properties common to the other general controls.

 

Properties	Description
Orientation	Click the field to display the , and then click one of the following: • Horizontal. The scale reads from left to right, Min value to Max value. • Vertical. The scale reads from bottom to top, Min value to Max value. The figure shows an example of a horizontal and vertical slider. The horizontal slider is combined with an Edit control that displays the changing numeric value as the slider is moved.
Min value, Max value	To specify the range of values that the slider represents, type a minimum and maximum numeric value. The slider has a tick mark for each numeric value in the range. For example, a slider with a range of 1–10 has 10 tick marks, and a slider with a range of 1–20 has 20 tick marks. When the form’s user moves the slider, the resulting value is written to the control's JavaScript variable as soon as the slider is released.
Increment size	Type a positive number to use as the increment that the numeric value changes as the slider is moved. For example, if the slider’s range is 1–10 and the increment size is 1, the value will change by 1 each time you move the slider. If the increment is 2, the value will change by 2 each time you move the slider. The increment size should be in relation to the slider’s range of values. For example, a slider that has a narrow range of values typically would not have a large increment size. Likewise, a small increment size may be insufficient for a slider that has a very wide range of values.

You can use the Slider control in combination with the:

•	Static text control to display a caption for the slider or display the current value of the slider’s setting.

•	Edit control to display the current value of the slider’s setting or allow users to enter a value instead of using the slider.

To coordinate the slider setting with a Static text control or Edit control and the protocol task parameter setting:

•	Both the Slider and Static or Edit controls must have the same JavaScript variable assigned (for example, mix).

•	The variable assigned in the Slider and Static or Edit controls must be in the global context so that the two controls can communicate.

•	The corresponding Mix task parameter in the protocol must also have the same JavaScript variable assigned (for example, mix).

If the slider’s Data Entry property is not selected, the slider will move according to the current value of the underlying JavaScript variable. The behavior of the slider is undefined if the JavaScript variable does not have a numeric value, or if the variable’s value is outside the slider's range.

Setting Progress bar properties

The Progress bar control has the following properties in addition to the properties common to the other general controls.

Note: You might want to use this control in combination with a Static text control to create the progress bar caption.

 

Properties	Description
JavaScript variable	Must have a numeric value that is a positive number and the value must not be greater than the Max value setting.
Max value	Type a numeric value larger than 0. The value represented by the left end of the progress bar is always 0. The Max value determines the value represented by the right end of the progress bar.
Bar color	Optional. To change the color, click the field, and then click the that appears. Click the color in the palette list, or click Custom Color to open the Select Color dialog box and create a custom color.

The progress bar moves according to the current value of the underlying JavaScript variable. All progress bars are horizontal.

Setting Pushbutton control properties

The Pushbutton control can execute any JavaScript code that you specify. You provide the script in the Pushbutton Properties, as the following figure shows.

Figure. Workflow to create a pushbutton

 

In addition to the properties common to the general controls, the Pushbutton control has the following properties. For an example of how to set up a pushbutton using a script, see Example: Creating a scripted Pushbutton control in a form.

 

Properties	Description
JavaScript variable	The JavaScript variable that will be associated with the control. Type any string that qualifies as valid syntax for a JavaScript variable name. The JavaScript variable can be used to exchange a result or value between the protocol and the form. A variable can also be shared between different areas of the same form, for example, to update another field within a form with a button. If you provide a variable, you can specify the Default value for the JavaScript variable.
Default value	Specify the default value of the JavaScript variable.
Script	Click the field, and then click the button that appears. In the Input Text dialog box, type the JavaScript code to be executed when the pushbutton is pressed, or click Browse to select the file (.txt) that contains the script. Note: If the script specifies a file on your computer, and you later export the form with this pushbutton, you must specify the file in the Additional Files page of the Export Wizard.
Always use global context	Specify the context in which to execute the script: • Global context. Select the check box to use the global context. For example, if the button is to be pressed while no protocol is running, you must use the global context. IMPORTANT Any protocol that uses the global context and contains JavaScript variables of the same name will be affected by changes you make to this variable, even if this form’s Use global context for variables check box is not selected. • Context of the running protocol. Clear the check box to use the protocol’s private context.
Disable when running	To make the button unavailable (grayed) whenever the form is running a protocol or runset, select this check box (default). To make the button enabled at all times, clear this check box.
Icon	Optional. To select an image to use as an icon in addition to the button caption, click the field, and then click the button that appears. In the Open dialog box, locate and select the image file (.jpg, .png, .bmp, or .ico), and then click Open. Note: Icons for the run and pause buttons are installed in the following folder: …\Program Files\Agilent Technologies\VWorks\clipart
Caption	To change the label that appears on the button, type the new text in the field.

Setting File Browsing properties

The File Browsing control has the properties that are common to the other general controls. No additional properties are provided.

For an example of how to set up a File Browsing control, see Example: Creating a scripted Pushbutton control in a form.

Setting Checkbox properties

The Checkbox control has the following properties in addition to the properties common to the general controls.

 

Properties	Description
Caption	Type the string to be displayed to the right of the check box.
Default value	Type one of the following: 0 — indicates the check box is cleared by default 1 — indicates the check box is selected by default Note: Any value other than zero indicates that the check box is selected.

The Checkbox control is binary. When the check box on the form is selected, a 1 is written to the associated JavaScript variable. When the check box is cleared (unchecked), a 0 is written to the associated JavaScript variable.

Note: If the JavaScript variable's numeric value is anything other than 0, the check box will display as checked.

Setting Radio Button properties

The Radio Button control has the following properties in addition to the properties common to the other general controls.

 

Properties	Description
Default value	Type one of the following: 0 — indicates the option is cleared by default 1 — indicates the option is selected by default Note: Any value other than zero indicates that the check box is selected.
Caption	Type the string to be displayed to the right of the radio button.
Group ID	Type a string to use as the ID of the radio button group. Only one button in the group can be selected at a time. When the form's user selects a button in the group, all other radio buttons with the same Group ID are cleared (not selected) automatically. For example, if you had a grouping of options for size, you could use the string, size, as the Group ID. Note: You can use a Group box to visually group a collection of radio button options.

The Radio Button control is binary. When the button on the form is selected, a 1 is written to the associated JavaScript variable. When the button is cleared, a 0 is written to the associated JavaScript variable.

Note: If the JavaScript variable's numeric value is anything other than 0, the option will display as selected.

Setting Image (static) control properties

The Image control has the following properties in addition to the properties common to the other general controls.

 

Properties	Description
Image file	To select an image to display on the form, click the field, and then click the button that appears. In the Open dialog box, locate and select the image file (.jpg, .png, or .bmp), and then click Open.

Setting Date and Time properties

The Date and Time control has the properties common to the other general controls. However, if you provide a default value, it must be in the following format. If you do not provide a default value, the software uses the current date and time from the computer.

 

Properties	Description
Default value	nn:nn:nn nn-nn-nnnn where, nn:nn:nn is the hour:minutes:seconds in a 24-hour clock and nn-nn-nnnn is the month:day:year

If you select the Data entry property for this control, the user can enter:

•	Time. The user can edit the default values.

•	Date. The user can click the drop-down list to select the date from a calendar.

Setting Group Box properties

The Group Box control has the following properties in addition to the properties common to the other general controls.

 

Properties	Description
Group name	Type the string to display as the caption for the group box.

Controls that you drag inside the group box become part of the group box. The group box may need to be resized to ensure that all the controls within the group box borders are clearly visible.

Setting Tab Control properties

The Tab Control has the following properties in addition to the properties common to the other general controls.

 

Tab Control properties	Description
Alignment	Specifies the position of the tabs: Top, Left, Right, or Bottom.
SizeMode	Specifies the tab size: • Normal. Each tab is sized to fit its name. • Fixed. The longest tab name determines the size of all the tabs. • FillToRight. The longest tab name determines the size of all the tabs, and the tabs are flush with the right and left margins of the control.
Width	Specifies the width of the tab control.
Height	Specifies the height of the tab control.

IMPORTANT The Dock selection overrides the values you specify for the Width and Height properties. For example, if you dock the control at the top of the canvas, the software increases the width of the control and updates the Width value. To return to the previously set Width and Height values, set the Dock property to None. For more information about docking tabbed pages, see Setting properties common to the general controls.

Each tabbed page contains the following properties in addition to the properties common to the other general controls.

 

Tabbed page properties	Description
Name	The text that is displayed on the tab. Provide a name that describes the function of the tab contents.

Setting Panel properties

The Panel control has properties that are common to the other general controls. See Setting properties common to the general controls.

Related information

 

For information about...	See...
Workflow for creating or editing a form	Workflow for creating or editing a form
Pushbutton and File Browsing controls	Example: Creating a scripted Pushbutton control in a form
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
JavaScript context and form design	Understanding JavaScript context in form design
Creating a basic protocol	Workflow for creating or editing a form
Using JavaScript	Creating a protocol: advanced topics