com.itmill.toolkit.ui
Class AbstractComponent

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

All Implemented Interfaces:

MethodEventSource, Paintable, VariableOwner, Component, EventListener

Direct Known Subclasses:

AbstractComponentContainer, AbstractField, Embedded, Label, Link, Upload

public abstract class AbstractComponent
extends Identifiable
implements Component, MethodEventSource

An abstract class that defines default implementation for the Component interface. Basic UI components that are not derived from an external component can inherit this class to easily qualify as a IT Mill Toolkit component. Most components in the toolkit do just that.

Since:

3.0

Version:

4.1.4

Author:

IT Mill Ltd.

Nested Class Summary

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

Constructor Summary

AbstractComponent()
Constructs a new Component.

Method Summary

void	addListener(Class eventType, Object object, Method method) Registers a new listener with the specified activation method to listen events generated by this component.
void	addListener(Class eventType, Object object, String methodName) Registers a new listener with the specified activation method to listen events generated by this component.
void	addListener(Component.Listener listener) Registers a new component event listener for this component.
void	addListener(Paintable.RepaintRequestListener listener) Adds repaint request listener.
void	attach() Notifies the component that it is connected to an application.
void	changeVariables(Object source, Map variables) Called when one or more variables handled by the implementing class are changed.
void	childRequestedRepaint(Collection alreadyNotified) The children must call this method when they need repainting.
void	dependsOn(VariableOwner depended) Makes this VariableOwner depend on the given VariableOwner.
void	detach() Notifies the component that it is detached from the application.
protected void	fireComponentErrorEvent() Emits the component error event.
protected void	fireComponentEvent() Emits the component event.
protected void	fireEvent(Component.Event event) Sends the event to all listeners.
Application	getApplication() Gets the component's parent application.
String	getCaption() Gets the caption of the component.
ErrorMessage	getComponentError() Gets the component's error message.
Object	getData() Gets the application specific data.
String	getDescription() Gets the component's description.
Set	getDirectDependencies() Gets the variable change listeners this VariableOwner directly depends on.
ErrorMessage	getErrorMessage() Gets the error message for this component.
Resource	getIcon() Gets the component's icon.
Locale	getLocale() Gets the locale of this component.
Component	getParent() Gets the visual parent of the component.
String	getStyle() Gets the look-and-feel style of the component.
abstract String	getTag() Gets the UIDL tag corresponding to the component.
Window	getWindow() Gets the component's parent window.
boolean	isEnabled() Tests if the variable owner is enabled or not.
boolean	isImmediate() Tests if the variable owner is in immediate mode or not.
boolean	isReadOnly() Tests if the component is in read-only mode.
boolean	isVisible() Tests if the component is visible or not.
void	paint(PaintTarget target) Paints the paintable into a UIDL stream.
void	paintContent(PaintTarget target) Paints any needed component-specific things to the given UIDL stream.
void	removeDirectDependency(VariableOwner depended) Removes the given component from this component's dependency list.
void	removeListener(Class eventType, Object target) Removes all registered listeners matching the given parameters.
void	removeListener(Class eventType, Object target, Method method) Removes one registered listener method.
void	removeListener(Class eventType, Object target, String methodName) Removes one registered listener method.
void	removeListener(Component.Listener listener) Removes a previously registered component event listener from this component.
void	removeListener(Paintable.RepaintRequestListener listener) Removes repaint request listener.
void	requestRepaint() Requests that the paintable should be repainted as soon as possible.
void	requestRepaintRequests() Request sending of repaint events on any further visible changes.
void	setCaption(String caption) Sets the component's caption String.
void	setComponentError(ErrorMessage componentError) Sets the component's error message.
void	setData(Object data) Sets the application specific data object.
void	setDescription(String description) Sets the component's description.
void	setEnabled(boolean enabled) Enables or disables the component.
void	setIcon(Resource icon) Sets the component's icon.
void	setImmediate(boolean immediate) Sets the component's immediate mode to the specified status.
void	setLocale(Locale locale) Sets the locale of this component.
void	setParent(Component parent) Sets the component's parent component.
void	setReadOnly(boolean readOnly) Sets the component's to read-only mode to the specified state.
void	setStyle(String style) Sets the look-and-feel style of the component.
void	setVisible(boolean visible) Sets the components visibility status.

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

getDebugId, getUIID, setDebugId, setUIID

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractComponent

public AbstractComponent()

Constructs a new Component.

Method Detail

getTag

public abstract String getTag()

Gets the UIDL tag corresponding to the component.

Returns:

the component's UIDL tag as String

getStyle

public String getStyle()

Description copied from interface: Component

Gets the look-and-feel style of the component.

Specified by:

getStyle in interface Component

Returns:

