ilog.cpl.interactor
Class IlpAbstractInteractor

java.lang.Object
  ilog.cpl.interactor.IlpAbstractInteractor

All Implemented Interfaces:

IlpInteractor

Direct Known Subclasses:

IlpDefaultObjectInteractor, IlpDefaultTableHeaderInteractor, IlpDefaultViewInteractor

public abstract class IlpAbstractInteractor
extends Object
implements IlpInteractor

Abstract implementation for IlpInteractor.

This implementation is able to manage two kinds of interactions:

• Keyboard interactions
• Mouse and focus interactions

The method processEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.AWTEvent) is called by an IlpGraphicController each time an event occurs on the IlpGraphicView this controller is attached to. This method recognizes IlpGestures from mouse or focus events.

This interactor triggers registered actions when specific gestures or key strokes are recognized.

Register actions as follows:

• Use the method setGestureAction(ilog.cpl.interactor.IlpGesture, javax.swing.Action) to register an action to be triggered when a specific gesture is recognized.
• Use the method setKeyStrokeAction(javax.swing.KeyStroke, javax.swing.Action) to register an action to be triggered when a specific keystroke is recognized

Since:

JTGO 3.0

See Also:

IlpGesture, processEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.AWTEvent), IlpGraphicView, IlpGraphicController

Constructor Summary

IlpAbstractInteractor()

Method Summary

