AntForm home

Main
About
Installation
Usage - AntForm
Usage - AntMenu
Screenshots
Downloading
Getting help

News
Recent

AntForm

Description

Provides a swing-based form for modifying a group of properties exposed through the task parameters. The form has a top label with a title, under which are laid out labels and components in two aligned columns. For each component that targets a property, a descriptive text is provided to assist the user interaction by prompting for specific information. At the end of the form, by default, two buttons are laid out, one for resetting the content of the form to the state where it was before any editing occurred, the other to approve the contents for saving or for a subsequent task/target. You can change this default by using controlbar

Parameters

Attribute	Description	Required
title	title of the form window and also set in a label at the top of the form. Defaults to `Ant Controls`	No
image	filepath of the image displayed alongside the title in the top panel of the form.	No
width	Width of the form window in pixels	No
height	Height of the form window in pixels	No
okMessage	Label text used for the approval button of the form. If set to an empty string, the button won't be displayed. Defaults to `OK`. Deprecated: use buttons in a controlbar instead.	No
resetMessage	Label text used for the cancel button of the form. If set to an empty string, the button won't be displayed. Defaults to `Reset` Deprecated: use buttons in a controlbar instead.	No
save	Name of a file in which to save the properties edited in the form.	No
stylesheet	filepath of a stylesheet to affect widget styles	No
focus	Name of the field on which to focus when the form is shown. Can be not only the name of a a field, but also the name of a button such as the okButton or resetButton. *Not supported anymore:* use nested elements `focus` attribute instead.	No
nextTarget	Next target to call upon validation for wizard mode. Deprecated: use buttons in a controlbar instead.	No
previousTarget	Previous target to call upon reset for wizard mode. Deprecated: use buttons in a controlbar instead.	No
lookAndFeel	Classname of a java look and feel implementation. The look and feel will carry over to other AntForm tasks if not reset.	No
icon	The icon file to use (JPG, GIF, PNG). Valid only on Windows platforms.	No
showwhenempty	This boolean (true/false) specifies whether the form should be displayed if no nested widget is to be displayed. This can happen if there are no nested elements or if all of them are hidden due to their if/unless attributes. Defaults to false.	No
loop	This boolean (true/false) specifies whether the form should be shown again after action (ok, cancel, call target). It can be useful for a main window to which we come back after each action. The loop is exited by clicking on a button (or menu) which has its `loopexit` attribute set to true. Defaults to false.	No

Parameters specified as nested elements

controlbar

Bottom button bar usually used to validate, cancel or reset a form. By default, this bar will contain a "Reset" button and a "Ok" button. If you do not want any button at the bottom of the form, use an emtpy controlbar
See ButtonBar for full usage documentation.

separator

Add a separator line to divide the form into sections.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No

label

Add a message box to the form. Maps to a non-editable multiline text field with automatic line wrapping.The text content of the label tag sets the message text.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No

textProperty

Assign editing of a property to a single-line text field.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
columns	Number of columns used to display the field.	No
editable	Sets property to be editable by default, non-editable otherwise	No
password	Sets the field to a password field that hides user entry. Defaults5to `false`	No
fontname	The font to use. The list of avaliable font family on the current platform can be obtained by using the dummy `printavailablefontfamilies` widget	No
fontstyle	The font style to use. This is a combination (comma/space separated list) of `plain`, `italic` and `bold`. default is `plain`	No
fontsize	The size of the font to use	No
Required	Postpones validation of the form if the property value is null.	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

numberProperty

Needs java 1.4 or bove.

spinner field used to set numeric property values, with controls to increment or decrement the value.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
editable	Sets property to be editable by default, non-editable otherwise	No
min	The minimum value that the field can take. Defaults to 0.	No
max	The maximum value that the field can take. Defaults to 100.	No
step	The increment step that the field takes when incremented via its controls. Defaults to 1.	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

listProperty

Needs java 1.4 or bove.

spinner field used to constrain a property to a list of values.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
editable	Sets property to be editable by default, non-editable otherwise	No
values	The list of values that the property can take.	Yes
separator	The separator for delimiting values in the `values` attribute. Defaults to ",".	No
escapeSequence	The escape sequence that prefixes the separator when the separator is part of a value. Defaults to "\".	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

