net.sf.jguiraffe.gui.builder.event

Class FormEventManager

java.lang.Object

net.sf.jguiraffe.gui.builder.event.FormEventManager

public class FormEventManager
extends Object

The main class for event handling in the form framework.

When programming against a concrete GUI framework like Swing or AWT, a developer usually registers event listeners directly at the components of interest. In this generic GUI framework the same task is done using this class.

This class is used by clients of the form framework to register event listeners at components of a form. It provides an addXXXListener() method for each supported event listener type. Each of these methods comes in two overloaded versions: One version allows to specify the name of a concrete component. The listener will then only be registered at that component. The other version registers the listeners for all components; so it will receive all occurring events of the corresponding type. Corresponding removeXXXListener() methods for unregistering listeners are also available.

Registering and unregistering event listeners can be done from arbitrary threads and will not conflict with the firing of events. This class implements proper synchronization. It is also possible to add or remove listeners in an invoked event handler.

This event manager class provides an additional level of abstraction over the platform (i.e. GUI library) specific event manager class (the concrete implementation of the PlatformEventManager interface). It is possible to use this implementation directly to register event listeners. The reason for this additional level is that it provides a simple way for registering broadcast event listeners, i.e. listeners that are capable of receiving all events of a specific type, caused by all involved components. In addition it provides an easier interface for the listener registration process.

The event manager class needs access to the component handlers of the available components. For this purpose it maintains a reference to a ComponentStore instance. This instance must have been initialized before the manager can be used.

Version:

$Id: FormEventManager.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

Constructor Summary

Constructors

Constructor and Description
FormEventManager(PlatformEventManager platformEventManager) Creates a new instance of FormEventManager and sets the platform specific event manager.

Method Summary

Modifier and Type	Method and Description
void	addActionListener(FormActionListener l) Adds an action listener that will be notified about all occurring action events.
void	addActionListener(String name, FormActionListener l) Adds an action listener for the specified component.
void	addChangeListener(FormChangeListener l) Adds a change listener that will be notified about all occurring change events.
void	addChangeListener(String name, FormChangeListener l) Adds a change listener for the specified component.
int	addEventListener(String componentName, String listenerType, EventListener l) Adds a generic event listener to a component.
boolean	addEventListenerToObject(Object target, String listenerType, EventListener l) Adds a generic event listener to the specified object.
void	addFocusListener(FormFocusListener l) Adds a focus listener that will be notified about all occurring focus events.
void	addFocusListener(String name, FormFocusListener l) Adds a focus listener for the specified component.
protected void	addListener(FormListenerType type, String name, FormEventListener l) Performs the actual adding of an event listener.
void	addMouseListener(FormMouseListener l) Adds a mouse listener that will be notified about all mouse events generated for the components in the current form.
void	addMouseListener(String name, FormMouseListener l) Adds a mouse listener to the specified component.
void	fireEvent(FormEvent event, FormListenerType type) Sends the specified event to all registered listeners.
ComponentHandler<?>	getComponentHandler(String name) Returns the component handler with the given name.
ComponentStore	getComponentStore() Returns the component store used by this event manager instance.
PlatformEventManager	getPlatformEventManager() Returns the platform specific event manager.
void	removeActionListener(FormActionListener l) Removes an action listener that is registered for all components.
void	removeActionListener(String name, FormActionListener l) Removes the specified action listener for the specified component.
void	removeChangeListener(FormChangeListener l) Removes a change listener that is registered for all components.
void	removeChangeListener(String name, FormChangeListener l) Removes the specified change listener for the specified component.
int	removeEventListener(String componentName, String listenerType, EventListener l) Removes an arbitrary event listener from a component.
boolean	removeEventListenerFromObject(Object target, String listenerType, EventListener l) Removes an arbitrary event listener from the specified object.
void	removeFocusListener(FormFocusListener l) Removes a focus listener that is registered for all components.
void	removeFocusListener(String name, FormFocusListener l) Removes the specified focus listener for the specified component.
protected boolean	removeListener(FormListenerType type, String name, FormEventListener l) Performs the actual removal of an event listener.
void	removeMouseListener(FormMouseListener l) Removes a mouse listener that is registered for all components.
void	removeMouseListener(String name, FormMouseListener l) Removes the specified mouse listener from the component with the given name.
void	setComponentStore(ComponentStore componentStore) Sets the component store to be used.

