com.itmill.toolkit.ui
Class Form

java.lang.Object
  com.itmill.toolkit.terminal.Identifiable
      com.itmill.toolkit.ui.AbstractComponent
          com.itmill.toolkit.ui.AbstractField
              com.itmill.toolkit.ui.Form

All Implemented Interfaces:

Buffered, BufferedValidatable, Item, Item.Editor, Item.Viewer, Property, Property.Editor, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer, Validatable, MethodEventSource, Paintable, VariableOwner, Component, Component.Focusable, Field, EventListener

public class Form
extends AbstractField
implements Item.Editor, Buffered, Item, Validatable

Form component provides easy way of creating and managing sets fields.

Form is a container for fields implementing Field interface. It provides support for any layouts and provides buffering interface for easy connection of commit and discard buttons. All the form fields can be customized by adding validators, setting captions and icons, setting immediateness, etc. Also direct mechanism for replacing existing fields with selections is given.

Form provides customizable editor for classes implementing Item interface. Also the form itself implements this interface for easier connectivity to other items. To use the form as editor for an item, just connect the item to form with setItemDataSource(Item). If only a part of the item needs to be edited, setItemDataSource(Item,Collection) can be used instead. After the item has been connected to the form, the automatically created fields can be customized and new fields can be added. If you need to connect a class that does not implement Item interface, most properties of any class following bean pattern, can be accessed trough BeanItem.

Since:

3.0

Version:

4.1.4

Author:

IT Mill Ltd.

Nested Class Summary

Nested classes/interfaces inherited from class com.itmill.toolkit.ui.AbstractField

AbstractField.ReadOnlyStatusChangeEvent

Nested classes/interfaces inherited from interface com.itmill.toolkit.data.Buffered

Buffered.SourceException

Nested classes/interfaces inherited from interface com.itmill.toolkit.data.Item

Item.Editor, Item.PropertySetChangeEvent, Item.PropertySetChangeListener, Item.PropertySetChangeNotifier, Item.Viewer

Nested classes/interfaces inherited from interface com.itmill.toolkit.ui.Field

Field.ValueChangeEvent

Nested classes/interfaces inherited from interface com.itmill.toolkit.ui.Component

Component.ErrorEvent, Component.ErrorListener, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.itmill.toolkit.terminal.Paintable

Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener

Nested classes/interfaces inherited from interface com.itmill.toolkit.data.Property

Property.ConversionException, Property.Editor, Property.ReadOnlyException, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer

Constructor Summary

Form()
Contructs a new form with default layout.

Form(Layout formLayout)
Contructs a new form with given layout.

Form(Layout formLayout, FieldFactory fieldFactory)
Contructs a new form with given layout and FieldFactory.

Method Summary

