Class SimplePopupMenuHandler

  • All Implemented Interfaces:
    ActionData, PopupMenuHandler

    public class SimplePopupMenuHandler
    extends ActionDataImpl
    implements PopupMenuHandler

    A specialized implementation of a PopupMenuHandler, which can be used out of the box for creating not too complex, mostly static popup menus.

    An instance of this class is initialized with a collection defining the content of a context menu. This collection can contain the following elements:

    • Action objects (i.e. objects implementing the FormAction interface): Actions are directly added to the context menu constructed by this object.
    • Further SimplePopupMenuHandler implementations: If another SimplePopupMenuHandler instance is encountered, a sub menu is created, and then the handler is invoked to populate it. In order to provide the properties required for a sub menu, this class extends ActionDataImpl. So things like the menu text or its icon can be set as properties. There is also a method to initialize all properties from another ActionData object.
    • null elements: They are used for defining menu separators.

    One advantage of this class is that instances can be fully defined in builder scripts (using the facilities provided by the dependency injection framework). As long as the context menus are static (i.e. they always display the same menu items) no programming is required, but this class can be used directly and fully defined in the application's configuration scripts.

    There are some hooks allowing subclasses to influence the menu construction process: Specific methods are called before items are added to the menu under construction. Derived classes can intercept here and for instance suppress actions under certain circumstances.

    Implementation note: This class is intended to be used by the event handling system of the GUI framework, i.e. to be invoked on the event dispatch thread. It is not safe to call it on multiple concurrent threads.

    Version:
    $Id: SimplePopupMenuHandler.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Constructor Detail

      • SimplePopupMenuHandler

        public SimplePopupMenuHandler​(Collection<?> items)
        Creates a new instance of SimplePopupMenuHandler and initializes it with the content of the menu. The passed in collection must not be null and must contain only valid objects, i.e. (per default)
        • objects implementing the FormAction interface or
        • further SimplePopupMenuHandler objects.
        The constructor does not check the content of the collection for validity. This can be done by invoking the checkMenuItems() method by hand.
        Parameters:
        items - a collection with the content of the menu to construct
        Throws:
        IllegalArgumentException - if the collection is null
        See Also:
        checkMenuItems()
    • Method Detail

      • getMenuItems

        public List<?> getMenuItems()
        Returns a list with the content of the menu to be constructed by this handler.
        Returns:
        the content definition of the menu to be constructed
      • checkMenuItems

        public void checkMenuItems()
                            throws FormActionException
        Tests whether all menu elements to be processed by this handler are supported. This method iterates over the items to be added to the menu and invokes the checkMenuElement() method on each. This ensures that only valid elements are involved. Note that this method is not automatically called by the constructor. This design was chosen to support derived classes that extend the number of menu elements that can be handled. Such classes have to override methods like checkMenuElement(), which therefore cannot be called from the constructor. To ensure a fail-fast approach, checkMenuItems() should be called manually after an instance was constructed. However, this is optional. Invalid data will also be detected when the menu is constructed.
        Throws:
        FormActionException - if invalid data is found in the list of elements to be added to the menu
      • constructPopup

        public void constructPopup​(PopupMenuBuilder builder,
                                   ComponentBuilderData compData)
                            throws FormActionException
        Constructs the menu. This implementation iterates over the collection of menu elements that was passed to the constructor. For each element addMenuElement() is called, which will process the element. If an element found in the collection cannot be handled, an exception is thrown.
        Specified by:
        constructPopup in interface PopupMenuHandler
        Parameters:
        builder - the menu builder
        compData - the component builder data object
        Throws:
        FormActionException - if an invalid element is found in the elements collection
      • getConstructedMenu

        public Object getConstructedMenu()
        Returns the last menu that was constructed by this handler. This method can be called after constructPopup() for gaining access to the created menu object.
        Returns:
        the menu created by the last constructPopup() invocation
      • checkMenuElement

        protected void checkMenuElement​(Object element)
                                 throws FormActionException
        Checks whether the specified menu element can be processed by this handler. This method is called by checkMenuItems(). It checks for FormAction and SimplePopupMenuHandler objects. For all other objects an exception is thrown.
        Parameters:
        element - the element to check
        Throws:
        FormActionException - if the element is not supported
      • addMenuElement

        protected void addMenuElement​(PopupMenuBuilder builder,
                                      ComponentBuilderData compData,
                                      Object element)
                               throws FormActionException
        Adds an element to the menu to be constructed. This method is called by constructPopup() for all elements found in the collection defining the menu. This base implementation checks for FormAction and SimplePopupMenuHandler objects and delegates to the corresponding specific add methods.
        Parameters:
        builder - the menu builder
        compData - the component builder data object
        element - the element to be added
        Throws:
        FormActionException - if the element cannot be handled
      • addAction

        protected void addAction​(PopupMenuBuilder builder,
                                 ComponentBuilderData compData,
                                 FormAction action)
                          throws FormActionException
        Adds an action to the menu constructed by this handler. This method is called by addMenuElement() when an action is encountered.
        Parameters:
        builder - the menu builder
        compData - the component builder data object
        action - the action to be added
        Throws:
        FormActionException - if an error occurs
      • addSubMenu

        protected void addSubMenu​(PopupMenuBuilder builder,
                                  ComponentBuilderData compData,
                                  SimplePopupMenuHandler subHandler)
                           throws FormActionException
        Adds a sub menu to the menu constructed by this handler. This method is called by addMenuElement() when another SimplePopupMenuHandler is encountered representing a sub menu.
        Parameters:
        builder - the menu builder
        compData - the component builder data object
        subHandler - the handler representing the sub menu
        Throws:
        FormActionException - if an error occurs
      • addSeparator

        protected void addSeparator​(PopupMenuBuilder builder,
                                    ComponentBuilderData compData)
                             throws FormActionException
        Adds a separator to the menu constructed by this handler. This method is called by addMenuElement() when a null element is encountered in the elements collection.
        Parameters:
        builder - the menu builder
        compData - the component builder data object
        Throws:
        FormActionException - if an error occurs