org.millstone.base.ui
Class Form

java.lang.Object
  |
  +--org.millstone.base.ui.AbstractComponent
        |
        +--org.millstone.base.ui.Form

All Implemented Interfaces:

Buffered, Component, java.util.EventListener, Item, Item.Editor, Item.Viewer, MethodEventSource, Paintable, VariableOwner

public class Form

extends AbstractComponent

implements Item.Editor, Buffered, Item

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

Form is a container for fields extending AbstractField class. 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:

3.0.3

Author:

IT Mill Ltd.

Nested Class Summary

Nested classes inherited from class org.millstone.base.data.Buffered

Buffered.SourceException

Nested classes inherited from class org.millstone.base.data.Item

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

Nested classes inherited from class org.millstone.base.ui.Component

Component.Event, Component.Listener

Nested classes inherited from class org.millstone.base.terminal.Paintable

Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener

Constructor Summary

Form()
Contruct a new form with default layout.

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

Method Summary

void	addField(java.lang.Object propertyId, AbstractField field) Add abstract field to form.
boolean	addItemProperty(java.lang.Object id, Property property) Add a new property to form and create corresponding field.
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.
AbstractField	getField(java.lang.Object propertyId) Get the field identified by the propertyid
Item	getItemDataSource() Gets the Item serving as the data source of the viewer.
Property	getItemProperty(java.lang.Object id) The property identified by the property id.
java.util.Collection	getItemPropertyIds() Gets the collection of IDs of all Properties stored in the Item.
Layout	getLayout() Get the layout of the form.
java.lang.String	getTag() Gets the UIDL tag corresponding to the component.
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	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(java.lang.Object id) Removes the property and corresponding field from the form.
Select	replaceWithSelect(java.lang.Object propertyId, java.lang.Object[] values, java.lang.Object[] descriptions) Set a form field to be selectable from static list of changes.
void	setItemDataSource(Item newDataSource) Set the item datasource for the form.
void	setItemDataSource(Item newDataSource, java.util.Collection propertyIds) Set the item datasource for the form, but limit the form contents to specified properties of the item.
void	setReadThrough(boolean readThrough) Sets the object's read-through mode to the specified status.
void	setWriteThrough(boolean writeThrough) Sets the object's write-through mode to the specified status.

Methods inherited from class org.millstone.base.ui.AbstractComponent

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

Methods inherited from class java.lang.Object

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

Constructor Detail

Form

public Form()

Contruct a new form with default layout.

By default the form uses OrderedLayout with form-style.

Form

public Form(Layout formLayout)

Contruct a new form with given layout.

Parameters:

formLayout - The layout of the form.

Method Detail

getTag

public java.lang.String getTag()

Description copied from class: AbstractComponent

Gets the UIDL tag corresponding to the component.

Specified by:

getTag in class AbstractComponent

Returns:

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 AbstractComponent

Parameters:

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

Throws:

PaintException - if the 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

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

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

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

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

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

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

Parameters:

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

addItemProperty

public boolean addItemProperty(java.lang.Object id,
                               Property property)

Add 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 id

Returns:

true if the operation succeeded, false if not

See Also:

Item.addItemProperty(Object, Property)

addField

public void addField(java.lang.Object propertyId,
                     AbstractField field)

Add abstract 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 - Property id the the field.

field - New field added to the form.

getItemProperty

public Property getItemProperty(java.lang.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 AbstractField getField(java.lang.Object propertyId)

Get the field identified by the propertyid

getItemPropertyIds

public java.util.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(java.lang.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 false if not

See Also:

Item.removeItemProperty(Object)

removeAllProperties

public boolean removeAllProperties()

Removes all properties and fields from the form.

Returns:

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)

Set 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,
                              java.util.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()

Get the layout of the form.

By default form uses OrderedLayout with form-style.

Returns:

Layout of the form.

replaceWithSelect

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

Set a 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.

Returns:

The select property generated

attach

public void attach()

Description copied from interface: Component

Notifies the component that it is connected to an application. This method is always called before the component is first time painted and is suitable to be extended. The getApplication() and getWindow() functions might return null before this method is called.

The caller of this method is Component.setParent(Component) if the parent is already in the application. If the parent is not in the application, it must call the Component.attach() for all its children when it will be added to the application.

Specified by:

attach in interface Component

Overrides:

attach in class AbstractComponent

See Also:

Component.attach()

detach

public void detach()

Description copied from interface: Component

Notifies the component that it is detached from the application.

The Component.getApplication() and Component.getWindow() methods might return null after this method is called.

The caller of this method is Component.setParent(Component) if the parent is in the application. When the parent is detached from the application it is its response to call Component.detach() for all the children and to detach itself from the terminal.

Specified by:

detach in interface Component

Overrides:

detach in class AbstractComponent

See Also:

Component.detach()