multiLineTextProperty

Like textProperty, only uses a multiline text field to edit the targeted property.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
columns	Number of columns used to display the field.	No
rows	Number of rows used to display the field.	No
editable	Sets property to be editable by default, non-editable otherwise	No
fontname	The font to use. The list of avaliable font family on the current platform can be obtained by using the dummy `printavailablefontfamilies` widget	No
fontstyle	The font style to use. This is a combination (comma/space separated list) of `plain`, `italic` and `bold`. default is `plain`	No
fontsize	The size of the font to use	No
Required	Postpones validation of the form if the property value is null.	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

table

Provide a table for showing data that can be represented as a two-dimensional array of values. Since the overall data is mapped to a single value, column separator and row separator characters are used. The escape sequence for introducing a separator into the data fields is the "\" character.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
editable	Specify wether the table can be edited. Defaults to `true`	No.
rowSeparator	Character used to separate row data in the property string. defaults to "`;`"	No
columnSeparator	Character used to separate row data in the property string. defaults to "`;`"	No
columns	String used to construct the column header data.	Yes
width	Width in pixels to set the preffered table size. Both width and height must be set and > 0 to be effective.	No
height	Height in pixels to set the preffered table size. Both width and height must be set and > 0 to be effective.	No
columnWidth	Size in pixels to set the preffered column width.	No
bestFitColumns	Specify wether to set each column width according to the content. Defaults to `false`.	No
data	*Deprecated*. Use the specified property value instead (as for other components).	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

cancel

Add a cancel button to the bottom button bar.
Deprecated: use buttons in a controlbar instead.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text labelling the cancel button. If set to an empty string, the button won't be displayed.	Yes

tab

Add a tab pane to which subsequent widgets will be added.

Note 1: the tab element is not used in the intuitive nested sense. Do not try to add widgets directly to the tab, but rather add widget property fields after a tab declaration. In a sequential manner the property widgets will be added to the tabbed pane.

Note 2: when using tabs, the first element in antform should always be a tab.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label identifying the current tab.	Yes

selectionProperty

Provide a selection list of values that can be assigned to the targeted property. Functions just like listProperty, only maps to a drop-down listbox and not a spinner component.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
values	list of values available for selecting the property value. Use commas to separate the values by default, though you can specify another separator with the `separator` attribute.	No
separator	Specify a different separator from the default comma.	No
escapeSequence	The escape sequence that prefixes the separator when the separator is part of a value. Defaults to "\".	No
editable	Sets property to be editable by default, non-editable otherwise	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

radioSelectionProperty

Like selectionProperty, only is rendered with radio button fields instead of a drop-down list.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
values	list of values available for selecting the property value. Use commas to separate the values by default, though you can specify another separator with the `separator` attribute.	No
separator	Specify a different separator from the default comma.	No
escapeSequence	The escape sequence that prefixes the separator when the separator is part of a value. Defaults to "\".	No
editable	Sets property to be editable by default, non-editable otherwise	No
columns	The number of columns to use. Defaults to 1.	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

checkSelectionProperty

Like selectionProperty, only is rendered with checkBox fields instead of a drop-down list. In addition, the property is get and set via a list of values separated by the specified separator since multiple selection is allowed with checkBoxes. Think of the checkSelectionProperty as a multi-select list.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
values	list of values available for selecting the property value. Use commas to separate the values by default, though you can specify another separator with the `separator` attribute.	No
separator	Specify a different separator from the default comma.	No
escapeSequence	The escape sequence that prefixes the separator when the separator is part of a value. Defaults to "\".	No
editable	Sets property to be editable by default, non-editable otherwise	No
columns	The number of columns to use. Defaults to 1.	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

dateProperty

Needs java 1.4 or bove.

