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