org.millstone.base.ui
Class AbstractComponent

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

All Implemented Interfaces:

Component, java.util.EventListener, MethodEventSource, Paintable, VariableOwner

Direct Known Subclasses:

AbstractComponentContainer, AbstractField, Embedded, Form, Label, Link, Upload

public abstract class AbstractComponent

extends java.lang.Object

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 MillStone component. Most components in the MillStone base UI package do just that.

Since:

3.0

Version:

3.0.3

Author:

IT Mill Ltd.

Nested Class Summary

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

AbstractComponent()
Constructs a new Component

Method Summary

void	addListener(java.lang.Class eventType, java.lang.Object object, java.lang.reflect.Method method) Registers a new listener with the specified activation method to listen events generated by this component.
void	addListener(java.lang.Class eventType, java.lang.Object object, java.lang.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) Add repaint request listener.
void	attach() Notifies the component that it is connected to an application.
void	changeVariables(java.lang.Object source, java.util.Map variables) Called when one or more variables handled by the implementing class are changed.
void	childRequestedRepaint(java.util.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	fireComponentEvent() Emits a component event.
protected void	fireEvent(Component.Event event) Send event to all listeners
Application	getApplication() Gets the component's parent application.
java.lang.String	getCaption() Gets the caption of the component.
ErrorMessage	getComponentError() Gets the component's error message.
java.lang.String	getDescription() Gets the component's description.
java.util.Set	getDirectDependencies() Gets the variable change listeners this VariableOwner directly depends on.
ErrorMessage	getErrorMessage() Get the error message for this component.
Resource	getIcon() Gets the component's icon.
java.util.Locale	getLocale() Gets the locale of this component.
Component	getParent() Gets the visual parent of the component.
java.lang.String	getStyle() Gets the look-and-feel style of the component.
abstract java.lang.String	getTag() Gets the UIDL tag corresponding to the component.
Window	getWindow() Gets the component's parent window.
boolean	isEnabled() Tests if the component is enabled or not.
boolean	isImmediate() Tests if the component 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(java.lang.Class eventType, java.lang.Object target) Removes all registered listeners matching the given parameters.
void	removeListener(java.lang.Class eventType, java.lang.Object target, java.lang.reflect.Method method) Removes one registered listener method.
void	removeListener(java.lang.Class eventType, java.lang.Object target, java.lang.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) Remove 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(java.lang.String caption) Sets the component's caption String.
void	setComponentError(ErrorMessage componentError) Sets the component's error message.
void	setDescription(java.lang.String description) Sets the component's description.
void	setEnabled(boolean enabled) Enable or disable 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(java.util.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(java.lang.String style) Sets the look-and-feel style of the component.
void	setVisible(boolean visible) Sets the components visibility status.

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 java.lang.String getTag()

Gets the UIDL tag corresponding to the component.

Returns:

component's UIDL tag as String

getStyle

public java.lang.String getStyle()

Description copied from interface: Component

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

Specified by:

getStyle in interface Component

Returns:

component's styleValue of property style.

setStyle

public void setStyle(java.lang.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 - new style of the component

getCaption

public java.lang.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:

component's caption String

setCaption

public void setCaption(java.lang.String caption)

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

Parameters:

caption - new caption String for the component

getLocale

public java.util.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.getDefautl(). 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(java.util.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: Component

Tests if the component is enabled or not. All the variable change events are blocked from disabled components. Also the component should visually indicate that it is disabled (by shading the component for example). All hidden (isVisible() == false) components must return false.

Components should be enabled by default.

Specified by:

isEnabled in interface Component

Returns:

true if the component is enabled, false if not

See Also:

VariableOwner.isEnabled()

setEnabled

public void setEnabled(boolean enabled)

Description copied from interface: Component

Enable or disable 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 - boolean value specifying if the component should be enabled after the call or not

isImmediate

public boolean isImmediate()

Description copied from interface: Component

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

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

Specified by:

isImmediate in interface Component

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 - boolean value specifying if the component should be in the immediate mode after the call.

See Also:

Component.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 - Boolean value specifying if the component should be visible after the call or not

getDescription

public java.lang.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(java.lang.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 - 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()

Get 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:

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

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

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() 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

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:

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's 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 - 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 - target UIDL stream where the component should paint itself to

Throws:

PaintException - if the 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(java.util.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 - A 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

Add 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 - to be added

removeListener

public void removeListener(Paintable.RepaintRequestListener listener)

Description copied from interface: Paintable

Remove repaint request listener.

Specified by:

removeListener in interface Paintable

Parameters:

listener - to be removed

changeVariables

public void changeVariables(java.lang.Object source,
                            java.util.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 - Source of the variable change. This is the origin of the event. For example in Web Adapter this is the request.

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

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

getDirectDependencies

public java.util.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(java.lang.Class eventType,
                        java.lang.Object object,
                        java.lang.reflect.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 MillStone inheritable event mechanism see the org.millstone.base.event.

Specified by:

addListener in interface MethodEventSource

Parameters:

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

Throws:

java.lang.IllegalArgumentException - unless method has exactly one match in object

addListener

public void addListener(java.lang.Class eventType,
                        java.lang.Object object,
                        java.lang.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 MillStone inheritable event mechanism see the org.millstone.base.event.

Specified by:

addListener in interface MethodEventSource

Parameters:

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

Throws:

java.lang.IllegalArgumentException - unless method has exactly one match in object

removeListener

public void removeListener(java.lang.Class eventType,
                           java.lang.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 MillStone inheritable event mechanism see the org.millstone.base.event.

Specified by:

removeListener in interface MethodEventSource

Parameters:

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

removeListener

public void removeListener(java.lang.Class eventType,
                           java.lang.Object target,
                           java.lang.reflect.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 MillStone inheritable event mechanism see the org.millstone.base.event.

Specified by:

removeListener in interface MethodEventSource

Parameters:

eventType - 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(java.lang.Class eventType,
                           java.lang.Object target,
                           java.lang.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 MillStone inheritable event mechanism see the org.millstone.base.event.

Specified by:

removeListener in interface MethodEventSource

Parameters:

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

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

fireEvent

protected void fireEvent(Component.Event event)

Send event to all listeners

Parameters:

event - 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 a component event. It is transmitted to all registered listeners interested in such events.