void	addField(Object propertyId, Field field) Adds the field to form.
boolean	addItemProperty(Object id, Property property) Adds a new property to form and create corresponding field.
void	addValidator(Validator validator) Adds a new validator for this object.
void	attach() Notifies the component that it is connected to an application
void	commit() Updates all changes since the previous commit to the data source.
void	detach() Notifies the component that it is detached from the application.
void	discard() Discards all changes since last commit.
void	focus() Focuses the first field in the form.
Field	getField(Object propertyId) Gets the field identified by the propertyid.
FieldFactory	getFieldFactory() Get the field factory of the form.
Item	getItemDataSource() Gets the Item serving as the data source of the viewer.
Property	getItemProperty(Object id) The property identified by the property id.
Collection	getItemPropertyIds() Gets the collection of IDs of all Properties stored in the Item.
Layout	getLayout() Gets the layout of the form.
String	getTag() Gets the UIDL tag corresponding to the component.
Class	getType() Gets the field type.
Collection	getValidators() Gets the Lists all validators currently registered for the object.
Collection	getVisibleItemProperties() Returns the visibleProperties.
boolean	isInvalidAllowed() Checks the validabtable object accept invalid values.
boolean	isModified() Tests if the value stored in the object has been modified since it was last updated from the data source.
boolean	isReadThrough() Tests if the object is in read-through mode.
boolean	isValid() Tests the current value of the object against all registered validators
boolean	isWriteThrough() Tests if the object is in write-through mode.
void	paintContent(PaintTarget target) Paints any needed component-specific things to the given UIDL stream.
boolean	removeAllProperties() Removes all properties and fields from the form.
boolean	removeItemProperty(Object id) Removes the property and corresponding field from the form.
void	removeValidator(Validator validator) Removes a previously registered validator from the object.
Select	replaceWithSelect(Object propertyId, Object[] values, Object[] descriptions) Sets the form field to be selectable from static list of changes.
void	setFieldFactory(FieldFactory fieldFactory) Sets the field factory of Form.
protected void	setFormDataSource(Object data, Collection properties) Updates the internal form datasource.
protected void	setInternalValue(Object newValue) Sets the internal value.
void	setInvalidAllowed(boolean invalidValueAllowed) Should the validabtable object accept invalid values.
void	setItemDataSource(Item newDataSource) Sets the item datasource for the form.
void	setItemDataSource(Item newDataSource, Collection propertyIds) Set the item datasource for the form, but limit the form contents to specified properties of the item.
void	setLayout(Layout newLayout) Sets the layout of the form.
void	setReadOnly(boolean readOnly) Sets the component's to read-only mode to the specified state.
void	setReadThrough(boolean readThrough) Sets the object's read-through mode to the specified status.
void	setTabIndex(int tabIndex) Sets the Tabulator index of this Focusable component.
void	setVisibleItemProperties(Collection visibleProperties) Sets the visibleProperties.
void	setWriteThrough(boolean writeThrough) Sets the object's write-through mode to the specified status.
void	validate() Checks the validity of the validatable.

Methods inherited from class com.itmill.toolkit.ui.AbstractField

addListener, addListener, constructField, finalize, fireReadOnlyStatusChange, fireValueChange, getErrorMessage, getFocusableId, getPropertyDataSource, getTabIndex, getValue, isInvalidCommitted, isReadOnly, isRequired, removeListener, removeListener, setInvalidCommitted, setPropertyDataSource, setRequired, setValue, toString, valueChange

Methods inherited from class com.itmill.toolkit.ui.AbstractComponent

addListener, addListener, addListener, addListener, changeVariables, childRequestedRepaint, dependsOn, fireComponentErrorEvent, fireComponentEvent, fireEvent, getApplication, getCaption, getComponentError, getData, getDescription, getDirectDependencies, getIcon, getLocale, getParent, getStyle, getWindow, isEnabled, isImmediate, isVisible, paint, removeDirectDependency, removeListener, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintRequests, setCaption, setComponentError, setData, setDescription, setEnabled, setIcon, setImmediate, setLocale, setParent, setStyle, setVisible

Methods inherited from class com.itmill.toolkit.terminal.Identifiable

getDebugId, getUIID, setDebugId, setUIID

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.itmill.toolkit.ui.Field

getDescription, setCaption, setDescription

Methods inherited from interface com.itmill.toolkit.ui.Component

addListener, childRequestedRepaint, getApplication, getCaption, getIcon, getLocale, getParent, getStyle, getWindow, isEnabled, isVisible, removeListener, setEnabled, setParent, setStyle, setVisible

Methods inherited from interface com.itmill.toolkit.terminal.Paintable

addListener, paint, removeListener, requestRepaint, requestRepaintRequests

Methods inherited from interface com.itmill.toolkit.terminal.VariableOwner

changeVariables, dependsOn, getDirectDependencies, isImmediate, removeDirectDependency

Constructor Detail

Form

public Form()

Contructs a new form with default layout.

By default the form uses OrderedLayout with form-style.

Parameters:

formLayout - the layout of the form.

Form

public Form(Layout formLayout)

Contructs a new form with given layout.

Parameters:

formLayout - the layout of the form.

Form

public Form(Layout formLayout,
            FieldFactory fieldFactory)