protected ActionEvent	createActionEvent(Action action, IlpInteractionContext ctxt, IlpInteractionState state, int modifiers) Returns a new ActionEvent.
protected ActionEvent	createActionEvent(IlpInteractionContext ctxt, IlpInteractionState state, int modifiers) Deprecated. Please use IlpActionEventFactory instead.
protected boolean	delegateEvent(IlpInteractionContext ctxt, MouseEvent e) This method may be redefined by subclasses if the event process needs to be delegated to a sub-interactor.
protected boolean	displayPopupMenu(IlpInteractionContext ctxt, MouseEvent e) Displays a pop-up menu on the source and at the location given by the specified mouse event if this event corresponds to a pop-up trigger and a pop-up menu factory is set for this interactor and if this factory does not return null.
IlpInteractorAction[]	getAction() Returns the list of interactor actions supported by this instance.
IlpInteractorAction	getAction(int index) Returns the interactor action supported by this instance in the given position.
IlpActionEventFactory	getActionEventFactory() Retrieves the ActionEvent factory used to create events when actions are triggered by this interactor.
Action	getGestureAction(IlpGesture gesture) Returns the customized action associated with the given gesture, if any.
Action	getGestureAction(IlpGesture gesture, int modifiers) Returns the customized action associated with the given gesture, if any.
int	getGestureButton(IlpGesture gesture) Retrieves the mouse button that will trigger the specified gesture.
int	getGestureModifiers(IlpGesture gesture) Deprecated. Please use method setGestureAction(ilog.cpl.interactor.IlpGesture, javax.swing.Action) and (@link #getGestureAction} to register and retrieve actions associated to gestures and modifiers.
protected abstract IlpInteractionState	getInteractionState(IlpInteractionContext ctxt) Looks up the interaction state corresponding to the given context.
Action	getKeyStrokeAction(KeyStroke keyStroke) Retrieves the customized action associated with the given keystroke, if any.
IlpPopupMenuFactory	getPopupMenuFactory() Retrieves the pop-up menu factory used to create a pop-up menu using this interactor, if any.
protected void	manageSelection(IlpInteractionContext ctxt, IlpRepresentationObjectSelectionModel selectionModel, IlpRepresentationObject ro) This method is called before displaying a pop-up menu to update the selection.
boolean	processEvent(IlpInteractionContext ctxt, AWTEvent event) This method is called by an IlpGraphicController each time an event occurs on the IlpGraphicView this controller is attached to.
protected boolean	processGesture(IlpGesture gesture, IlpInteractionContext ctxt, IlpInteractionState state, AWTEvent e) Manages a completely recognized gesture, trying to trigger the associated action.
protected boolean	processKeyEvent(IlpInteractionContext ctxt, KeyEvent event) Manages the key events occurring on the entity to which this interactor is attached.
protected boolean	processMouseOrFocusEvent(IlpInteractionContext ctxt, AWTEvent event) This method recognizes gestures from mouse or focus events and tries to trigger the associated action, if any.
void	setAction(IlpInteractorAction[] actions) Sets the actions supported by this interactor.
void	setAction(int index, IlpInteractorAction action) Sets an action supported by this interactor.
void	setActionEventFactory(IlpActionEventFactory factory) Sets the ActionEvent factory used to create events when actions are triggered by this interactor.
void	setGestureAction(IlpGesture gesture, Action action) Associates an action with a given gesture.
void	setGestureAction(IlpGesture gesture, int modifiers, Action action) Associates an action with a given gesture.
void	setKeyStrokeAction(KeyStroke keyStroke, Action action) Associates an action with the specified keystroke.
void	setPopupMenuFactory(IlpPopupMenuFactory factory) Sets the pop-up menu factory to be used to create a pop-up menu.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlpAbstractInteractor

public IlpAbstractInteractor()

Method Detail

getPopupMenuFactory

public IlpPopupMenuFactory getPopupMenuFactory()

Retrieves the pop-up menu factory used to create a pop-up menu using this interactor, if any.

Specified by:

getPopupMenuFactory in interface IlpInteractor

Returns:

The pop-up menu factory used to create a pop-up menu.

See Also:

setPopupMenuFactory(ilog.cpl.interactor.IlpPopupMenuFactory)

setPopupMenuFactory

public void setPopupMenuFactory(IlpPopupMenuFactory factory)

Sets the pop-up menu factory to be used to create a pop-up menu.

Specified by:

setPopupMenuFactory in interface IlpInteractor

Parameters:

factory - The factory to be used to create a popup menu. If this parameter equals null, no pop-up menu will be displayed.

See Also:

getPopupMenuFactory()

getActionEventFactory

public IlpActionEventFactory getActionEventFactory()

Retrieves the ActionEvent factory used to create events when actions are triggered by this interactor.

Returns:

The factory used to create ActionEvents.

Since:

JTGO 4.0

See Also:

setActionEventFactory(ilog.cpl.interactor.IlpActionEventFactory), createActionEvent(ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, int), IlpActionEventFactory

setActionEventFactory

public void setActionEventFactory(IlpActionEventFactory factory)

Sets the ActionEvent factory used to create events when actions are triggered by this interactor.

Parameters:

factory - The factory to be used to create ActionEvents. If this parameter equals null, events will not be created.

Since:

JTGO 4.0

See Also:

getActionEventFactory(), createActionEvent(ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, int), IlpActionEventFactory

getGestureAction

public Action getGestureAction(IlpGesture gesture)

Returns the customized action associated with the given gesture, if any.

This method returns the action associated with the given gestures without any modifiers.

Specified by:

getGestureAction in interface IlpInteractor

Parameters:

gesture - The gesture with which action is associated.

See Also:

setGestureAction(ilog.cpl.interactor.IlpGesture, javax.swing.Action)

getGestureAction

public Action getGestureAction(IlpGesture gesture,
                               int modifiers)

Returns the customized action associated with the given gesture, if any.

Parameters:

gesture - The gesture with which action is associated.

modifiers - The gesture modifiers which specify when an action should be triggered.

Note: In the modifiers argument, due to overlap in the values of ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK, it is recommended the use of extended modifiers such as InputEvent.ALT_DOWN_MASK instead of InputEvent.ALT_MASK, and InputEvent.META_DOWN_MASK instead of InputEvent.META_MASK.

Since:

JTGO 4.0

See Also:

setGestureAction(ilog.cpl.interactor.IlpGesture, javax.swing.Action), InputEvent

setGestureAction

public void setGestureAction(IlpGesture gesture,
                             Action action)

Associates an action with a given gesture.

Specified by:

setGestureAction in interface IlpInteractor

Parameters:

gesture - The gesture which triggers an action.

action - The action to be triggered by the specified gesture. If this parameter equals null, the specified gesture triggers no action.

Throws:

IllegalArgumentException - if the given gesture equals null.

See Also:

getGestureAction(ilog.cpl.interactor.IlpGesture)

setGestureAction

public void setGestureAction(IlpGesture gesture,
                             int modifiers,
                             Action action)

Associates an action with a given gesture.

Parameters:

gesture - The gesture which triggers an action.

modifiers - The gesture modifiers which trigger an action.

action - The action to be triggered by the specified gesture. If this parameter equals null, the specified gesture triggers no action.

Throws:

IllegalArgumentException - if the given gesture equals null.

Note: In the modifiers argument, InputEvent.ALT_DOWN_MASK should be used instead of InputEvent.ALT_MASK, and InputEvent.META_DOWN_MASK should be used instead of InputEvent.META_MASK, because the values of ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK overlap.

The following example illustrates the use of this method that registers an action that is triggered when button 1 is clicked with the CTRL key pressed.

 setGestureAction (IlpGesture.BUTTON1_CLICKED, InputEvent.CTRL_DOWN_MASK, action);
 

Since:

JTGO 4.0

See Also:

getGestureAction(ilog.cpl.interactor.IlpGesture), InputEvent

getGestureButton

public int getGestureButton(IlpGesture gesture)

Retrieves the mouse button that will trigger the specified gesture. This default implementation always returns MouseEvent.BUTTON1_MASK. Modifications should be implemented by redefining this method. Basic gestures do not use this method since they implicitly involve a button (BUTTON1_CLICKED, for instance).

Specified by:

getGestureButton in interface IlpInteractor

Parameters:

gesture - The gesture concerned.

getGestureModifiers

public int getGestureModifiers(IlpGesture gesture)

Deprecated. Please use method setGestureAction(ilog.cpl.interactor.IlpGesture, javax.swing.Action) and (@link #getGestureAction} to register and retrieve actions associated to gestures and modifiers.

Retrieves the keyboard modifiers that will trigger the specified gesture. This default implementation always returns 0.

Modifications should be implemented by redefining this method.

Note: In the modifiers argument, due to overlap in the values of ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK, it is recommended the use of extended modifiers such as InputEvent.ALT_DOWN_MASK instead of InputEvent.ALT_MASK, and InputEvent.META_DOWN_MASK instead of InputEvent.META_MASK.

Specified by:

getGestureModifiers in interface IlpInteractor

Parameters:

gesture - The gesture concerned.

Deprecated Since:

JTGO 4.0

getKeyStrokeAction

public Action getKeyStrokeAction(KeyStroke keyStroke)

Retrieves the customized action associated with the given keystroke, if any.

Specified by:

getKeyStrokeAction in interface IlpInteractor

Parameters:

keyStroke - The keystroke with which action is associated.

See Also:

setKeyStrokeAction(javax.swing.KeyStroke, javax.swing.Action)

setKeyStrokeAction

public void setKeyStrokeAction(KeyStroke keyStroke,
                               Action action)

Associates an action with the specified keystroke.

Specified by:

setKeyStrokeAction in interface IlpInteractor

Parameters:

keyStroke - The keystroke which triggers an action.

action - The action to be triggered by the specified gesture. If this parameter equals null, no action will be triggered.

Throws:

IllegalArgumentException - if the given keystroke equals null.

See Also:

getKeyStrokeAction(javax.swing.KeyStroke)

setAction

public void setAction(IlpInteractorAction[] actions)

Sets the actions supported by this interactor.

See Also:

IlpGestureAction, IlpKeyStrokeAction

setAction

public void setAction(int index,
                      IlpInteractorAction action)

Sets an action supported by this interactor.

See Also:

IlpInteractorAction

getAction

public IlpInteractorAction[] getAction()

Returns the list of interactor actions supported by this instance.

Returns:

vector with all actions supported by this interactor

getAction

public IlpInteractorAction getAction(int index)

Returns the interactor action supported by this instance in the given position.

Parameters:

index - Index of the action in the interactor collection

processEvent

public boolean processEvent(IlpInteractionContext ctxt,
                            AWTEvent event)

This method is called by an IlpGraphicController each time an event occurs on the IlpGraphicView this controller is attached to.

The method does the following:

1. It delegates the handling to processKeyEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.event.KeyEvent) if the event is a key event.
2. If the event is a mouse event, it tries to delegate it to a sub-interactor, calling delegateEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.event.MouseEvent), or display a popup menu, calling displayPopupMenu(ilog.cpl.interactor.IlpInteractionContext, java.awt.event.MouseEvent).
3. In all other cases, calls processMouseOrFocusEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.AWTEvent).