the component's styleValue of property style.

setStyle

public void setStyle(String style)

Description copied from interface: Component

Sets the look-and-feel style of the component. This method will trigger a RepaintRequestEvent.

Specified by:

setStyle in interface Component

Parameters:

style - the new style of the component.

getCaption

public String getCaption()

Description copied from interface: Component

Gets the caption of the component. Caption is the visible name of the component.

Specified by:

getCaption in interface Component

Returns:

the component's caption String.

setCaption

public void setCaption(String caption)

Sets the component's caption String. Caption is the visible name of the component. This method will trigger a RepaintRequestEvent.

Parameters:

caption - the new caption String for the component.

getLocale

public Locale getLocale()

Description copied from interface: Component

Gets the locale of this component.

Specified by:

getLocale in interface Component

Returns:

This component's locale. If this component does not have a locale, the locale of its parent is returned. Eventually locale of application is returned. If application does not have its own locale the locale is determined by Locale.getDefautlt. Returns null if the component does not have its own locale and has not yet been added to a containment hierarchy such that the locale can be determined from the containing parent.

setLocale

public void setLocale(Locale locale)

Sets the locale of this component.

Parameters:

locale - the locale to become this component's locale.

getIcon

public Resource getIcon()

Description copied from interface: Component

Gets the component's icon. A component may have a graphical icon associated with it, this method retrieves it if it is defined.

Specified by:

getIcon in interface Component

Returns:

the component's icon or null if it not defined.

setIcon

public void setIcon(Resource icon)

Sets the component's icon. This method will trigger a RepaintRequestEvent.

Parameters:

icon - the icon to be shown with the component's caption.

isEnabled

public boolean isEnabled()

Description copied from interface: VariableOwner

Tests if the variable owner is enabled or not. The terminal should not send any variable changes to disabled variable owners.

Specified by:

isEnabled in interface VariableOwner

Specified by:

isEnabled in interface Component

Returns:

true if the variable owner is enabled, false if not

See Also:

VariableOwner.isEnabled()

setEnabled

public void setEnabled(boolean enabled)

Description copied from interface: Component

Enables or disables the component. Being enabled means that the component can be edited. This method will trigger a RepaintRequestEvent.

Specified by:

setEnabled in interface Component

Parameters:

enabled - the boolean value specifying if the component should be enabled after the call or not

isImmediate

public boolean isImmediate()

Description copied from interface: VariableOwner

Tests if the variable owner is in immediate mode or not. Being in immediate mode means that all variable changes are required to be sent back from the terminal immediately when they occur.

Note: VariableOwner does not include a set- method for the immediateness property. This is because not all VariableOwners wish to offer the functionality. Such VariableOwners are never in the immediate mode, thus they always return false in VariableOwner.isImmediate().

Specified by:

isImmediate in interface VariableOwner

Returns:

true if the component is in immediate mode, false if not.

setImmediate

public void setImmediate(boolean immediate)

Sets the component's immediate mode to the specified status. This method will trigger a RepaintRequestEvent.

Parameters:

immediate - the boolean value specifying if the component should be in the immediate mode after the call.

See Also:

VariableOwner.isImmediate()

isVisible

public boolean isVisible()

Description copied from interface: Component

Tests if the component is visible or not. Visibility defines if the component is shown in the UI or not. Default is true.

Specified by:

isVisible in interface Component

Returns:

true if the component is visible in the UI, false if not

setVisible

public void setVisible(boolean visible)

Description copied from interface: Component

Sets the components visibility status. Visibility defines if the component is shown in the UI or not.

Specified by:

setVisible in interface Component

Parameters:

visible - the Boolean value specifying if the component should be visible after the call or not.

getDescription

public String getDescription()

Gets the component's description. The description can be used to briefly describe the state of the component to the user. The description string may contain certain XML tags:

Tag	Description	Example
<b>	bold	bold text
<i>	italic	italic text
<u>	underlined	underlined text
<br>	linebreak	N/A
<ul> <li>item1 <li>item1 </ul>	item list	item1 item2

These tags may be nested.

Returns:

component's description String

setDescription

public void setDescription(String description)

Sets the component's description. See getDescription() for more information on what the description is. This method will trigger a RepaintRequestEvent.

Parameters:

description - the new description string for the component.

getParent

public Component getParent()

Description copied from interface: Component

Gets the visual parent of the component. The components can be nested but one component can have only one parent.

Specified by:

getParent in interface Component

Returns:

the parent component.

setParent

public void setParent(Component parent)

Description copied from interface: Component

Sets the component's parent component.

This method calls automatically Component.attach() if the parent is attached to a window (or is itself a window}, and Component.detach() if parent is set null, but the component was in the application.