Contructs a new form with given layout and FieldFactory.

Parameters:

formLayout - the layout of the form.

fieldFactory - the FieldFactory of the form.

Method Detail

getTag

public String getTag()

Description copied from class: AbstractComponent

Gets the UIDL tag corresponding to the component.

Specified by:

getTag in class AbstractComponent

Returns:

the component's UIDL tag as String

paintContent

public void paintContent(PaintTarget target)
                  throws PaintException

Description copied from class: AbstractComponent

Paints any needed component-specific things to the given UIDL stream. The more general AbstractComponent.paint(PaintTarget) method handles all general attributes common to all components, and it calls this method to paint any component-specific attributes to the UIDL stream.

Overrides:

paintContent in class AbstractField

Parameters:

target - the target UIDL stream where the component should paint itself to

Throws:

PaintException - if the paint operation failed.

commit

public void commit()
            throws Buffered.SourceException

Description copied from interface: Buffered

Updates all changes since the previous commit to the data source. The value stored in the object will always be updated into the data source when commit is called.

Specified by:

commit in interface Buffered

Overrides:

commit in class AbstractField

Throws:

Buffered.SourceException - if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

discard

public void discard()
             throws Buffered.SourceException

Description copied from interface: Buffered

Discards all changes since last commit. The object updates its value from the data source.

Specified by:

discard in interface Buffered

Overrides:

discard in class AbstractField

Throws:

Buffered.SourceException - if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

isModified

public boolean isModified()

Description copied from interface: Buffered

Tests if the value stored in the object has been modified since it was last updated from the data source.

Specified by:

isModified in interface Buffered

Overrides:

isModified in class AbstractField

Returns:

true if the value in the object has been modified since the last data source update, false if not.

isReadThrough

public boolean isReadThrough()

Description copied from interface: Buffered

Tests if the object is in read-through mode. If the object is in read-through mode, retrieving its value will result in the value being first updated from the data source to the object.

The only exception to this rule is that when the object is not in write-through mode and it's buffer contains a modified value, the value retrieved from the object will be the locally modified value in the buffer which may differ from the value in the data source.

Specified by:

isReadThrough in interface Buffered

Overrides:

isReadThrough in class AbstractField

Returns:

true if the object is in read-through mode, false if it's not.

isWriteThrough

public boolean isWriteThrough()

Description copied from interface: Buffered

Tests if the object is in write-through mode. If the object is in write-through mode, all modifications to it will result in commit being called after the modification.

Specified by:

isWriteThrough in interface Buffered

Overrides:

isWriteThrough in class AbstractField

Returns:

true if the object is in write-through mode, false if it's not.

setReadThrough

public void setReadThrough(boolean readThrough)

Description copied from interface: Buffered

Sets the object's read-through mode to the specified status. When switching read-through mode on, the object's value is updated from the data source.

Specified by:

setReadThrough in interface Buffered

Overrides:

setReadThrough in class AbstractField

Parameters:

readThrough - Boolean value to indicate if the object should be in read-through mode after the call.

setWriteThrough

public void setWriteThrough(boolean writeThrough)

Description copied from interface: Buffered

Sets the object's write-through mode to the specified status. When switching the write-through mode on, the commit operation will be performed.

Specified by:

setWriteThrough in interface Buffered

Overrides:

setWriteThrough in class AbstractField

Parameters:

writeThrough - Boolean value to indicate if the object should be in write-through mode after the call.

addItemProperty

public boolean addItemProperty(Object id,
                               Property property)

Adds a new property to form and create corresponding field.

Specified by:

addItemProperty in interface Item

Parameters:

id - ID of the new Property

property - the Property to be added and associated with the id

Returns:

true if the operation succeeded, false if not

See Also:

Item.addItemProperty(Object, Property)

addField

public void addField(Object propertyId,
                     Field field)

Adds the field to form.

The property id must not be already used in the form.