The given IlpInteractionContext will be used to store contextual information about the event such as partially recognized gestures or mouse position where event occurred.

Specified by:

processEvent in interface IlpInteractor

Parameters:

ctxt - The view where the event occurred.

event - The event that occurred.

See Also:

processKeyEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.event.KeyEvent), delegateEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.event.MouseEvent), displayPopupMenu(ilog.cpl.interactor.IlpInteractionContext, java.awt.event.MouseEvent), processMouseOrFocusEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.AWTEvent), IlpInteractionContext

processMouseOrFocusEvent

protected boolean processMouseOrFocusEvent(IlpInteractionContext ctxt,
                                           AWTEvent event)

This method recognizes gestures from mouse or focus events and tries to trigger the associated action, if any.

The event handling is as follows:

• If the interaction context does not contain any partially recognized gesture:
  • If the event corresponds to an atomic gesture (is composed of one event), tries to trigger the associated action and returns.
  • If the event starts a non-atomic gesture, sets the starting position in the interaction context and the partially recognized gesture and returns.
• If the interaction context already contains partially recognized gestures:
  • If the event ends an incomplete gesture stored in the interaction context, calls processGesture(ilog.cpl.interactor.IlpGesture, ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, java.awt.AWTEvent) to remove the gesture from the incomplete gesture list and tries to trigger the associated action.
  • Removes incomplete gestures which the received event is not part of.

