Types of control
Published 23 January 2013
SQL Scripts Manager enables you to define a graphical user interface for a script. You specify the interface design in the XML script file (extension .rgtool), using <control> elements.
This page describes how to use <control> elements in detail, covering each possible control type, sub-controls, and other attributes of <control> elements.
For more information about the structure of a complete XML script file, including how to place <control> elements in blocks, see The SQL Scripts Manager XML schema.
XML is case sensitive; you must use the exact text shown when creating your own XML script files.
<control> attributes
Every instance of a <control> element can have the following attributes:
- type [required]
Describes the type of the control. See the following sections for more information about each control type. Possible values are:
Control type
Description
Control type
Description
Check box
Selectable list box control (single or multi selection)
Combo box (fixed or editable)
File browser dialog box
Combo boxes for selecting an instance and specifying a new database
Text box for password entry
Combo boxes for selecting an instance and database, and specifying a new table
Group of option buttons
Combo boxes for selecting an instance and database
Save file dialog box
Text box and browse button, for folder selection
Combo box for selecting an instance, and text boxes for connection credentials
A UI heading label
Combo boxes for selecting an instance, database, and table
Text box that accepts only integers
Text box
- id [optional]
The control id is used to read the value of the control in your script code.
See the <script> element for information about how to use control id's in script code.
If you don't provide a value for the id attribute, SQL Scripts Manager will generate an identifier automatically. These identifiers can then be used to refer to the control in preset files.
- label [optional]
A string placed to the left side of the control on the user interface.
For the controls of type check (check box), the label string is placed to the right of the check box.
Default sub-controls
The following sub-controls (elements) can be specified as children of any type of control:
- <font> [optional]
This element changes the font used to render the parent control. This setting will not affect any other controls.
Attributes:
- name: font name (default is 'Tahoma')
- size: the point size of the font (default is 8.25)
- style: the font style (bold, italic, regular, strikethrough, underline) (default is 'regular')
- <help>
Adds an interactive help button ( ) to the control. When a user clicks a help button, a help window is displayed.
Use help buttons to help explain how a particular control should be used.
Sub-elements:
- <title>: the title of the help window
<text>: the help text displayed. The help text can include simple HTML tags (for example, <i>, <b>, <p>, <ul>, <li>, <h1>, h2>, <pre>) for formatting the text in the help window.
In most cases, you will want to identify your help text as CDATA (unparsed character data), by placing it between <![CDATA[ and ]]> tags.
Example:
<control type="check" id="rememberpassword" label="Remember password"> <help> <title>Remember password</title> <text><![CDATA[ <p>If you select this check box, your <i>password</i> is persisted in the registry in <b>encrypted form</b>. On subsequent runs of the script, the password is completed automatically. See <a href="http://localhost/index.htm> this document</a> for more information.</p> ]]> </text> </help> </control>
check
Creates a check box.
The label for a check box is positioned to the right of the control.
Example
<control type="check" id="rememberpassword" label="Remember password" />
combo
Creates a combo box; you can choose whether the combo box is editable, or fixed.
Sub-elements
- width: the width of the control in pixels (default is 200)
- editable: if 'true', the combo box includes a text box that the user can type into (default is 'false')
- list / item: each item listed in the combo box
Example
<control type="combo" id="Databases"> <width>220</width> <editable>true</editable> <list> <item>SYSTEM_DATABASES</item> <item>USER_DATABASES</item> <item>ALL_DATABASES</item> </list> </control>
createdatabase
Creates a SQL Server instance-selection control that includes a combo box for selecting a database on the specified SQL Server instance.
Use this control when you need to specify a name for a database that does not have to exist on the instance (for example, when the database will be created when the script is run).
Example
<control type="createdatabase" id="connection" />
createtable
Creates a SQL Server instance-selection control that includes combo boxes for selecting a database and a table.
Use this control when you need to specify a name for a table that may not exist in the specified database (for example, if the table will be created when the script runs).
<control type="createtable" id="connection" />
database
Creates a SQL Server instance-selection control that includes a combo box for selecting an existing database from the specified SQL Server instance.
This control checks that the selected database exists on the server, before running the script.
Example
<control type="database" id="connection" />
folderbrowser
Creates a control that enables the user to select a folder.
The control comprises a text box and a browse button: the browse button launches a folder browser dialog box, and the text box enables the user to type a folder path rather than using the browser dialog box.
Sub-elements
- title: the title of the folder browser dialog box
Example
<control type="folderbrowser" id="folder"> <title>Select a destination folder</title> </control>
header
Creates a label on the user interface.
Use this control to create headings between other controls on the user interface. This may be useful if you have created a large number of controls, and need to organize them more clearly.
Use the font sub-control to change the font used to render the heading.
Example
<control type="header" label="Database location"> <font name="Arial" size="12" style="bold" /> </control>
integer
Creates a text box control that accepts only integer numbers.
Sub-elements
- min: the lower bound for accepted values
- max: the upper bound for accepted values
Example
<control type="integer" id="percentage" label="Fill factor (%):"> <min>0</min> <max>100</max> </control>
list
Creates a selectable list box control. You can choose between single and multi selection.
Sub-elements
- mode: specifies the selection behavior for the list box. Possible values are:
- none: no items can be selected
- one: only one item can be selected
- multisimple: multiple items can be selected
- multiextended: multiple items can be selected, optionally while using the SHIFT, CTRL, and arrow keys
- height: the height of the list box control in pixels (default is 20)
- width: the width of the list box control in pixels (default is 200)
- list / item: a list of items that are shown in the combo box
Example
<control type="list" id="options"> <height>100</height> <width>220</width> <mode>one</mode> <list> <item>SYSTEM_DATABASES</item> <item>USER_DATABASES</item> <item>ALL_DATABASES</item> </list> </control>
openfile
Launches a file browser dialog box.
Sub-elements
- title: the title of file browser dialog box (default is 'Title')
- filter: the filter pattern for the file browser dialog box (default is 'All Files (*.*)|*.*')
Write filter patterns using the format: <text1>|<file pattern1>|<text2>|<file pattern2>[...]
Example
<control type="openfile" id="file"> <title>Source file...</title> <filter>CSV Files (*.csv)|*.csv|All Files (*.*)|*.*</filter> </control>
password
Creates a password entry text box.
Example
<control type="password" id="password" label="Password:" />
radio
Creates a group of option buttons (also known as radio buttons).
Sub-elements
- list / item: a list of option button items
Example
<control type="radio" id="Options"> <list> <item>Physical only</item> <item>Physical and data purity</item> <item>Physical, data purity, and extended checks</item> </list> </control>
savefile
Launches a Save File dialog box.
Sub-elements
- title: the title of the dialog box (default is 'Title')
- filter: the filter pattern for the dialog box (default is 'All Files (*.*)|*.*')
Write filter patterns using the format: <text1>|<file pattern1>|<text2>|<file pattern2>[...]
Example
<control type="savefile" id="file"> <filter>CSV Files (*.csv)|*.csv|All Files (*.*)|*.*</filter> <title>Destination file...</title> </control>
server
Creates a composite control for selecting a SQL Server instance and providing the connection credentials.
Example
<control type="server" id="connection" />
table
Creates a SQL Server instance-selection control that includes combo boxes for selecting a database and a table.
Use this control to select an existing database table.
Example
<control type="table" id="connection" />
text
Creates a text box.
Sub-elements
- height: the height of the text box, in lines. This setting is only used if multiline is set to 'true' (default is 1)
- width: the width of the text box in pixels
- maxlength: the maximum text length in characters (default is 20)
- multiline: specifies whether the text box will accept multiple lines of text ('true' or 'false') (default is false)
- allowEmpty: specifies whether an empty text box is considered valid ('true' or 'false')
Example
<control type="text" id="note" label="Note:"> <height>10</height> <width>220</width> <maxlength>2048</maxlength> <multiline>true</multiline> <allowEmpty>true</allowEmpty> </control>