This method is rarely called directly. Instead the ComponentContainer.addComponent(Component) method is used to add components to container, which call this method implicitly.

Specified by:

setParent in interface Component

Parameters:

parent - the new parent component.

getErrorMessage

public ErrorMessage getErrorMessage()

Gets the error message for this component.

Returns:

ErrorMessage containing the description of the error state of the component or null, if the component contains no errors. Extending classes should override this method if they support other error message types such as validation errors or buffering errors. The returned error message contains information about all the errors.

getComponentError

public ErrorMessage getComponentError()

Gets the component's error message.

Returns:

the component's error message.

setComponentError

public void setComponentError(ErrorMessage componentError)

Sets the component's error message. The message may contain certain XML tags, for more information see

Parameters:

componentError - the new ErrorMessage of the component.

isReadOnly

public boolean isReadOnly()

Description copied from interface: Component

Tests if the component is in read-only mode.

Specified by:

isReadOnly in interface Component

Returns:

true if the component is in read-only mode, false if not.

setReadOnly

public void setReadOnly(boolean readOnly)

Description copied from interface: Component

Sets the component's to read-only mode to the specified state. This method will trigger a RepaintRequestEvent.

Specified by:

setReadOnly in interface Component

Parameters:

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

getWindow

public Window getWindow()

Description copied from interface: Component

Gets the component's parent window. If the component does not yet belong to a window null is returned.

Specified by:

getWindow in interface Component

Returns:

the parent window of the component or null.

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 methods 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

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

getApplication

public Application getApplication()

Description copied from interface: Component

Gets the component's parent application. If the component does not yet belong to a application null is returned.

Specified by:

getApplication in interface Component

Returns:

the parent application of the component or null.

requestRepaintRequests

public void requestRepaintRequests()

Description copied from interface: Paintable

Request sending of repaint events on any further visible changes. Normally the paintable only send up to one repaint request for listeners after paint as the paintable as the paintable assumes that the listeners already know about the repaint need. This method resets the assumtion. Paint implicitly does the assumtion reset functionality implemented by this method.

This method is normally used only by the terminals to note paintables about implicit repaints (painting the component without actually invoking paint method).

Specified by:

requestRepaintRequests in interface Paintable

paint

public final void paint(PaintTarget target)
                 throws PaintException

Description copied from interface: Paintable

Paints the paintable into a UIDL stream. This method creates the UIDL sequence describing it and outputs it to the given UIDL stream.

It is called when the contents of the component should be painted in response to the component first being shown or having been altered so that its visual representation is changed.

Specified by:

paint in interface Paintable

Parameters:

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

Throws:

PaintException - if the paint operation failed.

paintContent

public void paintContent(PaintTarget target)
                  throws PaintException

Paints any needed component-specific things to the given UIDL stream. The more general 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.

Parameters:

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

Throws:

PaintException - if the paint operation failed.

requestRepaint

public void requestRepaint()

Description copied from interface: Paintable

Requests that the paintable should be repainted as soon as possible.

Specified by:

requestRepaint in interface Paintable

childRequestedRepaint

public void childRequestedRepaint(Collection alreadyNotified)

Description copied from interface: Component

The children must call this method when they need repainting. The call must be made event in the case the children sent the repaint request themselves.

Specified by:

childRequestedRepaint in interface Component

Parameters:

alreadyNotified - the collection of repaint request listeners that have been already notified by the child. This component should not renotify the listed listeners again. The container given as parameter must be modifiable as the component might modify it and pass it forwards. Null parameter is interpreted as empty collection.

addListener

public void addListener(Paintable.RepaintRequestListener listener)

Description copied from interface: Paintable

Adds repaint request listener. In order to assure that no repaint requests are missed, the new repaint listener should paint the paintable right after adding itself as listener.

Specified by:

addListener in interface Paintable

Parameters:

listener - the listener to be added.

removeListener

public void removeListener(Paintable.RepaintRequestListener listener)

Description copied from interface: Paintable

Removes repaint request listener.

Specified by:

removeListener in interface Paintable

Parameters:

listener - the listener to be removed.

changeVariables

public void changeVariables(Object source,
                            Map variables)

Description copied from interface: VariableOwner

Called when one or more variables handled by the implementing class are changed.

Specified by:

changeVariables in interface VariableOwner

Parameters:

source - the Source of the variable change. This is the origin of the event. For example in Web Adapter this is the request.

variables - the Mapping from variable names to new variable values.

dependsOn

public void dependsOn(VariableOwner depended)

Description copied from interface: VariableOwner

Makes this VariableOwner depend on the given VariableOwner. This means that any variable change events relating to depended must be sent before any such events that relate to this object.

Specified by:

dependsOn in interface VariableOwner

Parameters:

