com.sas.visuals.adapters
Class PopupMenuAdapter

com.sas.visuals.adapters.PopupMenuAdapter

All Implemented Interfaces:

ContextCommandsConsumerInterface, ContextCommandsInterface, SupportsErrorHandlerInterface, java.awt.event.MouseListener, java.io.Serializable, java.util.EventListener

public class PopupMenuAdapter
implements java.awt.event.MouseListener, SupportsErrorHandlerInterface, ContextCommandsConsumerInterface, ContextCommandsInterface, java.io.Serializable

PopupMenuAdapter is a class to handle populating and displaying a PopupMenu on a java.awt.Component. The menu items are populated based on a list of Commands. ContextCommandsInterface objects are registered to create the Command list based on a context object. A CommandDispatcher object is added as a listener on each MenuItem to execute the Command associated with that MenuItem.
Notes:

• When the component is set, the popupmenu is added to the component and this adapter is added as a mouseListener on the component, if it is not designTime.
• The component is NOT automatically added as a context commands producer.
• If no context has been set, the default context is the component.
• The context is sent as the parameter to the Command.execute(Object) method.
• If the popupMenu is not enabled, it will not be displayed at all.

TreeView
The TreeView component is one component that can use the PopupMenuAdapter. By default, no commands will appear in the popup menu for the TreeView, but if the nodes in the TreeView are set to NodeStyle.EDITABLE, then the PopupMenuAdapter will have a rename command. The following code will do such:

treeView.getDefaultNodeStyle().set(NodeStyle.EDITABLE, new Boolean(true));
treeView.setPopupMenuVisible(false);
PopupMenuAdapter popupMenuAdapter = new PopupMenuAdapter();
popupMenuAdapter.setComponent(treeView);
popupMenuAdapter.addContextCommandsProducer(treeView);


You can add more commands to the popup menu by creating you own list of commands and adding another ContextCommandsProducer. See the code below in the TableView for an example of this. The rename command will be separated from your list of commands by a separator.

TableView
The TableView component can also use the PopupMenuAdapter. Since the TableView has no commands associated with it, the user must create their own class and list of commands to use. The example below will display two commands in the popup menu and will just do a simple print out of the command to the message log when executed:

PopupMenuAdapter popupMenuAdapter = new PopupMenuAdapter();
popupMenuAdapter.setComponent(tableView);
CommandList myCmdList = new CommandList();
myCmdList.add( new MyCommand("Command 1") );
myCmdList.add( new MyCommand("Command 2") );
popupMenuAdapter.addContextCommandsProducer( myCmdList );

...

class CommandList 
   extends OrderedCollection 
   implements ContextCommandsInterface
{
   public Command[] getContextCommands( Object context, int x, int y )
   {
      Object[] array = toArray();
      Command[] cmdArray = new Command[array.length];
      System.arraycopy( array, 0, cmdArray, 0, array.length );
      return cmdArray;
   }
}

