Laying Down CONTROLS in the EDITORLAYOUT Section
The EDITORLAYOUT section nay contain only two kinds of tags:
CONTROL and CONTAINER tags. CONTROL and
CONTAINER tags represent graphical controls. The tags are identical in definition,
with the exception that only CONTAINER tags have the capability to contain other CONTROL tags.
A Panel control is a good example of a control which can be a CONTAINER containing other CONTROLS such as Labels or TextBoxes. Look at the following example.
<TAG>
<EDITORLAYOUT HEIGHT=50 WIDTH=200>
<CONTAINER NAME="Panel1" TYPE="Panel" WIDTH=150 HEIGHT=50>
<CONTROL NAME="lblCode" TYPE="label" CAPTION="Code" DOWN=20 RIGHT=20 WIDTH=70>
<CONTROL NAME="txtCode" TYPE="TextBox" ANCHOR="lblCode" CORNER="NE" WIDTH="30">
</CONTAINER>
</EDITORLAYOUT>
</TAG>
You can name the above template MYTAG.VTM and test it by attempting to edit an
empty <MYTAG> tag. The MYTAG dialog demonstrates how controls can act as
containers. Only a few controls can be containers :
- TabDialog - A tab dialog control capable of containing TabPage container controls.
- TabPage - Only used inside a TabDialog container control.
- Panel - A general purpose panel container control. Can contain any regular
or container controls.
You must have already noticed that the control represented by a CONTROL or a CONTAINER
tag is defined by the TYPE attribute. We can also see that WIDTH and HEIGHT attributes
determine the size.
The ANCHOR, and CORNER attributes determine the point relative to which the control
is positioned. The ANCHOR can be specified as the name of any control that was already
laid down. The corner specifies the corner of the anchor control to be used for
positioning. The possible choices are NE, NW, SE, SW. The DOWN and RIGTH
attributes then specify the pixel offset from the anchor control.
CONTROL\CONTAINER attributes |
TYPE |
Type of the control\container.
Available control types are :
- Label
- TextBox
- CheckBox
- RadioGroup
- DropDown
- TextArea
- FontPicker
- ColorPicker
- Image
- FileBrowser
- SQLTextArea
Available container types are:
|
NAME |
Name of the control. |
ANCHOR |
(Optional) The name of the control relative top which control is positioned. If omitted, control is positioned relative to the upper left corner of its container. |
CORNER |
(Optional) Corner of the ANCHOR control relative to which offset position is calculated (NW,NE, SW, SE). Default is NW, the upper-left corner. |
DOWN |
Offset in pixels down from the anchor point (corner). |
RIGHT |
Offset in pixels right from the anchor point (corner). |
WIDTH |
Width of the control. Can be specified in three ways:
- in pixels (e.g. WIDTH=200)
- as name of another control (e.g. WIDTH="SomeControl") In this case the width of the specified control is used. The control must be already positioned.
- set to maximum (WIDTH="MAXIMUM") Stretches control to the right boundary of its container.
|
HEIGHT |
Height of the control. Can be specified in three ways:
- in pixels (e.g. HEIGHT =200)
- as name of another control (e.g. HEIGHT ="SomeControl") In this case the height of the specified control is used. The control must be already positioned.
- - set to maximum (HEIGHT ="MAXIMUM") Stretches control to the bottom boundary of its container.
|
LFWIDTH |
Width of the control used when user’s system is set to use large fonts. |
LFHEIGHT |
Height of the control used when user’s system is set to use large fonts. |
MAXWIDTHPADDING |
Used with WIDTH=MAXIMUM. Specifies the padding in pixels from the container’s right boundary. |
MAXHEIGHTPADDING |
Used with HEIGHT=MAXIMUM. Specifies the padding in pixels from the container’s bottom boundary. |
|
|
REFERENCE: <CONTAINER TYPE="TabDialog"
<CONTAINER TYPE="TabDialog" … |
TabDialog control is a special container control, as it can only contain <CONTAINER TYPE="TabPage"> tags. This is natural as one needs to specify the tab pages before embedding more controls on the tab dialog itself.
|
EXAMPLE
<CONTAINER NAME="MainTabDialog" TYPE="TabDialog" WIDTH=MAXIMUM HEIGHT=MAXIMUM>
<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="TEXTAREA Tag">
... embeded controls
</CONTAINER>
<CONTAINER NAME="TabPage2" TYPE="TabPage" CAPTION="Content">
... embeded controls
</CONTAINER>
</CONTAINER>
REFERENCE: <CONTAINER TYPE="TabPage"
<CONTAINER TYPE="TabPage" ... |
TabPage control is also a bit special as it can only be contained inside a TabDialog CONTAINER control. |
CAPTION |
Caption displayed on the top of the tab. |
EXAMPLE
<CONTAINER NAME="MainTabDialog" TYPE="TabDialog" WIDTH=MAXIMUM HEIGHT=MAXIMUM>
<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="TEXTAREA Tag">
... embeded controls
</CONTAINER>
<CONTAINER NAME="TabPage2" TYPE="TabPage" CAPTION="Content">
... embeded controls
</CONTAINER>
</CONTAINER>
REFERENCE: <CONTAINER TYPE="Panel"
<CONTAINER TYPE="Panel" … |
Panel is the most common container control. Panel can contain any control or container except TabPage which is restricted to TabDialog.
|
CAPTION |
Caption displayed in the upper left corner of the panel boundary. |
EXAMPLE
<EDITORLAYOUT HEIGHT=225>
<CONTAINER NAME="MainTabDialog" TYPE="TabDialog" WIDTH=MAXIMUM HEIGHT=MAXIMUM>
<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="MYTAG Tag">
<CONTAINER NAME="Panel1" TYPE="Panel" DOWN=5 RIGHT=10 WIDTH="MAXIMUM" HEIGHT=125>
<CONTROL NAME="lblSource" TYPE="Label" CAPTION="Source:" DOWN=17 RIGHT=10 WIDTH=50>
<CONTROL NAME="txtSource" TYPE="TextBox" ANCHOR="lblSource" CORNER="NE" WIDTH="MAXIMUM">
<CONTROL NAME="lblAlign" TYPE="Label" CAPTION="Align:" ANCHOR="lblSource" CORNER="SW" DOWN=11 WIDTH=50>
<CONTROL NAME="dropAlign" TYPE="DropDown" ANCHOR="lblAlign" CORNER="NE" WIDTH=100>
<ITEM VALUE="TOP" CAPTION="TOP" >
<ITEM VALUE="MIDDLE" CAPTION="MIDDLE" SELECTED>
<ITEM VALUE="BOTTOM" CAPTION="BOTTOM" >
</CONTROL>
</CONTAINER>
<CONTAINER NAME="Panel2" TYPE="Panel" CAPTION=" Panel 2 " ANCHOR="Panel1" CORNER="SW"
DOWN=5 WIDTH="MAXIMUM" HEIGHT=MAXIMUM
</CONTAINER>
</CONTAINER>
<CONTAINER NAME="Advanced" TYPE="TabPage" CAPTION="Advanced">
</CONTAINER>
</CONTAINER>
</EDITORLAYOUT>
REFERENCE: <CONTROL TYPE="Label"
<CONTROL TYPE="Label" … |
Panel is the most common container control. Panel can contain any control or container except TabPage which is restricted to TabDialog.
|
CAPTION |
The text displayed by the label. |
AUTOSIZE |
YES\NO. Automatically sizes the control to the text it contains. This option is overridden if WIDTH or HEIGHT are explicitly specified. |
TRANSPARENT |
YES\NO. Makes label trasparent. |
ALIGN |
LEFT\CENTER\RIGHT. Horizontal alignment of text in the label. |
VALIGN |
TOP\CENTER\BOTTOM. Horizontal alignment of text in the label. |
EXAMPLE
<CONTROL NAME="lblSource" TYPE="Label" CAPTION="Source:" DOWN=17 RIGHT=10 WIDTH=50>
REFERENCE: <CONTROL TYPE="TextBox"
<CONTROL TYPE="TextBox" … |
A simple textbox control.
|
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. |
EDITABLE |
YES\NO. Enables disables editing. |
AUTOSELECT |
YES\NO. Decides whether contents get highlighted when cursor enters the textbox. |
MAXLENGTH |
Limits the amount of text in the textbox to a specific number of character. |
PASSWORDCHAR |
A character to be used to mask entered text. You can create a simple password box using PASWORDCHAR="*". |
CHARCASE |
NORMAL\UPPER\LOWER. Specifies whether entered text is automatically uppercased of lowercased. The default is NORMAL, preserving entered case. |
VALIGN |
TOP\CENTER\BOTTOM. Horizontal alignment of text in the label. |
EXAMPLE
<CONTROL NAME="lblSource" TYPE="Label" CAPTION="Source:" DOWN=17 RIGHT=10 WIDTH=50>
<CONTROL NAME="txtSource" TYPE="TextBox" VALUE="Some Value" ANCHOR="lblSource" CORNER="NE" WIDTH="MAXIMUM">
REFERENCE: <CONTROL TYPE="DropDown"
<CONTROL TYPE="DropDown" … |
A drop-down listbox. This tag requires <ITEM> sub-tags, which specify the list of items in the drop down. The item tag has CAPTION and VALUE attributes. CAPTION specifies the visible item text while VALUE specifies the underlying value for the option. SELECTED attribute specifies which item is initially selected. Then free-text is entered into an EDITABLE DropDown, the actual text is considered the value of the control.
Example:
<CONTROL NAME="dropTagOptions" TYPE="DropDown" WIDTH="200">
<ITEM CAPTION="option1" VALUE="Value1">
<ITEM CAPTION="option2" VALUE="Value2" SELECTED>
<ITEM CAPTION="option3" VALUE="Value3">
</CONTROL>
|
EDITABLE |
The EDITABLE attribute decides whether it behaves like an editable combo-box or a fixed listbox. |
EXAMPLE
<CONTROL NAME="lblAlign" TYPE="Label" CAPTION="Align:" ANCHOR="lblSource" CORNER="SW" DOWN=11 WIDTH=50>
<CONTROL NAME="dropAlign" TYPE="DropDown" ANCHOR="lblAlign" CORNER="NE" WIDTH=100>
<ITEM VALUE="TOP" CAPTION="TOP" >
<ITEM VALUE="MIDDLE" CAPTION="MIDDLE" SELECTED>
<ITEM VALUE="BOTTOM" CAPTION="BOTTOM" >
</CONTROL>
REFERENCE: <CONTROL TYPE="FontPicker"
<CONTROL TYPE="FontPicker" … |
A simple drop-down font picker.
|
EDITABLE |
The EDITABLE attribute decides whether a font name can be entered manually into the listbox. |
EXAMPLE
<CONTROL NAME="lblFace" TYPE="Label" CAPTION="Font:" DOWN=17 RIGHT=10 WIDTH=50>
<CONTROL NAME="fontFace" TYPE="FontPicker" ANCHOR="lblFace" CORNER="NE" WIDTH="MAXIMUM">
REFERENCE: <CONTROL TYPE="ColorPicker"
<CONTROL TYPE="ColorPicker" … |
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.
|
EXAMPLE
<CONTROL NAME="lblColor" TYPE="Label" CAPTION="Color:" ANCHOR="lblFace" CORNER="SW" DOWN=11 WIDTH=50>
<CONTROL NAME="colorColor" TYPE="ColorPicker" ANCHOR="lblColor" CORNER="NE" WIDTH="MAXIMUM">
REFERENCE: <CONTROL TYPE="CheckBox"
<CONTROL TYPE="CheckBox" … |
A simple checkbox control. Returns ‘true’ or ‘false’.
|
CAPTION |
Caption displayed next to the checkbox. |
CHECKED |
YES\NO. Specifies initial status. |
EXAMPLE
<CONTROL NAME="checkNoShading"TYPE="CheckBox" CAPTION=" No Shading"
ANCHOR="numWidth" CORNER="NE" DOWN=4 RIGHT=20 WIDTH=MAXIMUM>
REFERENCE: <CONTROL TYPE="RadioGroup"
<CONTROL TYPE="RadioGroup" … |
A set of radio buttons. This tag requires <ITEM> sub-tags, which specify the list of radio buttons. The item tag has CAPTION and VALUE attributes. CAPTION specifies the caption of the radio button, VALUE specifies the underlying value for the option. SELECTED attribute specifies which radio options should be preselected.
Example:
<CONTROL NAME="radioTagOptions" TYPE="RadioGroup" WIDTH="200">
<ITEM CAPTION="option1" VALUE="Value1">
<ITEM CAPTION="option2" VALUE="Value2" SELECTED>
<ITEM CAPTION="option3" VALUE="Value3">
</CONTROL>
|
EXAMPLE
<CONTROL NAME="radioNameConflict" TYPE="RadioGroup" CAPTION="Radio One"
ANCHOR="lblAccept" CORNER="SW" DOWN=35 HEIGHT=MAXIMUM WIDTH=MAXIMUM >
<ITEM VALUE="ERROR" CAPTION="ERROR - The file will not be saved and Cold Fusion will return an error." SELECTED="TRUE">
<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>
REFERENCE: <CONTROL TYPE="TextArea"
<CONTROL TYPE="TextArea" … |
A simple multi-line text entry control.
|
SCROLLBAR |
NONE\HORIZONTAL\VERTICAL\BOTH. Specifies which scrollbars should be displayed.
|
WRAP |
YES\NO. Enables wrapping of text. |
EXAMPLE
<CONTROL NAME="txtContent" TYPE="TextArea" DOWN=5 RIGHT=5
WIDTH=MAXIMUM HEIGHT=MAXIMUM MAXWIDTHPADDING=5 MAXHEIGHTPADDING=5>
REFERENCE: <CONTROL TYPE="SQLTextArea"
<CONTROL TYPE="SQLTextArea" … (Cold Fusion Studio ONLY) |
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.
|
SCROLLBAR |
NONE\HORIZONTAL\VERTICAL\BOTH. Specifies which scrollbars should be displayed.
|
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.
|
WRAP |
YES\NO. Enables wrapping of text. |
EXAMPLE
<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="CFQUERY Tag">
<CONTAINER NAME="Panel1" TYPE="Panel" DOWN=5 RIGHT=10 WIDTH="MAXIMUM" HEIGHT=80>
<CONTROL NAME="lblQueryName" TYPE="Label" CAPTION="Query Name:" DOWN=17 RIGHT=10 WIDTH=80>
<CONTROL NAME="lblDataSource" TYPE="Label" CAPTION="Data Source:" ANCHOR="lblQueryName" CORNER="SW" DOWN=10 RIGHT=0 WIDTH=80>
<CONTROL NAME="txtQueryName" TYPE="TextBox" ANCHOR="lblQueryName" CORNER="NE" WIDTH=130>
<CONTROL NAME="txtDataSource" TYPE="TextBox" ANCHOR="lblDataSource" CORNER="NE" WIDTH=130>
<CONTROL NAME="lblMaxRows" TYPE="Label" CAPTION="Max Rows:" ANCHOR="txtQueryName" CORNER="NE" DOWN=0 RIGHT=10 WIDTH=70>
<CONTROL NAME="lblTimeout" TYPE="Label" CAPTION="Timeout:" ANCHOR="txtDataSource" CORNER="NE" DOWN=0 RIGHT=10 WIDTH=70>
<CONTROL NAME="numMaxRows" TYPE="TextBox" ANCHOR="lblMaxRows" CORNER="NE" WIDTH=30>
<CONTROL NAME="numTimeout" TYPE="TextBox" ANCHOR="lblTimeout" CORNER="NE" WIDTH=30>
<CONTROL NAME="checkDebug" TYPE="CheckBox" CAPTION="Print debug info"
ANCHOR="numTimeout" CORNER="NE" RIGHT=10 DOWN=4 WIDTH=MAXIMUM>
</CONTAINER>
<CONTROL NAME="lblSQLStatement" TYPE="Label" CAPTION="SQL Statement:"
ANCHOR="Panel1" CORNER="SW"DOWN=10 RIGHT=0 WIDTH=110>
<CONTROL NAME="txtSQLStatement" TYPE="SQLTextArea"
ANCHOR="lblSQLStatement" CORNER="SW" DOWN="8" WIDTH=MAXIMUM HEIGHT=MAXIMUM
DSNAMECONTROL="txtDataSource" QUERYNAMECONTROL="txtQueryName">
</CONTAINER>
REFERENCE: <CONTROL TYPE="FileBrowser"
<CONTROL TYPE="FileBrowser" … |
A textbox used to enter a file path. The control contains two toolbar buttons proving accessibility to local and remote file\directory browsing.
|
CAPTION |
The window caption that should displayed in the file\directory browsing dialogs. For example: CAPTION="Select File You Want Uploaded".
|
FILTER |
The file filter that should be used by the file\directory browsing dialogs. For example : FILTER="*.gif;*.jpeg;*.jpg".
|
DIRONLY |
YES\NO. Specified that a directory is being selected. This option will convert the file dialogs accessible from the browse buttons to become directory-browsing dialogs. By default, file-browsing is assumed. |
FILENAMEONLY |
YES\NO. Specified 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. The attribute is irrelevant when the DIRONLY attribute is used.
|
RELATIVE |
YES\NO. Instructs the control to calculate the relative path when a file or a directory 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.
|
EXAMPLE
<CONTROL NAME="lblSource" TYPE="Label" CAPTION="Source:" DOWN=17 RIGHT=10 WIDTH=60>
<CONTROL NAME="txtSource" TYPE="FileBrowser"
ANCHOR="lblSource" CORNER="NE" WIDTH="MAXIMUM"
RELATIVE FILTER="*.htm;*.html;*.cfml;*.cfm;*.asp" >
REFERENCE: <CONTROL TYPE="Image"
<CONTROL TYPE="Image" … |
An image control capable of containing BMP images.
|
FILEPATH |
Path to the image file relative from the editor template.
|
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 |
YES\NO. Centers the image
|
EXAMPLE
<CONTROL NAME="imgApplet" TYPE="Image" FILEPATH="Images/Applet.bmp"
DOWN=10 RIGHT=10 AUTOSIZE="Yes">
(Editors contributed by Kevin Davis and Wil Genovese)