This field is added to the form layout in the default position (the position used by ComponentContainer.addComponent(Component) method. In the special case that the underlying layout is a custom layout, string representation of the property id is used instead of the default location.

Parameters:

propertyId - the Property id the the field.

field - the New field added to the form.

getItemProperty

public Property getItemProperty(Object id)

The property identified by the property id.

The property data source of the field specified with property id is returned. If there is a (with specified property id) having no data source, the field is returned instead of the data source.

Specified by:

getItemProperty in interface Item

Parameters:

id - identifier of the Property to get

Returns:

the Property with the given ID or null

See Also:

Item.getItemProperty(Object)

getField

public Field getField(Object propertyId)

Gets the field identified by the propertyid.

Parameters:

propertyId - the id of the property.

getItemPropertyIds

public Collection getItemPropertyIds()

Description copied from interface: Item

Gets the collection of IDs of all Properties stored in the Item.

Specified by:

getItemPropertyIds in interface Item

Returns:

unmodifiable collection containing IDs of the Properties stored the Item

removeItemProperty

public boolean removeItemProperty(Object id)

Removes the property and corresponding field from the form.

Specified by:

removeItemProperty in interface Item

Parameters:

id - ID of the Property to be removed

Returns:

true if the operation succeeded

See Also:

Item.removeItemProperty(Object)

removeAllProperties

public boolean removeAllProperties()

Removes all properties and fields from the form.

Returns:

the Success of the operation. Removal of all fields succeeded if (and only if) the return value is true.

getItemDataSource

public Item getItemDataSource()

Description copied from interface: Item.Viewer

Gets the Item serving as the data source of the viewer.

Specified by:

getItemDataSource in interface Item.Viewer

Returns:

data source Item

setItemDataSource

public void setItemDataSource(Item newDataSource)

Sets the item datasource for the form.

Setting item datasource clears any fields, the form might contain and adds all the properties as fields to the form.

Specified by:

setItemDataSource in interface Item.Viewer

Parameters:

newDataSource - The new data source Item

See Also:

Item.Viewer.setItemDataSource(Item)

setItemDataSource

public void setItemDataSource(Item newDataSource,
                              Collection propertyIds)

Set the item datasource for the form, but limit the form contents to specified properties of the item.

Setting item datasource clears any fields, the form might contain and adds the specified the properties as fields to the form, in the specified order.

See Also:

Item.Viewer.setItemDataSource(Item)

getLayout

public Layout getLayout()

Gets the layout of the form.

By default form uses OrderedLayout with form-style.

Returns:

the Layout of the form.

setLayout

public void setLayout(Layout newLayout)

Sets the layout of the form.

By default form uses OrderedLayout with form-style.

Parameters:

newLayout - the Layout of the form.

replaceWithSelect

public Select replaceWithSelect(Object propertyId,
                                Object[] values,
                                Object[] descriptions)

Sets the form field to be selectable from static list of changes.

The list values and descriptions are given as array. The value-array must contain the current value of the field and the lengths of the arrays must match. Null values are not supported.

Parameters:

propertyId - the id of the property.

values -

descriptions -

Returns:

the select property generated

attach

public void attach()

Notifies the component that it is connected to an application

Specified by:

attach in interface Component

Overrides:

attach in class AbstractField

See Also:

Component.attach()

detach

public void detach()

Notifies the component that it is detached from the application.

Specified by:

detach in interface Component

Overrides:

detach in class AbstractComponent

See Also:

Component.detach()

addValidator

public void addValidator(Validator validator)

Adds a new validator for this object.

Specified by:

addValidator in interface Validatable

Overrides:

addValidator in class AbstractField

Parameters:

validator - the new validator to be added.

See Also:

Validatable.addValidator(com.itmill.toolkit.data.Validator)

removeValidator

public void removeValidator(Validator validator)

Removes a previously registered validator from the object.

Specified by:

removeValidator in interface Validatable

Overrides:

removeValidator in class AbstractField

Parameters:

validator - the validator to remove.

See Also:

Validatable.removeValidator(com.itmill.toolkit.data.Validator)

getValidators

public Collection getValidators()

Gets the Lists all validators currently registered for the object.

Specified by:

getValidators in interface Validatable

Overrides:

getValidators in class AbstractField

Returns:

the Unmodifiable collection that holds all validators for the field.

See Also:

Validatable.getValidators()

isValid

public boolean isValid()

Tests the current value of the object against all registered validators

Specified by:

isValid in interface Validatable

Overrides:

isValid in class AbstractField

Returns:

true if all registered validators claim that the current value is valid, false otherwise.

See Also:

Validatable.isValid()

validate

public void validate()
              throws Validator.InvalidValueException

Checks the validity of the validatable.

Specified by:

validate in interface Validatable

Overrides:

validate in class AbstractField

Throws:

Validator.InvalidValueException - if the value is not valid

See Also:

Validatable.validate()

isInvalidAllowed

public boolean isInvalidAllowed()

Checks the validabtable object accept invalid values.

Specified by:

isInvalidAllowed in interface Validatable

Overrides:

isInvalidAllowed in class AbstractField

Returns:

true iff the invalid values are allowed.

See Also:

Validatable.isInvalidAllowed()

setInvalidAllowed

public void setInvalidAllowed(boolean invalidValueAllowed)
                       throws UnsupportedOperationException

Should the validabtable object accept invalid values.

Specified by:

setInvalidAllowed in interface Validatable

Overrides:

setInvalidAllowed in class AbstractField

Throws:

UnsupportedOperationException - if the setInvalidAllowed is not supported.

See Also:

Validatable.setInvalidAllowed(boolean)

setReadOnly

public void setReadOnly(boolean readOnly)

Sets the component's to read-only mode to the specified state.

Specified by:

setReadOnly in interface Property

Specified by:

setReadOnly in interface Component

Overrides:

setReadOnly in class AbstractField

Parameters:

readOnly - the boolean value specifying if the component should be in read-only mode after the call or not.

See Also:

Component.setReadOnly(boolean)

setFieldFactory

public void setFieldFactory(FieldFactory fieldFactory)

Sets the field factory of Form. FieldFactory is used to create fields for form properties. By default the form uses BaseFieldFactory to create Field instances.

Parameters:

fieldFactory - the New factory used to create the fields.

See Also:

Field, FieldFactory

getFieldFactory

public FieldFactory getFieldFactory()

Get the field factory of the form.

Returns:

the FieldFactory Factory used to create the fields.

getType

public Class getType()

Gets the field type.

Specified by:

getType in interface Property

Specified by:

getType in class AbstractField

Returns:

type of the Property

See Also:

AbstractField.getType()

setInternalValue

protected void setInternalValue(Object newValue)

Sets the internal value. This is relevant when the Form is used as Field.

Overrides:

setInternalValue in class AbstractField

Parameters:

newValue - the new value to be set.

See Also:

AbstractField.setInternalValue(java.lang.Object)

setFormDataSource

protected void setFormDataSource(Object data,
                                 Collection properties)

Updates the internal form datasource. Method setFormDataSource.

Parameters:

data -

properties -

getVisibleItemProperties

public Collection getVisibleItemProperties()

Returns the visibleProperties.

Returns:

the Collection of visible Item properites.

setVisibleItemProperties

public void setVisibleItemProperties(Collection visibleProperties)

Sets the visibleProperties.

Parameters:

visibleProperties - the visibleProperties to set.

focus

public void focus()

Focuses the first field in the form.

Specified by:

focus in interface Component.Focusable

Overrides:

focus in class AbstractField

See Also:

Component.Focusable.focus()

setTabIndex

public void setTabIndex(int tabIndex)

Sets the Tabulator index of this Focusable component.

Specified by:

setTabIndex in interface Component.Focusable

Overrides:

setTabIndex in class AbstractField

Parameters:

tabIndex - the tab order of this component. Negative value means unspecified.

See Also:

Component.Focusable.setTabIndex(int)