Interface PopupMenuBuilder

  • All Known Implementing Classes:
    AbstractPopupMenuBuilder

    public interface PopupMenuBuilder

    A builder interface for creating popup menus.

    Using the methods defined in this interface arbitrary complex popup menus can be created. A popup menu consists of an arbitrary number of FormAction objects plus optional separators and sub menus. The basic usage pattern is to invoke the several add() methods for defining the menu's content. Finally the create() method must be called, which will actually create the menu.

    This interface provides a platform-independent view on popup menus. There will be concrete implementations for the GUI libraries supported. These implementations take care of creating the correct, platform-specific menu objects.

    As is common practice for builder-like structures this interface supports method chaining, i.e. most methods return a reference to the builder itself, which can be used for immediately adding the next element. The following example fragment shows how a popup menu with some items and a sub menu can be constructed. It assumes that the references to the actions involved are defined somewhere else:

     PopupMenuBuilder builder = ...  // obtain the builder
    
     Object popup = builder
         .addAction(actionOpen)
         .addAction(actionSave)
         .addAction(actionSaveAs)
         .addSeparator()
         .addSubMenu(builder.subMenuBuilder(tiMenuEdit)
             .addAction(actionCopy)
             .addAction(actionCut)
             .addAction(actionPaste)
             .create())
         .addSeparator()
         .addAction(actionExit)
         .create();
     

    Version:
    $Id: $
    Author:
    Oliver Heger
    • Method Detail

      • addAction

        PopupMenuBuilder addAction​(FormAction action)
        Adds an action to the current menu. This will create a menu item that invokes this action when it is selected by the user. The properties of this item (like text, icon, etc.) are obtained from the action object.
        Parameters:
        action - the action to be added (must not be null)
        Returns:
        a reference to this builder
        Throws:
        IllegalArgumentException - if the action is null
      • addSeparator

        PopupMenuBuilder addSeparator()
        Adds a separator to the current menu. Separators can be used for grouping related menu items.
        Returns:
        a reference to this builder
      • addSubMenu

        PopupMenuBuilder addSubMenu​(Object subMenu)
        Adds a sub menu to the current menu. This allows for complex structures of hierarchical menus. The object passed to this method must be a menu that was created by a sub menu builder.
        Parameters:
        subMenu - the sub menu to add (must not be null)
        Returns:
        a reference to this builder
        Throws:
        IllegalArgumentException - if the sub menu is null
        See Also:
        subMenuBuilder(ActionData)
      • subMenuBuilder

        PopupMenuBuilder subMenuBuilder​(ActionData menuDesc)
        Returns a builder for creating a sub menu. The builder returned by this method can be used to define the sub menu (i.e. add actions, separators, and further sub menus as desired). Its create() method returns the menu created. The passed in ActionData object contains the definition of the menu as it will be displayed in the parent menu (i.e. its text, icon, etc.).
        Parameters:
        menuDesc - an ActionData object with the properties of the sub menu (must not be null)
        Returns:
        a builder for defining the new sub menu
        Throws:
        IllegalArgumentException - if the menu description is null
      • create

        Object create()
        Creates the menu and returns a reference to it. If this is the top-level builder (i.e. not a builder for a sub menu), the popup menu will be displayed.
        Returns:
        the menu created by this builder