CONTROL

While containers generally serve to organize controls, controls generally are meant to collect for user input or to display information on a user interface.

The following subjects are covered in this document:


Related information about VTML and WIZML:

Tutorial
The Visual Tool Markup Language (VTML)
Reference
VTML reference - overview
Context
EDITORLAYOUT and PAGELAYOUT sections
Container for
ITEM
Related tags
CONTAINER

top

Tools

CONTROL plays a role in the following VTML-driven tools:

  1. Tag Editor
  2. Wizard

top


Location

A CONTROL tag can be used within either the EDITORLAYOUT section of a Tag Definition or the PAGELAYOUT section of a Wizard profile file. It can occur either directly within these tags or within a CONTAINER tag.

top


User interface aspects

Focus:
Which control (or tab page!) receives focus when the editor window is displayed is determined by which corresponding ATTRIB tag occurs first in the ATTRIBUTES section.
Tabbing order:
Determined by the order in which these controls appear in the EDITORLAYOUT or PAGELAYOUT section.

top

Control types

The following controls can be used in VTML (Label and Image are output-only, all others are input controls):


top

CONTROL TYPE="Label"

Function

A label can serve as a caption for an input control. It can also be used simply to display extra information on the dialog. This is an output-only control.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="Label" .../>
CAPTION The text displayed by the label.
AUTOSIZE YES/NO. Redundant. Automatically sizes the control to the text it contains. This option is overridden if WIDTH or HEIGHT are explicitly specified; if not, AUTOSIZE is always in operation, regardless whether Yes or No is specified..
TRANSPARENT YES/NO. Makes label transparent. In practice, there seems to be very little difference between transparent or not.
ALIGN LEFT/CENTER/RIGHT. Horizontal alignment of text in the label.
VALIGN TOP/CENTER/BOTTOM. Vertical alignment of text in the label.

Examples

<CONTROL TYPE="Label" NAME="lblSource" WIDTH=50 DOWN=15 RIGHT=10 CAPTION="Source:"/>

top


CONTROL TYPE="TextBox"

Function

A simple textbox control.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="TextBox" .../>
VALUE The text displayed by the textbox.
AUTOSIZE YES/NO. Automatically sizes the control to the text it contains. This option is overridden if WIDTH or HEIGHT are explicitly specified.
Not operational.
EDITABLE YES/NO. Enables/disables editing.
AUTOSELECT FLAG. Decides whether contents get highlighted when cursor enters the textbox.
ALLOWDECIMALPOINT YES/NO (Default unknown). Indicates whether an entered number can contain a decimal point.
Not operational but useful as comment if backed up up by WIZML code.
ALLOWNEGATIVE YES/NO (Default unknown). Indicates whether an entered number can be negative.
Not operational but useful as comment if backed up up by WIZML code.
MAXLENGTH Limits the amount of text in the textbox to a specific number of characters.
PASSWORDCHAR A character to be used to mask entered text. You can create a simple password box using PASSWORDCHAR="*".
CHARCASE NORMAL/UPPER/LOWER. Specifies whether entered text is automatically uppercased or lowercased. The default is NORMAL, preserving entered case.
VALIGN TOP/CENTER/BOTTOM. Horizontal alignment of text in the textbox.

Examples

<CONTROL TYPE="Label" NAME="lblSource" WIDTH=50 DOWN=15 RIGHT=10 CAPTION="Source:"/>
<CONTROL TYPE="TextBox" NAME="txtSource" WIDTH="MAXIMUM" VALUE="Some Value" ANCHOR="lblSource" CORNER="NE"/>

top


CONTROL TYPE="CheckBox"

Function

A simple checkbox control. Returns 'true' or 'false'.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="CheckBox" .../>
CAPTION Caption displayed next to the checkbox.
CHECKED FLAG. Specifies initial status.

Examples

<CONTROL TYPE="CheckBox" NAME="checkNoShading" WIDTH="MAXIMUM"
       ANCHOR="numWidth" CORNER="NE" DOWN=4 RIGHT=20 CAPTION=" No Shading"/>

top


CONTROL TYPE="DropDown"

Function