Provide a calendar control for assigning a date to a property.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
dateFormat	date format for transforming to and from dates and strings. Defaults to `dd/MM/yyyy`	No
editable	Sets property to be editable by default, non-editable otherwise	No
fontname	The font to use. The list of avaliable font family on the current platform can be obtained by using the dummy `printavailablefontfamilies` widget	No
fontstyle	The font style to use. This is a combination (comma/space separated list) of `plain`, `italic` and `bold`. default is `plain`	No
fontsize	The size of the font to use	No
Required	Postpones validation of the form if the property value is null.	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

booleanProperty

Provide an input field for a property to be assigned to true if checked, unassigned otherwise. If the property has already been set prior to the form being called, it will be set to true if checked or false otherwise.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
editable	Sets property to be editable by default, non-editable otherwise	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

fileSelectionProperty

provide an input field for selecting files and directories

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Text of the label used to prompt for information	Yes
property	Name of the property to be set by this field of the form	Yes
editable	Sets property to be editable by default, non-editable otherwise	No
columns	Number of columns with which to display the text field of the file selection widget. Defaults to 34.	No
directoryChooser	if set to `true`, allows only for selection of directories, not individual files. Defaults to `false`	No
Required	Postpones validation of the form if the property value is null.	No
tooltip	Text to display in a tooltip box attached to this widget.	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Default to false.	No

linkBar

Deprecated. Use ButtonBar instead.

ButtonBar

Provide a bar with a horizontal layout of buttons to other targets. This type has no attributes and is basically a holder for button types.

link

Deprecated. Use Button instead

button

Add a button that calls other target in the current Ant process.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
label	Button label	Yes
target	Name of the target to call when clicking this button. Not used when type="reset"	No
type	Type of action performed when clicking on this button. Valid action types are: `ok`: validate form properties and close window `cancel`: do not validate form properties and close window `reset`: reset form properties and keep window open Default action is "ok".	No
background	Wether to run the target in a separate thread or not. The ant project in which antform is used will not exit until the created thread is finished. Defaults to `false`	No
newproject	Wether to run the target in a separate project (as `antcall` does) or not. Setting this attribute to `false` allows to set properties in the called target that will be reusable in the calling target. Defaults to `true` (simulates `antcall`)	No
focus	Specifies that this widget should get the focus when the form is shown. If several widgets have this set to true, the first one will get the focus. Defaults to false.	No
loopexit	When set to true, clicking on this component will exit the form loop (see the loop attribute of antmenu/antform). Defaults to false.	No

antMenuItem

Provide a menu bound to the frame menu bar and recursively hosting other AntMenuItems, each of which links to an Ant target.

Attribute	Description	Required
if	specify a property that must be set for this widget to exist.	No
unless	specify a property that must NOT be set for this widget to exist.	No
target	Name of the target to which the AntMenuItem links.	No
name	Label of the file menu item	Yes
type	Type of action performed when clicking on this button. Valid action types are: `ok`: validate form properties and close window `cancel`: do not validate form properties and close window `reset`: reset form properties and keep window open Default action is "ok".	No
background	Wether to run the target in a separate thread or not. The ant project in which antform is used will not exit until the created thread is finished. Defaults to `false`	No
newproject	Wether to run the target in a separate project (as `antcall` does) or not. Setting this attribute to `false` allows to set properties in the called target that will be reusable in the calling target. Defaults to `true` (simulates `antcall`)	No
loopexit	When set to true, clicking on this component will exit the form loop (see the loop attribute of antmenu/antform). Defaults to false.	No

printAvailableFontFamilies

This empty element will not display anything on the resulting form. Instead, it will print out the list of available font families on the console.

Examples

The following example generates properties for sending a mail.


<antform title="Send Mail" 
	save="properties.txt"
	image="doc/images/testlogo.jpg">
	<label>To send a mail, use the following form. Pick a recipient,
 type a subject and a body...the script will do the rest.</label>
	<selectionProperty label="Recipient: " 
	property="recipient" 
	values="address1@somewhere.com; address2@somewhere.com; address4@somewhere.com" 
	separator=";"/>
	<textProperty label="Subject : " property="subject" />
	<multilineTextProperty label="Message body: "
		property="body"/>
	<booleanProperty label="Send immediately: " property="send"/>
</antform>

The AntForm Team - sardak@users.sourceforge.net- updated: 31/01/2009