class MyCommand
   extends AbstractCommand
{
   public MyCommand( String txt )
   {
      setText(txt);
   {

   public Object clone() throws CloneNotSupportedException
   {
      return new MyCommand( getText() );
   }

   public void execute( Object arg )
   {
      System.out.println( " executed command " + getText() );
   }
}

See Also:

Serialized Form

Field Summary

protected com.sas.collection.OrderedCollectionInterface	commandProducers
protected java.awt.Component	component
protected java.lang.Object	context
protected ErrorHandlerInterface	errHandler
protected java.awt.PopupMenu	popupMenu
protected boolean	popupMenuEnabled
protected boolean	separatorsAdded

Constructor Summary

PopupMenuAdapter()
Default constructor. setComponent() must be called before the adapter can be used.

PopupMenuAdapter(java.awt.Component comp)
Constructor that sets the component to control the popupMenu.

PopupMenuAdapter(java.awt.Component comp, ContextCommandsInterface[] producers)
Constructor that sets the component to control the PopupMenu and the ContextCommandsInterface objects to populate the PopupMenu with.

Method Summary

void	addContextCommandsProducer(ContextCommandsInterface producer) Register a new context commands producer.
java.lang.Object	clone() Clone the PopupMenuAdapter instance.
protected void	connectPopupToComponent() Called to connect the PopupMenu to the Component.
java.awt.Component	getComponent() Get the component whose popup menu is being controlled.
java.lang.Object	getContext() Get the context object used to get the Command list.
com.sas.util.Command[]	getContextCommands(java.lang.Object context, int x, int y) Get the Command objects based on the specified context and position.
ContextCommandsInterface[]	getContextCommandsProducers() Get an array of the registered ContextCommandsProducers.
ErrorHandlerInterface	getErrorHandler() Get the error handler used by all commands that implement the SupportsErrorHandlerInterface.
protected java.awt.PopupMenu	getPopupMenu() Get the PopupMenu to be shown.
boolean	isPopupMenuEnabled() Get whether the popup menu is enabled for the component.
boolean	isSeparatorsAdded() Get whether or not a separator is added between each producer's list of commands.
void	mouseClicked(java.awt.event.MouseEvent event) MouseListener method invoked when the mouse has been clicked on the component.
void	mouseEntered(java.awt.event.MouseEvent event) MouseListener method invoked when the mouse enters the component.
void	mouseExited(java.awt.event.MouseEvent event) MouseListener method invoked when the mouse exits the component.
void	mousePressed(java.awt.event.MouseEvent event) MouseEvent handler to listen for MouseEvents that are popupTriggers.
void	mouseReleased(java.awt.event.MouseEvent event) MouseEvent handler to listen for MouseEvents that are popupTriggers.
protected CommandDispatcher	newCommandDispatcher(com.sas.util.Command command) Factory method for creating a CommandDispatcher to execute the specified Command when the MenuItem is selected.
protected com.sas.collection.OrderedCollectionInterface	newCommandProducerList() Factory method for creating the list to store the command producers in.
protected java.awt.PopupMenu	newPopupMenu() Factory method for creating a PopupMenu for this adapter.
protected java.awt.MenuItem	newPopupMenuItem(com.sas.util.Command command) Factory method for creating a MenuItem from a Command object.
protected void	populateMenu(java.awt.Menu menu, com.sas.util.Command[] cmds) Recursively creates the items to go on the menu.
protected void	populatePopupMenu(java.awt.PopupMenu popupMenu, int x, int y) Helper method to populate the popupMenu with Items.
void	removeContextCommandsProducer(ContextCommandsInterface producer) Unregister a context commands producer.
void	setComponent(java.awt.Component comp) Set the component to listen to MouseEvents on and to add the PopupMenu to.
void	setContext(java.lang.Object cntxt) Set the context object used to get the Command list.
void	setDefaultValues()
void	setErrorHandler(ErrorHandlerInterface errorHandler) Set the error handler used by all commands that implement the SupportsErrorHandlerInterface.
void	setPopupMenuEnabled(boolean enabled) Sets whether the popup menu is enabled for the component.
void	setSeparatorsAdded(boolean addSeparators) Set whether or not a separator is added between each producer's list of commands.
void	showPopupMenu(int x, int y) Display the popup menu for the component.

Field Detail

component

protected java.awt.Component component

context

protected java.lang.Object context

popupMenuEnabled

protected boolean popupMenuEnabled

separatorsAdded

protected boolean separatorsAdded

errHandler

protected ErrorHandlerInterface errHandler

popupMenu

protected java.awt.PopupMenu popupMenu

commandProducers

protected com.sas.collection.OrderedCollectionInterface commandProducers

Constructor Detail

PopupMenuAdapter

public PopupMenuAdapter()

Default constructor. setComponent() must be called before the adapter can be used.

PopupMenuAdapter

public PopupMenuAdapter(java.awt.Component comp)

Constructor that sets the component to control the popupMenu.

Parameters:

component - The component to control the popup menu of.

See Also:

setComponent(java.awt.Component)

PopupMenuAdapter

public PopupMenuAdapter(java.awt.Component comp,
                        ContextCommandsInterface[] producers)

Constructor that sets the component to control the PopupMenu and the ContextCommandsInterface objects to populate the PopupMenu with.

Parameters:

component - The component to control the popup menu of.

producers - An array of ContextCommandsInterface objects that will be used to generate the popup menu for the component.

Method Detail

setDefaultValues

public void setDefaultValues()

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clone the PopupMenuAdapter instance. A new PopupMenuAdapter is created that has the same contextCommandProducers as the original, but the component field is null.

Overrides:

clone in class java.lang.Object

Returns:

the cloned PopupMenuAdapter instance

Throws:

java.lang.CloneNotSupportedException - if the object's class does not support the Cloneable interface.

getContextCommandsProducers

public ContextCommandsInterface[] getContextCommandsProducers()

Get an array of the registered ContextCommandsProducers. The order of the set will reflect the order of registration.

Specified by:

getContextCommandsProducers in interface ContextCommandsConsumerInterface

Returns:

The set of producers; an empty set will be represented by a zero-length array.

See Also:

ContextCommandsConsumerInterface.addContextCommandsProducer(com.sas.util.ContextCommandsInterface)

addContextCommandsProducer

public void addContextCommandsProducer(ContextCommandsInterface producer)

Register a new context commands producer. Does nothing if the producer has already been registered. The producer will be queried for commands whenever populating the popup menu.

Specified by:

addContextCommandsProducer in interface ContextCommandsConsumerInterface

Parameters:

producer - An object that implements ContextCommandsInterface.

See Also:

getContextCommandsProducers()

removeContextCommandsProducer

public void removeContextCommandsProducer(ContextCommandsInterface producer)

Unregister a context commands producer.

Specified by:

removeContextCommandsProducer in interface ContextCommandsConsumerInterface

Parameters:

producer - An object previously passed to addContextCommandsProducer().

See Also:

ContextCommandsConsumerInterface.addContextCommandsProducer(com.sas.util.ContextCommandsInterface)

getContextCommands

public com.sas.util.Command[] getContextCommands(java.lang.Object context,
                                                 int x,
                                                 int y)

Get the Command objects based on the specified context and position.

Specified by:

getContextCommands in interface ContextCommandsInterface

Parameters:

context - The context to return commands for. Each implemenation should define the contexts it accepts.

x - The horizontal coordinate of the location within the visual coordinate space of the context for which the caller would like commands. For example, if this method is being called in response to a mouse click, then x would be the x-position of the click. If the caller doesn't have a location in mind, -1 should be specified. Note that some implementations will find that x is not necessary, so are free to ignore it with appropriate documentation.

y - The vertical coordinate of the location within the visual coordinate space of the context for which the caller would like commands. For example, if this method is being called in response to a mouse click, then y would be the y-position of the click. If the caller doesn't have a location in mind, -1 should be specified. Note that some implementations will find that y is not necessary, so are free to ignore it with appropriate documentation.

Returns:

An array of commands.

isSeparatorsAdded

public boolean isSeparatorsAdded()

Get whether or not a separator is added between each producer's list of commands. The default is true.

Returns:

true if separators are added, false otherwise

setSeparatorsAdded

public void setSeparatorsAdded(boolean addSeparators)

Set whether or not a separator is added between each producer's list of commands. The default is true.

Parameters:

addSeparators - true if separators should be added, false otherwise

mouseClicked

public void mouseClicked(java.awt.event.MouseEvent event)

MouseListener method invoked when the mouse has been clicked on the component. Does nothing.

Specified by:

mouseClicked in interface java.awt.event.MouseListener

mouseEntered

public void mouseEntered(java.awt.event.MouseEvent event)

MouseListener method invoked when the mouse enters the component. Does nothing.

Specified by:

mouseEntered in interface java.awt.event.MouseListener

mouseExited

public void mouseExited(java.awt.event.MouseEvent event)

MouseListener method invoked when the mouse exits the component. Does nothing.

Specified by:

mouseExited in interface java.awt.event.MouseListener

mouseReleased

public void mouseReleased(java.awt.event.MouseEvent event)

MouseEvent handler to listen for MouseEvents that are popupTriggers. If the MouseEvent is a popupTrigger, showPopupMenu(int,int) is called.

Specified by:

mouseReleased in interface java.awt.event.MouseListener

Parameters:

a - MouseEvent to trigger the PopupMenu on

mousePressed

public void mousePressed(java.awt.event.MouseEvent event)

MouseEvent handler to listen for MouseEvents that are popupTriggers. If the MouseEvent is a popupTrigger, showPopupMenu(int,int) is called.

Specified by:

mousePressed in interface java.awt.event.MouseListener

Parameters:

a - MouseEvent to trigger the PopupMenu on

getComponent

public java.awt.Component getComponent()

Get the component whose popup menu is being controlled.

Returns:

The component whose popup menu is being controlled. May be null indicating no component's popup menu is being controlled.

setComponent

public void setComponent(java.awt.Component comp)

Set the component to listen to MouseEvents on and to add the PopupMenu to. This adapter will be removed as a MouseListener from the previous component and the popupMenu will be removed from that components PopupMenu list.

Parameters:

comp - The component to control the popup menu of. The previous component is removed as a MouseListener and as parent of the popup menu.

connectPopupToComponent

protected void connectPopupToComponent()

Called to connect the PopupMenu to the Component. If it is designTime, this method does nothing. This method determines the popupMenu's parent. Then it removes the popupMenu from it's parent and removes this as a mouseListener from the popupMenu parent. The popupMenu is then added to the component and this adapter is added as a MouseListener to the component. This method is currently called by setComponent() and the readObject() methods.

showPopupMenu

public void showPopupMenu(int x,
                          int y)

Display the popup menu for the component. This method will populate the menu using the contextCommandProducers. The previous Menu children are removed and the new ones are added. The popup menu is then shown at the given location relative to the component property.

Parameters:

x - the x location relative to the component property.

y - the y location relative to the component property.

setPopupMenuEnabled

public void setPopupMenuEnabled(boolean enabled)

Sets whether the popup menu is enabled for the component. By default the popupMenu is enabled. If the popupMenu is not enabled, the popupMenu is not shown.

isPopupMenuEnabled

public boolean isPopupMenuEnabled()

Get whether the popup menu is enabled for the component.

getContext

public java.lang.Object getContext()

Get the context object used to get the Command list. If the context is null, the component is sent back as context.

Returns:

the context used to determine the list of Commands. If no context has been set, the component will be returned.

setContext

public void setContext(java.lang.Object cntxt)

Set the context object used to get the Command list.

Parameters:

the - context used to determine the list of Commands. If no context is set, the component will be used as the context.

populatePopupMenu

protected void populatePopupMenu(java.awt.PopupMenu popupMenu,
                                 int x,
                                 int y)

Helper method to populate the popupMenu with Items. The popupMenus are created by getting the appropriate commands based on the context and subcontext. The populateMenu method is called to create the menu items and add the appropriate listener to execute the commands.

populateMenu

protected void populateMenu(java.awt.Menu menu,
                            com.sas.util.Command[] cmds)

Recursively creates the items to go on the menu. A new CommandDispatcher is used to execute the commands.

Parameters:

menu - the menu to populate based on the cmd

cmds - the Commands array to use to populate the Menu.

getPopupMenu

protected java.awt.PopupMenu getPopupMenu()

Get the PopupMenu to be shown. If one hasn't been created yet this will call newPopupMenu() to create the PopupMenu used by this adapter.

Returns:

the PopupMenu used by this adapter.

newPopupMenu

protected java.awt.PopupMenu newPopupMenu()

Factory method for creating a PopupMenu for this adapter.

newCommandDispatcher

protected CommandDispatcher newCommandDispatcher(com.sas.util.Command command)

Factory method for creating a CommandDispatcher to execute the specified Command when the MenuItem is selected. This method creates a com.sas.util.CommandDispatcher object using the Command, the context as the command data and the errorHandler.

Parameters:

command - the Command for the CommandDispatcher to execute when the MenuItem associated with the Command is selected.

Returns:

a CommandDispatcher for the specified Command

newCommandProducerList

protected com.sas.collection.OrderedCollectionInterface newCommandProducerList()

Factory method for creating the list to store the command producers in. This method creates a com.sas.collection.OrderedCollection object.

Returns:

a com.sas.collection.OrderedCollectionInterface object

newPopupMenuItem

protected java.awt.MenuItem newPopupMenuItem(com.sas.util.Command command)

Factory method for creating a MenuItem from a Command object. The MenuItem can be either a Menu, CheckboxMenuItem, or a MenuItem object based on the specified Command. If the Command implements the CommandsInterface, a Menu item will be created. If the Command implements the BooleanDataInterface, a CheckboxMenuItem will be created. If the Command implements the MenuCommand interface and is a Separator, a separator MenuItem will be created. Otherwise a regular MenuItem will be created.

Parameters:

command - the Command to determine what type of MenuItem to create

Returns:

a MenuItem object to trigger the specified Command

setErrorHandler

public void setErrorHandler(ErrorHandlerInterface errorHandler)

Set the error handler used by all commands that implement the SupportsErrorHandlerInterface. When a popupMenu is selected in the popupMenu, the errorHandler is set and the command is executed. The errorHandler is null by default.

Specified by:

setErrorHandler in interface SupportsErrorHandlerInterface

Parameters:

errorHandler - The error handler.

getErrorHandler

public ErrorHandlerInterface getErrorHandler()

Get the error handler used by all commands that implement the SupportsErrorHandlerInterface. When a popupMenu is selected in the popupMenu, the errorHandler is set and the command is executed. The errorHandler is null by default.

Specified by:

getErrorHandler in interface SupportsErrorHandlerInterface

Parameters:

errorHandler - The error handler.