A drop-down listbox. This tag requires <ITEM/> sub-tags, which specify the list of items in the drop down. When free text is entered into an editable DropDown, the actual text is considered the value of the control. This control type requires an end tag </CONTROL> to enclose the ITEM sub-tags.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="DropDown" ...> </CONTROL>
EDITABLE FLAG. The EDITABLE attribute decides whether it behaves like an editable dropdown combobox or a fixed dropdown listbox.

Examples

<CONTROL TYPE="Label" NAME="lblAlign" WIDTH=50 ANCHOR="lblSource" CORNER="SW" DOWN=10 CAPTION="Align:"/>

<CONTROL TYPE="DropDown" NAME="dropAlign" WIDTH=100 ANCHOR="lblAlign" CORNER="NE">  
      <ITEM VALUE="TOP"    CAPTION="TOP"/>
      <ITEM VALUE="MIDDLE" CAPTION="MIDDLE" SELECTED/>
      <ITEM VALUE="BOTTOM" CAPTION="BOTTOM"/>
</CONTROL>

top


CONTROL TYPE="ListBox"VTML 2

Function

A listbox. This tag requires <ITEM/> sub-tags, which specify the list of items in the listbox. This control type requires an end tag </CONTROL> to enclose the ITEM sub-tags. The size of a listbox is determined by its (LF)WIDTH and (LF)HEIGHT attributes.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="Listbox" ...> </CONTROL>
MULTISELECT FLAG. The MULTISELECT attribute decides whether the user can select multiple items. When multiple selections are made the control returns the values as a comma-delimited string.

Examples

<CONTROL TYPE="Label" NAME="lblAlign" WIDTH=50 ANCHOR="lblSource" CORNER="SW" DOWN=10 CAPTION="Align:"/>

<CONTROL TYPE="ListBox" NAME="listAlign" WIDTH=100 ANCHOR="lblAlign" CORNER="NE">  
      <ITEM VALUE="TOP"    CAPTION="TOP"/>
      <ITEM VALUE="MIDDLE" CAPTION="MIDDLE" SELECTED/>
      <ITEM VALUE="BOTTOM" CAPTION="BOTTOM"/>
</CONTROL>

top


CONTROL TYPE="RadioGroup"

Function

A set of radio buttons. This tag requires <ITEM/> sub-tags, which specify the list of radio buttons. This control type requires an end tag </CONTROL> to enclose the nested ITEM sub-tags.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="RadioGroup" ...> </CONTROL>
(No specific attributes)

Examples

<CONTROL TYPE="RadioGroup" NAME="radioNameConflict" WIDTH="MAXIMUM"
         ANCHOR="lblAccept" CORNER="SW" DOWN=35 HEIGHT="MAXIMUM" CAPTION="Radio One">
    <ITEM VALUE="ERROR"      CAPTION="ERROR - The file will not be saved and Cold Fusion will return an error."
          SELECTED/>
    <ITEM VALUE="SKIP"       CAPTION="SKIP - Neither saves the file nor throws an error."/>
    <ITEM VALUE="OVERWRITE"  CAPTION="OVERWRITE - Replaces the existing file if name conflict occurs."/>
    <ITEM VALUE="MAKEUNIQUE" CAPTION="MAKEUNIQUE - Automatically generates a unique filename for the upload."/>
</CONTROL>

top


Usage Notes

A radio group is always surrounded by a group box, labelled with the CAPTION; this group box can not be suppressed. The size of the group box is determined (LF)WIDTH and (LF)HEIGHT attributes. The radio buttons will be laid out vertically within this group box, and made to fit to its size which can result in overlapping radio buttons. Horizontal layout is not possible.

CONTROL TYPE="Image"

Function

An image control capable of containing BMP images. BMPs Should be saved as RLE (run-length encoding) to ensure transparency across systems. The lower left pixel determines transparent color. This is an output-only control.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="Image" .../>
FILEPATH Path to the image file relative to the Tag definition or Wizard profile file.
AUTOSIZE YES/NO. Automatically sizes the control to the image it contains. This option is overridden if WIDTH or HEIGHT are explicitly specified.
TRANSPARENT YES/NO. Controls transparency.
CENTER FLAG. Centers the image; works only if both WIDTH and HEIGHT are explicitly specified.