Note:This method may be extended by subclasses to recognize more gestures than the basic ones.

Parameters:

ctxt - The interaction context used to store persistent information.

event - The event that occurred.

Returns:

true if a complete gesture has been recognized and the method processGesture(ilog.cpl.interactor.IlpGesture, ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, java.awt.AWTEvent) returned true, false otherwise.

See Also:

processGesture(ilog.cpl.interactor.IlpGesture, ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, java.awt.AWTEvent), IlpGesture, IlpInteractionContext, setGestureAction(ilog.cpl.interactor.IlpGesture, javax.swing.Action)

processKeyEvent

protected boolean processKeyEvent(IlpInteractionContext ctxt,
                                  KeyEvent event)

Manages the key events occurring on the entity to which this interactor is attached. It looks for an active action associated with the keystroke and executes it.

Note: An action associated with a keystroke will be triggered on KEY_PRESSED, KEY_RELEASED or KEY_TYPED, depending on the way the registered keystroke has been constructed:

• KEY_PRESSED for KeyStroke.getKeyStroke(KeyEvent.VK_A, 0, false)
• KEY_RELEASED for KeyStroke.getKeyStroke(KeyEvent.VK_A, 0, true)
• KEY_TYPED for KeyStroke.getKeyStroke('a')

Parameters:

ctxt - The context where the event occurred.

event - The key event that occurred.

See Also:

processEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.AWTEvent), setKeyStrokeAction(javax.swing.KeyStroke, javax.swing.Action)

delegateEvent

protected boolean delegateEvent(IlpInteractionContext ctxt,
                                MouseEvent e)

This method may be redefined by subclasses if the event process needs to be delegated to a sub-interactor. Default implementation for this method simply returns false.

Parameters:

ctxt - The interaction context of the event.

e - The mouse event to be delegated.

Returns:

true if the given event has been handled by a sub-interactor.

See Also:

processEvent(ilog.cpl.interactor.IlpInteractionContext, java.awt.AWTEvent), IlpInteractionContext

displayPopupMenu

protected boolean displayPopupMenu(IlpInteractionContext ctxt,
                                   MouseEvent e)

Displays a pop-up menu on the source and at the location given by the specified mouse event if this event corresponds to a pop-up trigger and a pop-up menu factory is set for this interactor and if this factory does not return null. When a pop-up menu is triggered, the selection is updated by calling the method manageSelection(ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.util.selection.IlpRepresentationObjectSelectionModel, ilog.cpl.model.IlpRepresentationObject).

Parameters:

ctxt - The interaction context of the event.