depended - the VariableOwner component who this component depends on.

removeDirectDependency

public void removeDirectDependency(VariableOwner depended)

Description copied from interface: VariableOwner

Removes the given component from this component's dependency list. After the call this component will no longer depend on depended wdepende direct dependency from the component. Indirect dependencies are not removed.

Specified by:

removeDirectDependency in interface VariableOwner

Parameters:

depended - the component to be removed from this component's dependency list.

getDirectDependencies

public Set getDirectDependencies()

Description copied from interface: VariableOwner

Gets the variable change listeners this VariableOwner directly depends on. This list does not contain any indirect dependencies, for example, if A depends on B and B depends on C, the dependency list of A does not include C.

Specified by:

getDirectDependencies in interface VariableOwner

Returns:

Set of VariableOwners this component directly depend on, null if this component does not depend on anybody.

addListener

public void addListener(Class eventType,
                        Object object,
                        Method method)

Registers a new listener with the specified activation method to listen events generated by this component. If the activation method does not have any arguments the event object will not be passed to it when it's called.

For more information on the inheritable event mechanism see the com.itmill.toolkit.event package documentation.

Specified by:

addListener in interface MethodEventSource

Parameters:

eventType - the type of the listened event. Events of this type or its subclasses activate the listener.

object - the object instance who owns the activation method.

method - the activation method.

addListener

public void addListener(Class eventType,
                        Object object,
                        String methodName)

Registers a new listener with the specified activation method to listen events generated by this component. If the activation method does not have any arguments the event object will not be passed to it when it's called.

This version of addListener gets the name of the activation method as a parameter. The actual method is reflected from object, and unless exactly one match is found, java.lang.IllegalArgumentException is thrown.

For more information on the inheritable event mechanism see the com.itmill.toolkit.event package documentation.

Specified by:

addListener in interface MethodEventSource

Parameters:

eventType - the type of the listened event. Events of this type or its subclasses activate the listener.

object - the object instance who owns the activation method.

methodName - the name of the activation method.

removeListener

public void removeListener(Class eventType,
                           Object target)

Removes all registered listeners matching the given parameters. Since this method receives the event type and the listener object as parameters, it will unregister all object's methods that are registered to listen to events of type eventType generated by this component.

For more information on the inheritable event mechanism see the com.itmill.toolkit.event package documentation.

Specified by:

removeListener in interface MethodEventSource

Parameters:

eventType - the exact event type the object listens to.

target - the target object that has registered to listen to events of type eventType with one or more methods.

removeListener

public void removeListener(Class eventType,
                           Object target,
                           Method method)

Removes one registered listener method. The given method owned by the given object will no longer be called when the specified events are generated by this component.

For more information on the inheritable event mechanism see the com.itmill.toolkit.event package documentation.

Specified by:

removeListener in interface MethodEventSource

Parameters:

eventType - the exact event type the object listens to.

target - target object that has registered to listen to events of type eventType with one or more methods.

method - the method owned by target that's registered to listen to events of type eventType.

removeListener

public void removeListener(Class eventType,
                           Object target,
                           String methodName)

Removes one registered listener method. The given method owned by the given object will no longer be called when the specified events are generated by this component.

This version of removeListener gets the name of the activation method as a parameter. The actual method is reflected from target, and unless exactly one match is found, java.lang.IllegalArgumentException is thrown.

For more information on the inheritable event mechanism see the com.itmill.toolkit.event package documentation.

Specified by:

removeListener in interface MethodEventSource

Parameters:

eventType - the exact event type the object listens to.

target - the target object that has registered to listen to events of type eventType with one or more methods.

methodName - the name of the method owned by target that's registered to listen to events of type eventType.

fireEvent

protected void fireEvent(Component.Event event)

Sends the event to all listeners.

Parameters:

event - the Event to be sent to all listeners.

addListener

public void addListener(Component.Listener listener)

Description copied from interface: Component

Registers a new component event listener for this component.

Specified by:

addListener in interface Component

Parameters:

listener - the new Listener to be registered.

removeListener

public void removeListener(Component.Listener listener)

Description copied from interface: Component

Removes a previously registered component event listener from this component.

Specified by:

removeListener in interface Component

Parameters:

listener - the listener to be removed.

fireComponentEvent

protected void fireComponentEvent()

Emits the component event. It is transmitted to all registered listeners interested in such events.

fireComponentErrorEvent

protected void fireComponentErrorEvent()

Emits the component error event. It is transmitted to all registered listeners interested in such events.

setData

public void setData(Object data)

Sets the application specific data object.

Parameters:

data - the Application specific data.

Since:

3.1

getData

public Object getData()

Gets the application specific data.

Returns:

the Application specific data set with setData function.

Since:

3.1