Examples

<CONTROL TYPE="Image" NAME="imgApplet" FILEPATH="Images/Applet.bmp" 
            DOWN=10 RIGHT=10 AUTOSIZE="Yes"/>

top


CONTROL TYPE="TextArea"

Function

A simple multi-line text entry control.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="TextArea" .../>
SCROLLBAR NONE/HORIZONTAL/VERTICAL/BOTH. Specifies which scrollbars should be displayed.
WRAP FLAG. Enables wrapping of text.
Disabled when a horizontal scrollbar is shown with SCROLLBAR="Horizontal" or SCROLLBAR="Both" even when the flag is present.

Examples

<CONTROL TYPE="TextArea" NAME="txtContent" WIDTH="MAXIMUM" HEIGHT="MAXIMUM"
        DOWN=5 RIGHT=5 MAXWIDTHPADDING=5 MAXHEIGHTPADDING=5/> 
			

top


CONTROL TYPE="ImgMapTextArea"VTML 3

Function

A simple multi-line text entry control with an interface to the Image Map editor.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="ImgMapTextArea" .../>
SCROLLBAR NONE/HORIZONTAL/VERTICAL/BOTH. Specifies which scrollbars should be displayed.
WRAP FLAG. Enables wrapping of text.
Disabled when a horizontal scrollbar is shown with SCROLLBAR="Horizontal" or SCROLLBAR="Both" even when the flag is present.
MAPNAMECONTROL Required. The name of the control in the same editor that contains the NAME attribute of the MAP tag.

Examples

<CONTROL TYPE="ImgMapTextArea" NAME="mapContent"
         WIDTH="MAXIMUM" HEIGHT="MAXIMUM" MAXHEIGHTPADDING=5 MAXWIDTHPADDING=5
         RIGHT=5 DOWN=5 MAPNAMECONTROL="txtMapName" SCROLLBAR="both"/>

Usage Notes

For Tag Editors only. Creates a text area to define AREA tags for an image map, with a button next to it which can call the Image Map Editor. Without the MAPNAMECONTROL attribute, the button to call the Image Map Editor won't work. When the attribute control it refers to already has a value - even when creating a new tag!- the Image Map Editor will go looking for an IMG tag in the same document which has a USEMAP attribute which refers to a MAP tag with this name; the image in the SRC attribute of this IMG tag will then be loaded in the Image Map Editor. If this control is bound to the $$TagBody variable for a MAP Tag Editor, the body of the MAP tag will be displayed in the text area, and passed to the Image Map Editor when editing the MAP tag.

top


CONTROL TYPE="SQLTextArea"

Function

A multi-line text entry control use to provide an SQL statement. The control contains a button which the user can use to invoke the query builder.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="SQLTextArea" .../> (ColdFusion/JRun Studio ONLY)
SCROLLBAR NONE/HORIZONTAL/VERTICAL/BOTH. Specifies which scrollbars should be displayed.
WRAP FLAG. Enables wrapping of text.
Disabled when a horizontal scrollbar is shown with SCROLLBAR="Horizontal" or SCROLLBAR="Both" even when the flag is present.
DSNAMECONTROL The name of the control that should be populated with the Data Source name when a query is selected.
QUERYNAMECONTROL The name of the control that should be populated with the Query Name when a query is selected.

Examples

