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. CorrespondingremoveXXXListener()
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 Description FormEventManager(PlatformEventManager platformEventManager)
Creates a new instance ofFormEventManager
and sets the platform specific event manager.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addActionListener(String name, FormActionListener l)
Adds an action listener for the specified component.void
addActionListener(FormActionListener l)
Adds an action listener that will be notified about all occurring action events.void
addChangeListener(String name, FormChangeListener l)
Adds a change listener for the specified component.void
addChangeListener(FormChangeListener l)
Adds a change listener that will be notified about all occurring change events.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(String name, FormFocusListener l)
Adds a focus listener for the specified component.void
addFocusListener(FormFocusListener l)
Adds a focus listener that will be notified about all occurring focus events.protected void
addListener(FormListenerType type, String name, FormEventListener l)
Performs the actual adding of an event listener.void
addMouseListener(String name, FormMouseListener l)
Adds a mouse listener to the specified component.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
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(String name, FormActionListener l)
Removes the specified action listener for the specified component.void
removeActionListener(FormActionListener l)
Removes an action listener that is registered for all components.void
removeChangeListener(String name, FormChangeListener l)
Removes the specified change listener for the specified component.void
removeChangeListener(FormChangeListener l)
Removes a change listener that is registered for all components.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(String name, FormFocusListener l)
Removes the specified focus listener for the specified component.void
removeFocusListener(FormFocusListener l)
Removes a focus listener that is registered for all components.protected boolean
removeListener(FormListenerType type, String name, FormEventListener l)
Performs the actual removal of an event listener.void
removeMouseListener(String name, FormMouseListener l)
Removes the specified mouse listener from the component with the given name.void
removeMouseListener(FormMouseListener l)
Removes a mouse listener that is registered for all components.void
setComponentStore(ComponentStore componentStore)
Sets the component store to be used.
-
-
-
Constructor Detail
-
FormEventManager
public FormEventManager(PlatformEventManager platformEventManager)
Creates a new instance ofFormEventManager
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 theComponentHandler
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 namel
- 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 namel
- 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 namel
- 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 namel
- 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 namel
- 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 namel
- 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 componentl
- 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 componentl
- 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 eventtype
- 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()
oraddFocusListener()
), 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 theFormListenerType
enumeration class ignoring case), the behavior of this method is exactly the same as if the corresponding specificadd()
method was called. Otherwise, the method uses reflection to find a corresponding method for adding the listener to aComponentHandler
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 theaddXXXListener()
method. For instance, theTreeHandler
interface, an extension ofComponentHandler
defines anaddExpansionListener()
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 allComponentHandler
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 processedlistenerType
- a string determining the listener typel
- 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 theaddEventListener(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 processedlistenerType
- a string determining the listener typel
- 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 likeaddEventListener(String, String, EventListener)
, however, the target object can be specified directly. The listener is registered using reflection as described in the comment foraddEventListener()
.- Parameters:
target
- the target object to which the listener is to be registeredlistenerType
- a string determining the listener typel
- 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 ofaddEventListenerToObject(Object, String, EventListener)
. It works analogously toremoveEventListener(String, String, EventListener)
, but the object affected is directly passed.- Parameters:
target
- the object from which the listener is to be removedlistenerType
- a string determining the listener typel
- 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 variousaddXXXListener()
methods.- Parameters:
type
- the type of the listener to be addedname
- 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 variousremoveXXXListener()
methods.- Parameters:
type
- the type of the listener to be removedname
- the name of the component (null for all listeners)l
- the affected event listener- Returns:
- a flag whether the listener could be removed
-
-