net.sf.jguiraffe.gui.builder.action

Class SimplePopupMenuHandler

java.lang.Object

net.sf.jguiraffe.gui.builder.action.ActionDataImpl

net.sf.jguiraffe.gui.builder.action.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 Summary

Constructors

Constructor and Description
SimplePopupMenuHandler(Collection<?> items) Creates a new instance of SimplePopupMenuHandler and initializes it with the content of the menu.

Method Summary

Modifier and Type	Method and Description
protected void	addAction(PopupMenuBuilder builder, ComponentBuilderData compData, FormAction action) Adds an action to the menu constructed by this handler.
protected void	addMenuElement(PopupMenuBuilder builder, ComponentBuilderData compData, Object element) Adds an element to the menu to be constructed.
protected void	addSeparator(PopupMenuBuilder builder, ComponentBuilderData compData) Adds a separator to the menu constructed by this handler.
protected void	addSubMenu(PopupMenuBuilder builder, ComponentBuilderData compData, SimplePopupMenuHandler subHandler) Adds a sub menu to the menu constructed by this handler.
protected void	checkMenuElement(Object element) Checks whether the specified menu element can be processed by this handler.
void	checkMenuItems() Tests whether all menu elements to be processed by this handler are supported.
void	constructPopup(PopupMenuBuilder builder, ComponentBuilderData compData) Constructs the menu.
Object	getConstructedMenu() Returns the last menu that was constructed by this handler.
List<?>	getMenuItems() Returns a list with the content of the menu to be constructed by this handler.

Methods inherited from class net.sf.jguiraffe.gui.builder.action.ActionDataImpl

getAccelerator, getIcon, getMnemonicKey, getName, getTask, getText, getToolTip, setAccelerator, setActionData, setIcon, setMnemonicKey, setName, setTask, setText, setToolTip

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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