<CONTAINER TYPE="TabPage" NAME="TabPage1" CAPTION="CFQUERY Tag">
     <CONTAINER TYPE="Panel" NAME="Panel1" WIDTH="MAXIMUM" HEIGHT=80 DOWN=5 RIGHT=10>
          <CONTROL TYPE="Label" NAME="lblQueryName" WIDTH=80 CAPTION="Query Name:" DOWN=15 RIGHT=10/>
          <CONTROL TYPE="Label" NAME="lblDataSource" WIDTH=80 ANCHOR="lblQueryName" CORNER="SW" DOWN=10 RIGHT=0 CAPTION="Data Source:"/>
          <CONTROL TYPE="TextBox" NAME="txtQueryName" WIDTH=130 ANCHOR="lblQueryName" CORNER="NE"/>
          <CONTROL TYPE="TextBox" NAME="txtDataSource" WIDTH=130 ANCHOR="lblDataSource" CORNER="NE"/>   
          <CONTROL TYPE="Label" NAME="lblMaxRows" WIDTH=70 ANCHOR="txtQueryName" CORNER="NE" DOWN=0 RIGHT=10 CAPTION="Max Rows:"/>
          <CONTROL TYPE="Label" NAME="lblTimeout" WIDTH=70 ANCHOR="txtDataSource" CORNER="NE" DOWN=0 RIGHT=10 CAPTION="Timeout:"/>
          <CONTROL TYPE="TextBox" NAME="numMaxRows" WIDTH=30 ANCHOR="lblMaxRows" CORNER="NE"/>
          <CONTROL TYPE="TextBox" NAME="numTimeout" WIDTH=30 ANCHOR="lblTimeout" CORNER="NE"/>

          <CONTROL TYPE="CheckBox" NAME="checkDebug" WIDTH="MAXIMUM"
                  ANCHOR="numTimeout" CORNER="NE" RIGHT=10 DOWN=4 CAPTION="Print debug info"/>
     </CONTAINER>

     <CONTROL TYPE="Label" NAME="lblSQLStatement" WIDTH=110
              ANCHOR="Panel1" CORNER="SW"DOWN=10 RIGHT=0 CAPTION="SQL Statement:"/>

     <CONTROL TYPE="SQLTextArea" NAME="txtSQLStatement" WIDTH="MAXIMUM" HEIGHT="MAXIMUM"
              ANCHOR="lblSQLStatement" CORNER="SW" DOWN="8"
              DSNAMECONTROL="txtDataSource" QUERYNAMECONTROL="txtQueryName"/>
</CONTAINER>

top


CONTROL TYPE="StyleTextBox"VTML 2

Function

A simple textbox control that enables entering style properties and interfaces with the Style Editor.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="StyleTextBox" .../>
VALUE The text displayed by the textbox.
MAXLENGTH Limits the amount of text in the style textbox to a specific number of characters.

Examples

<CONTROL TYPE="Label" NAME="lblSource" WIDTH=50 DOWN=15 RIGHT=10 CAPTION="Source:"/>
<CONTROL TYPE="TextBox" NAME="txtSource" WIDTH="MAXIMUM" VALUE="Some Value" ANCHOR="lblSource" CORNER="NE"/>

Usage Notes

This control will create a text box with a button next to it which can call the style editor TopStyle Lite in "inline" mode to create or edit the STYLE attribute of a tag. The text box itself remains editable to manually enter or update the style properties.

top


CONTROL TYPE="StyleTextArea"VTML 2

Function

