Form controls

You use controls to display fields on the form. The Designer provides controls for text boxes, list boxes, check boxes, option buttons, and so on. For example, you can associate a field that contains a string with a text-box control. Some controls can be used only with specific field types. For example, the list-view control and the parent/child control can be used only with a reference-list field.

You can use some controls to perform special tasks. Push buttons and list boxes can be associated with record scripts. For example, in the TestStudio schema, a push button is associated with the Build_Properties record script, which allows users to view the properties of the build they selected.

The Designer also provides an ActiveX control that you use to incorporate any registered ActiveX control into a form. For example, you might use an ActiveX control to interact with an external database. Before using this control, you must be familiar with ActiveX functionality and how to register your controls. Note that you can use ActiveX controls only with the Rational® ClearQuest® for Windows client.

The following form controls are supported:

Form control: Description
ActiveX: Incorporates any registered ActiveX control into a form. You write the initialization record script and the action record script.
Attachment: Displays a list of attached files and includes a set of controls that allow users to add, remove, or view attached files.
Check Box: A two-value control you can use for Boolean values or any field that has only two values. To specify the two values, right-click the control on the form and click Properties.
Combo Box: Combines an editable text field with a list box.
Drop-down List Box: Displays a list of possible values for a particular field.
Drop-down Combo Box: Combines an editable text field with a drop-down list box.
Duplicate Box: Displays the ID of the record of which this record is a duplicate.
Duplicate Dependent: Displays the IDs of any records that are duplicates of this record.
Group Box: Visually groups together one or more other controls.
History: Displays information about the actions applied to a record.
List Box: Displays a list of possible values for a particular field. List boxes include an additional control for selecting one or more items from a choice list.
List View: Allows you to display the records associated with a field of the REFERENCE_LIST type. Displays the associated reference list in a multicolumn format.
Option Button: Option button controls are used in groups to represent a set of mutually exclusive choices. Restricts the selection to one option in a group.
Parent/child: Allows you to set up a form to link associated records. Used with REFERENCE_LIST field type. The parent/child control consists of both a list view control and three push buttons. The list view control and push buttons are associated by using a unique list view ID. If you change the ID of the list view, you must also update the push buttons.
Picture: Allows you to include a static image on your form.
Push Button: Initiates specific tasks related to the record. You can associate push buttons with record hooks or with list views.
Static Text: Displays an uneditable text string.
Text Box: Displays a field value as an editable text string.

For detailed descriptions of the properties for each control type, see Form controls.

Adding controls to a form

Before you can add a field to a form, you must add the field in the Fields grid. For more information, see To add a new field to the Fields grid.

You can add controls to a form by using the Control Palette, the Field List, or the Form Controls menu.

The Control Palette provides a visual cue as to the type of control you are adding.
Selecting a field in the Field List and dragging it to the form adds the appropriate control to the form.
The Form Controls menu allows you to create the same controls as the Control palette; in addition, it contains a command to create ActiveX controls.

You can add a field to a form more than once, but all instances of the field must have the same value.

Adding a control with the Field List

The advantage of using the Field List to add a control to a form is that when you select a field from the list and drag it to the form, the appropriate control for that field type is added to the field. You do not have to edit the control properties to associate the field with the control.

The following table lists the default control that the Designer creates for each field type.

Field type: Default control
Attachment List: Attachment
Constant List Choice List: Drop-down list box
Date-Time: Text box
Integer: Text box
Multiline String: Text box
Reference List: Parent/child
Reference List Constant: List view
Reference Choice List=Default: Drop-down list box
Short String Constant List: Drop-down list box
Short String: Text Box

Editing control properties

If you use the Control Palette or the Form Controls menu to add a new control to a form, you must edit the control properties to associate that control with an existing field.

After adding a control to a form, you can edit the properties of the control, including selecting the field to associate with the control and specifying display attributes for the control. You can also assign record hooks to some controls to allow users perform specific tasks by using that control.

If you want dependent fields to be enabled in Rational ClearQuest Web, you must specify the field on which the dependency is based. To do this, use the Web Dependent Fields tab of the Control Properties sheet.

For descriptions of the properties for each control type, see Form controls.

Deleting a control from a form

If you no longer need a control, you can delete it from the form.

Deleting a control removes it and its label from the form but does not remove the associated field from the schema. To remove the field from the schema, you must delete the field from the Fields grid. For more information, see Deleting a field.

Changing the size and location of controls

To change the size and location a control, you can select the control and drag it to a new location on the form, or you can use the tools on the Form toolbar to adjust the position of one or more controls.

The Form Layout menu provides the same tools as the Form toolbar, plus some additional tools. The following table lists each tool and its function.

The align and same-size tools use the first control that you select as the basis for modifying the other controls.

Layout tool: Description
Align left: Aligns the left edge of each control with the left edge of the control that was selected first.
Align right: Aligns the right edge of each control with the right edge of the control that was selected first.
Align top: Aligns the top edge of each control with the top edge of the control that was selected first.
Align bottom: Aligns the bottom edge of each control with the bottom edge of the control that was selected first.
Align vertical centers: Aligns the vertical center of each control with the vertical center of the control that was selected first.
Align horizontal centers: Aligns the horizontal center of each control with the horizontal center of the control that was selected first.
Space evenly across: Arranges the selected controls horizontally to allocate an equal amount of space between all controls. The leftmost and rightmost controls are not moved.
Space evenly down: Arranges the selected controls vertically to allocate an equal amount of space between all controls. The topmost and bottommost controls are not moved.
Center vertically in dialog: Aligns the vertical center of each control with the vertical center of the tab.
Center horizontally in dialog: Aligns the horizontal center of each control with the horizontal center of the tab.
Make same width: Makes each control the same width as the control that was selected first.
Make same height: Makes each control the same height as the control that was selected first.
Make same width and height: Makes each control the same width and height as the control that was selected first.
Size to content: Adjusts the size of each selected control so that its entire contents can be viewed. This is useful for minimizing the size of a Static Text control while still maintaining the readability of the string.

Moving controls

You can move selected controls in two ways:

Drag the controls to a new location.
Press Shift+Arrow key. The control moves in the direction of the Arrow key you choose.

Aligning controls

You can align controls with one another.

To align controls:

Select a control.
All other controls that you select align with the first control that you select.
Shift-click additional controls and select an alignment command from the Form Layout menu or click an alignment button on the toolbar.

Resizing controls

You can resize individual controls, or make two or more controls the same height or width.

To resize an control, drag a corner of the control, or click Form Layout > Size to Content.

To make controls the same size:

Select a control.
All other controls that you select are the same size as the first control that you select.
Shift-click to add controls and click a Size command from the Form Layout menu.

Changing the tab order of controls

The tab order of controls determines which control receives focus when a user presses the Tab key. Each time the user presses Tab, the focus moves to the next control in the tab order.

By default, the tab order of controls is the order in which you added the controls to the form. You can change the tab order so that it reflects the order in which you expect users to use the controls.