e - The mouse event which may correspond to a pop-up trigger.

Returns:

true if a pop-up menu has been shown.

See Also:

setPopupMenuFactory(ilog.cpl.interactor.IlpPopupMenuFactory), manageSelection(ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.util.selection.IlpRepresentationObjectSelectionModel, ilog.cpl.model.IlpRepresentationObject), IlpInteractionContext

manageSelection

protected void manageSelection(IlpInteractionContext ctxt,
                               IlpRepresentationObjectSelectionModel selectionModel,
                               IlpRepresentationObject ro)

This method is called before displaying a pop-up menu to update the selection. The default behavior is the following:

• If there is no object under the mouse, the selection is cleared.
• If there is an object under the mouse and this object is selected, the selection remains unchanged and the pop-up menu should concern the entire selection.
• If there is an object under the mouse and this object is not selected, this object becomes selected, and others deselected.

Subclasses could redefine this method to handle the selection a different way.

Parameters:

ctxt - The interaction context of the event.

selectionModel - The selection model handling the selected objects. It should not be null in this method.

ro - The representation object which was under the mouse when the event occurred. It could be null.

See Also:

displayPopupMenu(ilog.cpl.interactor.IlpInteractionContext, java.awt.event.MouseEvent), setPopupMenuFactory(ilog.cpl.interactor.IlpPopupMenuFactory), IlpInteractionContext

processGesture

protected boolean processGesture(IlpGesture gesture,
                                 IlpInteractionContext ctxt,
                                 IlpInteractionState state,
                                 AWTEvent e)

Manages a completely recognized gesture, trying to trigger the associated action.

1. Removes the recognized gesture from the incomplete gesture list on the interaction context.
2. Sets the mouse position in the interaction context if the given event is a mouse event.
3. Triggers the associated action, if any.
4. Resets the interaction context if it contains no more incomplete gestures to manage.

Parameters:

gesture - The recognized gesture.

ctxt - The interaction context used to store persistent information.

state - The interaction state.

e - The event that ended the gesture.

Returns:

true if an enabled action was associated with the given gesture, false otherwise.

See Also:

createActionEvent(ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, int), IlpGesture, IlpInteractionContext

createActionEvent

protected ActionEvent createActionEvent(IlpInteractionContext ctxt,
                                        IlpInteractionState state,
                                        int modifiers)

Deprecated. Please use IlpActionEventFactory instead.

Returns a new ActionEvent. This method is called when a gesture has been recognized and has an associated action. The created ActionEvent will be passed to the action when it is triggered.

Each subclass has to define an implementation for this method in order to provide the right ActionEvent instance.

Parameters:

ctxt - The context where the event occurred.

state - The interaction's state.

modifiers - The modifiers associated with the recognized gesture.

See Also:

IlpInteractionContext, processGesture(ilog.cpl.interactor.IlpGesture, ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, java.awt.AWTEvent), setActionEventFactory(ilog.cpl.interactor.IlpActionEventFactory), ActionEvent, ActionListener

Deprecated Since:

JTGO 4.0

createActionEvent

protected ActionEvent createActionEvent(Action action,
                                        IlpInteractionContext ctxt,
                                        IlpInteractionState state,
                                        int modifiers)

Returns a new ActionEvent. This method is called when a gesture has been recognized and has an associated action. The created ActionEvent will be passed to the action when it is triggered.

By default, this method checks if there is an IlpActionEventFactory registered. If so, it is used to create the new event. Otherwise, each subclass has to define an implementation for this method in order to provide the right ActionEvent instance.

Parameters:

action - The action that is about to be triggered.

ctxt - The context in which the event occurred.

state - The state of the interaction.

modifiers - The modifiers associated with the recognized gesture.

Since:

JTGO 4.0

See Also:

IlpInteractionContext, processGesture(ilog.cpl.interactor.IlpGesture, ilog.cpl.interactor.IlpInteractionContext, ilog.cpl.interactor.IlpInteractionState, java.awt.AWTEvent), ActionEvent, ActionListener

getInteractionState

protected abstract IlpInteractionState getInteractionState(IlpInteractionContext ctxt)

Looks up the interaction state corresponding to the given context.

Parameters:

ctxt - The context where the event occurred.