A simple multi-line entry control that enables entering style properties and interfaces with the Style Editor.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="StyleTextArea" .../>
SCROLLBAR NONE/HORIZONTAL/VERTICAL/BOTH. Specifies which scrollbars should be displayed.
WRAP FLAG. Enables wrapping of text.
Disabled when a horizontal scrollbar is shown with SCROLLBAR="Horizontal" or SCROLLBAR="Both" even when the flag is present.
INLINESTYLEVTML 3 YES/NO. Controls whether the Style Editor button edits the contents of the textarea as an "in-line style" or edits the contents as a full style sheet with multiple selectors. The default mode of the Style Editor when called from a Tag Editor is as an in-line style editor, so this attribute must be defined and set to "No" to allow editing of multiple style sheet rules.
Since only a textarea allows multiple lines (while a textbox doesn't), this attribute is valid only for StyleTextArea but not for a StyleTextBox.

Examples

<CONTROL TYPE="StyleTextArea" NAME="styleContent" WIDTH="MAXIMUM" HEIGHT="MAXIMUM"
         DOWN=5 RIGHT=5 MAXWIDTHPADDING=5 MAXHEIGHTPADDING=5 INLINESTYLE="No"/>

Usage Notes

This control will create a text area with a button next to it which can call the style editor TopStyle Lite in "inline" mode to create or edit the body of a STYLE tag. To make this editable, the control must be bound to the special $$TagBody variable and the STYLE Tag Definition must have BODYEDITING defined in the TAG tag. The text area itself remains editable to manually enter or update the style rules.

top


CONTROL TYPE="FontPicker"

Function

A simple drop-down font picker.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="FontPicker" .../>
EDITABLE Obsolete for this control. A font name can always be entered manually into the listbox (i.e., it is always editable).

Examples

<CONTROL TYPE="Label" NAME="lblFace" WIDTH=50 DOWN=15 RIGHT=10 CAPTION="Font:"/>
<CONTROL TYPE="FontPicker" NAME="fontFace" WIDTH="MAXIMUM" ANCHOR="lblFace" CORNER="NE"/>

top


CONTROL TYPE="ColorPicker"

Function

A simple drop-down color picker. Enables selection of a predefined color or a special color code. Control returns value as a color name or hexadecimal value based on user's preferences.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="ColorPicker" .../>
(No specific attributes)

Examples

<CONTROL TYPE="Label" NAME="lblColor" WIDTH=50 ANCHOR="lblFace" CORNER="SW" DOWN=10 CAPTION="Color:"/>
<CONTROL TYPE="ColorPicker" NAME="colorColor" WIDTH="MAXIMUM" ANCHOR="lblColor" CORNER="NE"/>

Usage Notes

Note: Currently the Color Picker control is not able to read the current color when editing a tag, so editing an existing color is not possible.

top


CONTROL TYPE="FileBrowser"

Function

A textbox used to enter a file path. In HomeSite 3.01 / ColdFusion Studio 3.11 the control contains two tool buttons providing access to local and remote file/folder browsing. As of HomeSite 4.0 / ColdFusion Studio 4.0 there is a single browse button; the built-in File Open dialog enables both local and remote file selection. If the program is set up to use the standard Windows dialog instead, remote file selection is not possible.

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="FileBrowser" .../>
FILTER The file filter that should be used by the file/folder browsing dialogs. For Example : FILTER="*.jpeg;*.jpg".
In VTML 2 filters are freely definable; in VTML 1 the filter must correspond with one of the predefined filetypes in the program.
FILENAMEONLY FLAG. Specifies that only a filename should be entered into the textbox when a file is specified in a local or remote file dialog. By default the entire path would be pasted. Overrules RELATIVE.
RELATIVE FLAG. Instructs the control to calculate the relative path when a file or a folder path is selected. The relative path is calculated relative to the file currently opened. When a new file is being edited, it first has to be saved before relative path can be calculated. By default, absolute path is assumed.
DIRONLY FLAG. Specifies that a folder (direwctory) is being selected. This option will convert the file dialogs accessible from the browse buttons to show a folder-browsing dialog instead. By default, file-browsing is assumed. Overrules file-related attributes.
CAPTION Obsolete. (Was intended for the window caption that should displayed in the file/folder browsing dialogs. For Example: CAPTION="Select File You Want Uploaded".)

Examples

<CONTROL TYPE="Label" NAME="lblSource" WIDTH=60 DOWN=15 RIGHT=10 CAPTION="Source:"/gt;

<CONTROL TYPE="FileBrowser" NAME="txtSource" WIDTH="MAXIMUM"
         ANCHOR="lblSource" CORNER="NE" 
         RELATIVE FILTER="*.htm;*.html;*.cfml;*.cfm;*.asp"/>

top


CONTROL TYPE="ActiveX"VTML 2

Function

A container for an embedded ActiveX control. For an ActiveX control to function properly within a tag editor, the ActiveX control must implement four methods:

Syntax and Attributes

Defaults indicated in bold.

<CONTROL TYPE="ActiveX" .../>
PROGID The ProgID of the ActiveX control.

Examples

<CONTROL TYPE="Label" NAME="lblActiveX" WIDTH=50 DOWN=15 RIGHT=10 CAPTION="Process (CIRC3.OCX):"/>
<CONTROL TYPE="ActiveX" NAME="ctrlActiveX" WIDTH="MAXIMUM" ANCHOR="lblActiveX" CORNER="NE" PROGID="Circ3.Circ3Ctrl.1"/>

top