Methods inherited from class java.lang.Object

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

Constructor Detail

FormEventManager

public FormEventManager(PlatformEventManager platformEventManager)

Creates a new instance of FormEventManager and sets the platform specific event manager.

Parameters:

platformEventManager - the platform event manager

Method Detail

getPlatformEventManager

public PlatformEventManager getPlatformEventManager()

Returns the platform specific event manager.

Returns:

the platform event manager

getComponentStore

public ComponentStore getComponentStore()

Returns the component store used by this event manager instance.

Returns:

the underlying component store

setComponentStore

public void setComponentStore(ComponentStore componentStore)

Sets the component store to be used. From this store the event manager will fetch the ComponentHandler objects of the components, for which event listeners are to be registered.

Parameters:

componentStore - the component store to be used

getComponentHandler

public ComponentHandler<?> getComponentHandler(String name)

Returns the component handler with the given name. If this name is undefined, null is returned.

Parameters:

name - the name of the desired component

Returns:

the component handler for the component with this name

Throws:

IllegalStateException - if no component store has been set

addActionListener

public void addActionListener(String name,
                              FormActionListener l)

Adds an action listener for the specified component.

Parameters:

name - the component's name

l - the listener to add (can be null, then this operation will have no effect)

Throws:

NoSuchElementException - if no component with this names exists

addActionListener

public void addActionListener(FormActionListener l)

Adds an action listener that will be notified about all occurring action events.

Parameters:

l - the listener to add (can be null, then this operation will have no effect)

removeActionListener

public void removeActionListener(String name,
                                 FormActionListener l)

Removes the specified action listener for the specified component.

Parameters:

name - the component's name

l - the listener to be removed (if this listener is not registered at this component, this operation will have no effect)

removeActionListener

public void removeActionListener(FormActionListener l)

Removes an action listener that is registered for all components.

Parameters:

l - the action listener to be removed (if this listener is not registered for all components, this operation will have no effect)

addChangeListener

public void addChangeListener(String name,
                              FormChangeListener l)

Adds a change listener for the specified component.

Parameters:

name - the component's name

l - the listener to add

Throws:

NoSuchElementException - if no component with this names exists

addChangeListener

public void addChangeListener(FormChangeListener l)

Adds a change listener that will be notified about all occurring change events.

Parameters:

l - the listener to add

removeChangeListener

public void removeChangeListener(String name,
                                 FormChangeListener l)

Removes the specified change listener for the specified component.

Parameters:

name - the component's name

l - the listener to be removed (if this listener is not registered at this component, this operation will have no effect)

removeChangeListener

public void removeChangeListener(FormChangeListener l)

Removes a change listener that is registered for all components.

Parameters:

l - the change listener to be removed (if this listener is not registered for all components, this operation will have no effect)

addFocusListener

public void addFocusListener(String name,
                             FormFocusListener l)

Adds a focus listener for the specified component.

Parameters:

name - the component's name

l - the listener to add

Throws:

NoSuchElementException - if no component with this names exists

addFocusListener

public void addFocusListener(FormFocusListener l)

Adds a focus listener that will be notified about all occurring focus events.

Parameters:

l - the listener to add

removeFocusListener

public void removeFocusListener(String name,
                                FormFocusListener l)

Removes the specified focus listener for the specified component.

Parameters:

name - the component's name

l - the listener to be removed (if this listener is not registered at this component, this operation will have no effect)

removeFocusListener

public void removeFocusListener(FormFocusListener l)

Removes a focus listener that is registered for all components.

Parameters:

l - the focus listener to be removed (if this listener is not registered for all components, this operation will have no effect)

addMouseListener

public void addMouseListener(String name,
                             FormMouseListener l)

Adds a mouse listener to the specified component.

Parameters:

name - the name of the component

l - the listener to add

Throws:

NoSuchElementException - if no component with this name exists

addMouseListener

public void addMouseListener(FormMouseListener l)

Adds a mouse listener that will be notified about all mouse events generated for the components in the current form.

Parameters:

l - the listener to add

removeMouseListener

public void removeMouseListener(String name,
                                FormMouseListener l)

Removes the specified mouse listener from the component with the given name. If this listener is not registered at this component, this operation has no effect.

Parameters:

name - the name of the component

l - the listener to be removed

removeMouseListener

public void removeMouseListener(FormMouseListener l)

