net.sf.jguiraffe.gui.builder.action

Interface PopupMenuBuilder

All Known Implementing Classes:

AbstractPopupMenuBuilder, SwingPopupMenuBuilder

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 Summary

Modifier and Type	Method and Description
PopupMenuBuilder	addAction(FormAction action) Adds an action to the current menu.
PopupMenuBuilder	addSeparator() Adds a separator to the current menu.
PopupMenuBuilder	addSubMenu(Object subMenu) Adds a sub menu to the current menu.
Object	create() Creates the menu and returns a reference to it.
PopupMenuBuilder	subMenuBuilder(ActionData menuDesc) Returns a builder for creating a sub menu.

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