Removes a mouse listener that is registered for all components. If the listener is unknown, this operation has no effect.

Parameters:

l - the listener to be removed

fireEvent

public void fireEvent(FormEvent event,
                      FormListenerType type)

Sends the specified event to all registered listeners. This implementation relies on the given event object to be properly initialized, especially the component handler and name fields must be correctly filled. From the event the name of the affected component is extracted. All event listeners of the specified type that are registered for this specific component are notified first. Then the unspecific event listeners are invoked.

Parameters:

event - the event

type - the event listener type

addEventListener

public int addEventListener(String componentName,
                            String listenerType,
                            EventListener l)

Adds a generic event listener to a component. This is the most generic way of adding an event listener. While there are specific methods for adding default event listeners (e.g. addActionListener() or addFocusListener()), using this method arbitrary listeners can be added to components - also for non-standard events. The type of the listener is specified as a string. If this string refers to a standard event type (i.e. the string contains the name of one of the constants defined by the FormListenerType enumeration class ignoring case), the behavior of this method is exactly the same as if the corresponding specific add() method was called. Otherwise, the method uses reflection to find a corresponding method for adding the listener to a ComponentHandler based on naming conventions. The following convention is used: If the string Foo is passed, a method with the name addFooListener() is searched. This method is then invoked passing in the specified event listener. The type of the listener must be compatible with the listener type expected by the addXXXListener() method. For instance, the TreeHandler interface, an extension of ComponentHandler defines an addExpansionListener() method for adding specialized listeners for tree events. By passing in the string Expansion it is possible to register listeners of this type. If a component name is passed in, the listener is only registered at this component. Otherwise all ComponentHandler objects currently known are searched for corresponding methods for adding event listeners. The return value of this method determines the number of components, for which the event listener was added. A return value of 0 typically indicates that something went wrong: maybe there was a typo in the string representing the event listener type.

Parameters:

componentName - the name of the component, for which the listener should be added; can be null, then all fitting components are processed

listenerType - a string determining the listener type

l - the listener to be added (can be null, then this method has no effect)

Returns:

the number of components the event listener was registered at

removeEventListener

public int removeEventListener(String componentName,
                               String listenerType,
                               EventListener l)

Removes an arbitrary event listener from a component. This method is the counterpart of the addEventListener(String, String, EventListener) method. It works analogously to remove event listeners. The return value indicates the number of components for which the remove method for the event listener was called. This does not necessarily mean that the listener was actually registered at this components and was removed.

Parameters:

componentName - the name of the component, for which the listener should be added; can be null, then all fitting components are processed

listenerType - a string determining the listener type

l - the listener to be removed (can be null, then this method has no effect)

Returns:

the number of components from which the event listener was removed

addEventListenerToObject

public boolean addEventListenerToObject(Object target,
                                        String listenerType,
                                        EventListener l)

Adds a generic event listener to the specified object. This method works like addEventListener(String, String, EventListener), however, the target object can be specified directly. The listener is registered using reflection as described in the comment for addEventListener().

Parameters:

target - the target object to which the listener is to be registered

listenerType - a string determining the listener type

l - the listener to be added (can be null, then this method has no effect)

Returns:

a flag whether the listener could be added successfully

removeEventListenerFromObject

public boolean removeEventListenerFromObject(Object target,
                                             String listenerType,
                                             EventListener l)

Removes an arbitrary event listener from the specified object. This is the counterpart of addEventListenerToObject(Object, String, EventListener). It works analogously to removeEventListener(String, String, EventListener), but the object affected is directly passed.

Parameters:

target - the object from which the listener is to be removed

listenerType - a string determining the listener type

l - the listener to be removed (can be null, then this method has no effect)

Returns:

a flag whether the listener could be removed without errors

addListener

protected void addListener(FormListenerType type,
                           String name,
                           FormEventListener l)

Performs the actual adding of an event listener. This method is called by the various addXXXListener() methods.

Parameters:

type - the type of the listener to be added

name - the name of the component (null for all listeners)

l - the affected event listener

removeListener

protected boolean removeListener(FormListenerType type,
                                 String name,
                                 FormEventListener l)

Performs the actual removal of an event listener. This method is called by the various removeXXXListener() methods.

Parameters:

type - the type of the listener to be removed

name - the name of the component (null for all listeners)

l - the affected event listener

Returns:

a flag whether the listener could be removed