IlvChartInteractor (Perforce JViews 10.0 API)

java.lang.Object
- ilog.views.chart.IlvChartInteractor

All Implemented Interfaces:

IlvChart3DSupport, Serializable

Direct Known Subclasses:

IlvChart3DViewInteractor, IlvChartActionInteractor, IlvChartCycleSelectInteractor, IlvChartDataIndicatorInteractor, IlvChartDataInteractor, IlvChartLocalReshapeInteractor, IlvChartPanInteractor, IlvChartScrollInteractor, IlvChartZoomInteractor
```
public abstract class IlvChartInteractor
extends Object
implements IlvChart3DSupport, Serializable
```
This abstract class is the base class of all the interactors.
Chart interactors should be seen as atomic interactions that can be combined together to build more complex interactions. For example, if you want to be able to zoom the chart using the left mouse button and at the same time be able to pan the chart using the right mouse button :
```
     IlvChartInteractor inter = IlvChartInteractor.create("Zoom");
     chart.addInteractor(inter);
     inter = IlvChartInteractor.create("Pan");
     chart.addInteractor(inter);
     ...
 
```
A chart handles interactors as a list and process the events to interactors according to decreasing priority order. When an input event is received by the chart (actually the chart area), it is forwarded to all the interactors, until one of them consumes the event. That is, you have to take into account the types of events expected by the interactors and their action keys - in case they overlap - when assigning the priorities. In the sample above, there will be no conflicts between both the interactors due to their default configuration (zoom on the left mouse button, pan on the right mouse button). Since a chart forwards every input events to all of its interactors until one of them handles it (if any), the interactor that handled the event must set it as consumed so that it is no longer forwarded (see java.awt.AWTEvent.consumed()).
An interactor is associated with a chart and with a specific y-axis so that interactions performed on the chart using an interactor are only possible on the renderer attached to the same y-axis. It cannot be shared among several charts.

An interaction is defined according to three steps: when the interaction begins, when the interactions ends, and when the interaction is aborted. Each of these steps has a corresponding method that can be overridden to handle the state changes (startOperation(java.awt.event.MouseEvent), endOperation(java.awt.event.MouseEvent), abort()). While writing an interactor class, the programmer is responsible for defining these different states calling these callbacks when appropriate.

Interactor classes can be associated with a name (its shortname) and stored in an internal repository allowing the instantiation of any known interactor classes by shortcut name (see create(java.lang.String)). For example :

to register your own IlvChartInteractor subclass into the repository:
```
     class MyInteractor extends IlvChartInteractor {
         static {
             IlvChartInteractor.register("MyInter", MyInteractor.class);
         }
     ...
 
```
to get a new IlvChartEditPointInteractor instance by its shortname:
```
     IlvChartInteractor inter = IlvChartInteractor.create("EditPoint");
 
```
Interactors can have a localized name. In order to carry a localized name, an interactor class should carry a public static function
```
     public static String getLocalizedName(Locale locale) {
         ...
     }
 
```
Since:

JViews 5.0

See Also:

IlvChart.addInteractor(ilog.views.chart.IlvChartInteractor), Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`INTERNAL_HIGH` The priority value for high-priority internal interactors.
`static int`	`INTERNAL_LOW` The priority value for low-priority internal interactors.
`static int`	`NORMAL` The default priority value for public interactors.

Constructor Summary

Constructors
Constructor and Description
`IlvChartInteractor()` Creates a new `IlvChartInteractor` object associated to the y-axis of index `0`, with no action key.
`IlvChartInteractor(int yAxisIndex, int buttonOrKeyEventMask)` Creates a new `IlvChartInteractor` object associated to the given y-axis with the specified action key.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`abort()` Called when the interaction has been aborted.
`void`	`addChartInteractionListener(ChartInteractionListener l)` Adds a new interactor listener.
`protected void`	`chartConnected(IlvChart oldChart, IlvChart newChart)` Called when an interactor has been added to a chart.
`static IlvChartInteractor`	`create(String interName)` Creates a new interactor object according to a name.
`static IlvChartInteractor`	`create(String interName, boolean exception)` Creates a new interactor object according to a name.
`protected void`	`disableEvents(long mask)` Removes the given events from the handled events list.
`protected void`	`drawGhost()` Calls drawGhost(java.awt.Graphics).
`protected void`	`drawGhost(Graphics g)` This method may be overridden to do some temporary drawing during the interaction.
`protected void`	`enableEvents(long mask)` Adds the given events to the handled events list.
`protected void`	`endOperation(MouseEvent event)` Called when the interaction ends.
`protected void`	`fireChartInteractionEvent(ChartInteractionEvent event)` Fires a `ChartInteractionEvent`
`long`	`getAWTEventMask()` Returns the event mask.
`IlvChart`	`getChart()` Returns the chart on which the interactor has been attached to.
`IlvCoordinateSystem`	`getCoordinateSystem()` Returns the `IlvCoordinateSystem` owning the associated y-axis.
`IlvDoublePoint`	`getData(int x, int y)` Returns the data values corresponding to the specified display coordinates.
`IlvDoublePoint`	`getData(MouseEvent event)` Returns the data values corresponding to the coordinates of the specified mouse event.
`int`	`getEventMask()` Returns the action event mask.
`int`	`getEventMaskEx()` Returns the action event mask, according to the conventions of `java.awt.event.InputEvent.getModifiersEx()`.
`protected Rectangle`	`getGhostBounds()` Returns the ghost bounds.
`Color`	`getGhostColor()` Returns the color used during the ghost drawing operation.
`static Class<?>`	`getInteractorClassByName(String shortName)` Returns the interactor class associated with a given short name.
`static String`	`getLocalizedName(Class<?> interactorClass, Locale locale)` Returns the localized name of an interactor class in a given locale.
`int`	`getPriority()` Returns the priority of this interactor.
`static String[]`	`getRegisteredInteractorsByName()` Returns all the registered interactor classes using their short name.
`static String`	`getShortName(Class<?> interactorClass)` Returns the short name associated to the given interactor class.
`IlvAxis`	`getXAxis()` Returns the x-axis of the attached chart.
`Color`	`getXORColor()` Returns the XOR color.
`IlvAxis`	`getYAxis()` Returns the associated y-axis.
`int`	`getYAxisIndex()` Returns the associated y-axis index.
`void`	`handleExpose(Graphics g)` Called by the chart when the chart area is drawn.
`boolean`	`has3DSupport()` Indicates whether the interactor can be used with a 3D chart.
`protected void`	`initGhostGraphics(Graphics g)` Initializes the `g` according to the ghost properties.
`void`	`interactionStarted(IlvChartInteractor inter, MouseEvent event)` Called when the given interactor is about to start an interaction on the given event.
`boolean`	`isAborted()` Returns whether the interactor is in aborted state.
`protected boolean`	`isAllowDrawGhost()` Returns whether a ghost can be drawn.
`boolean`	`isConsumeEvents()` Returns `true` if this interactor consumes the events that it has recognized.
`boolean`	`isHandling(int x, int y)` Returns whether the mouse event that occurred at the specified location should be handled by the interactor.
`boolean`	`isInOperation()` Returns whether the interactor is in operation state.
`boolean`	`isXORGhost()` Returns whether the interactor draws its ghost in XOR mode.
`void`	`processKeyEvent(KeyEvent event)` Handles a `KeyEvent` event.
`void`	`processMouseEvent(MouseEvent event)` Handles a mouse event.
`void`	`processMouseMotionEvent(MouseEvent event)` Handles a mouse motion event.
`protected static void`	`register(String shortName, Class<?> interClass)` Registers the given class with the specified short name A registered interactor can then be instantiated using its short name.
`void`	`removeChartInteractionListener(ChartInteractionListener l)` Removes `l` from the interactor listeners.
`protected void`	`setAborted(boolean aborted)` Sets whether the interactor is in aborted state.
`protected void`	`setAllowDrawGhost(boolean allow)` Sets whether a ghost can be drawn.
`void`	`setChart(IlvChart chart)` Called when this interactor is attached to a chart or detached from its current chart.
`void`	`setConsumeEvents(boolean consume)` Determines whether this interactor should consume the events that it has recognized.
`protected Cursor`	`setCursor(Cursor cursor)` Sets the current mouse cursor.
`void`	`setEventMask(int actionEventMask)` Sets the action event mask.
`void`	`setGhostColor(Color color)` Sets the color used during the ghost drawing operation.
`protected void`	`setInOperation(boolean ended)` Sets whether the interactor is in operation state.
`void`	`setPriority(int priority)` Sets the priority of this interactor.
`void`	`setXORColor(Color xorColor)` Sets the XOR color.
`void`	`setXORGhost(boolean useXOR)` Sets whether the interactor draws its ghost in XOR mode.
`void`	`setYAxisIndex(int index)` Sets the associated y-axis index.
`protected void`	`startOperation(MouseEvent event)` Called when the interaction starts.
`IlvDoublePoint`	`toDisplay(IlvDoublePoint pt)` Returns the display coordinates corresponding to the specified data value.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - INTERNAL_HIGH
```
public static final int INTERNAL_HIGH
```
    The priority value for high-priority internal interactors.
    
    Since:
    
    JViews 6.0
    
    See Also:
    
    getPriority(), Constant Field Values
  - NORMAL
```
public static final int NORMAL
```
    The default priority value for public interactors.
    
    Since:
    
    JViews 6.0
    
    See Also:
    
    getPriority(), Constant Field Values
  - INTERNAL_LOW
```
public static final int INTERNAL_LOW
```
    The priority value for low-priority internal interactors.
    
    Since:
    
    JViews 6.0
    
    See Also:
    
    getPriority(), Constant Field Values
- Constructor Detail
  - IlvChartInteractor
```
public IlvChartInteractor()
```
    Creates a new IlvChartInteractor object associated to the y-axis of index 0, with no action key.
  - IlvChartInteractor
```
public IlvChartInteractor(int yAxisIndex,
                          int buttonOrKeyEventMask)
```
    Creates a new IlvChartInteractor object associated to the given y-axis with the specified action key.
    
    Parameters:
    
    yAxisIndex - The y-axis index.
    
    buttonOrKeyEventMask - A valid KeyEvent/MouseEvent key/button mask.
- Method Detail
  - register
```
protected static void register(String shortName,
                               Class<?> interClass)
```
    Registers the given class with the specified short name A registered interactor can then be instantiated using its short name.
    
    See Also:
    
    create(java.lang.String)
  - getInteractorClassByName
```
public static Class<?> getInteractorClassByName(String shortName)
```
    Returns the interactor class associated with a given short name. Returns null if no class with the given short name is registered so far.
    
    Since:
    
    JViews 7.5
    
    See Also:
    
    register(java.lang.String, java.lang.Class<?>)
  - getShortName
```
public static String getShortName(Class<?> interactorClass)
```
    Returns the short name associated to the given interactor class. Returns null if no class is found.
  - create
```
public static IlvChartInteractor create(String interName)
```
    Creates a new interactor object according to a name. The internal repository is checked first to find an interactor class associated to interName. If no class is found, then interName is supposed to be a class name and the interactor is created using the Java Reflection mechanism.
    Note: The short name of an interactor is put in the registry when the class of this interactor is loaded. You must thus explicitly load the class (for example using Class.forName()) before using the short name as a parameter to this method.
    
    Parameters:
    
    interName - The name associated to the interactor or a full qualified class name.
    
    Returns:
    
    An instance of the requested class or null if no corresponding class is found.
    
    See Also:
    
    register(java.lang.String, java.lang.Class<?>), getInteractorClassByName(java.lang.String), create(String,boolean)
  - create
```
public static IlvChartInteractor create(String interName,
                                        boolean exception)
                                 throws ClassNotFoundException,
                                        InstantiationException,
                                        IllegalAccessException
```
    Creates a new interactor object according to a name.
    
    Parameters:
    
    interName - The name of the interactor.
    
    exception - Whether exception should be thrown, or only reported on the standard error output stream.
    
    Returns:
    
    An instance of the requested class.
    
    Throws:
    
    ClassNotFoundException
    
    InstantiationException
    
    IllegalAccessException
    
    Since:
    
    JViews 5.5
    
    See Also:
    
    create(String)
  - getRegisteredInteractorsByName
```
public static String[] getRegisteredInteractorsByName()
```
    Returns all the registered interactor classes using their short name.
  - getLocalizedName
```
public static String getLocalizedName(Class<?> interactorClass,
                                      Locale locale)
```
    Returns the localized name of an interactor class in a given locale. If the class does not have a public static method String getLocalizedName(Locale), the corresponding short name is used, if it exists. Otherwise the class name, without package prefix, is used as a fallback.
    
    Since:
    
    JViews 7.5
  - getPriority
```
public final int getPriority()
```
    Returns the priority of this interactor.
    The framework distinguishes two kinds of interactors:
    - user interactors that are explicitly set on a chart by the user. These interactors have a priority between -1000 and 1000. The default is NORMAL priority.
    - internal interactors that are set on a chart indirectly. These interactors are usually hidden to the user (that is, they are not returned by IlvChart.getInteractors()) and can have either an INTERNAL_HIGH priority (they are processed first before the user interactors) or INTERNAL_LOW priority (they are process last after the user interactors).
    Returns:
    
    The interactor priority. Higher values mean higher priority.
    
    Since:
    
    JViews 6.0
  - setPriority
```
public void setPriority(int priority)
```
    Sets the priority of this interactor.
    
    Parameters:
    
    priority - The new priority of this interactor. It should be a value between -1000 and 1000 (exclusive).
    
    Since:
    
    JViews 8.1
  - getXAxis
```
public final IlvAxis getXAxis()
```
    Returns the x-axis of the attached chart.
  - getYAxis
```
public final IlvAxis getYAxis()
```
    Returns the associated y-axis.
  - getCoordinateSystem
```
public final IlvCoordinateSystem getCoordinateSystem()
```
    Returns the IlvCoordinateSystem owning the associated y-axis.
  - getChart
```
public final IlvChart getChart()
```
    Returns the chart on which the interactor has been attached to.
  - setChart
```
public final void setChart(IlvChart chart)
```
    Called when this interactor is attached to a chart or detached from its current chart.
    This method invokes chartConnected(ilog.views.chart.IlvChart, ilog.views.chart.IlvChart).
    
    Parameters:
    
    chart - The chart to which this interactor is being attached to, or null when it is being detached.
    
    Since:
    
    JViews 8.1
  - chartConnected
```
protected void chartConnected(IlvChart oldChart,
                              IlvChart newChart)
```
    Called when an interactor has been added to a chart. You should not call this method directly.
    
    Parameters:
    
    oldChart - The previous attached chart.
    
    newChart - The new attached chart.
    
    See Also:
    
    IlvChart.addInteractor(ilog.views.chart.IlvChartInteractor)
  - getAWTEventMask
```
public final long getAWTEventMask()
```
    Returns the event mask. This mask matches the events handled by the interactor using the standard InputEvent mask values.
    
    Since:
    
    JViews 8.1
  - enableEvents
```
protected final void enableEvents(long mask)
```
    Adds the given events to the handled events list.
  - disableEvents
```
protected final void disableEvents(long mask)
```
    Removes the given events from the handled events list.
  - isAborted
```
public final boolean isAborted()
```
    Returns whether the interactor is in aborted state.
  - setAborted
```
protected void setAborted(boolean aborted)
```
    Sets whether the interactor is in aborted state.
  - isInOperation
```
public final boolean isInOperation()
```
    Returns whether the interactor is in operation state.
  - setInOperation
```
protected void setInOperation(boolean ended)
```
    Sets whether the interactor is in operation state.
  - getYAxisIndex
```
public final int getYAxisIndex()
```
    Returns the associated y-axis index.
  - setYAxisIndex
```
public void setYAxisIndex(int index)
```
    Sets the associated y-axis index.
  - getEventMask
```
public final int getEventMask()
```
    Returns the action event mask.
    
    See Also:
    
    setEventMask(int), getEventMaskEx()
  - getEventMaskEx
```
public final int getEventMaskEx()
```
    Returns the action event mask, according to the conventions of java.awt.event.InputEvent.getModifiersEx(). This mask is computed from getEventMask().
    
    Since:
    
    JViews 7.5
    
    See Also:
    
    getEventMask(), setEventMask(int)
  - setEventMask
```
public void setEventMask(int actionEventMask)
```
    Sets the action event mask.
    Note: In the mask, InputEvent.BUTTON2_DOWN_MASK should be used instead of InputEvent.BUTTON2_MASK, and InputEvent.BUTTON3_DOWN_MASK should be used instead of InputEvent.BUTTON3_MASK, because the values of ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK overlap.
    
    Parameters:
    
    actionEventMask - A valid KeyEvent/MouseEvent key/button value.
  - isConsumeEvents
```
public boolean isConsumeEvents()
```
    Returns true if this interactor consumes the events that it has recognized.
    
    Since:
    
    JViews 7.5
  - setConsumeEvents
```
public void setConsumeEvents(boolean consume)
```
    Determines whether this interactor should consume the events that it has recognized.
    By default, interactors do consume events. Set this to false if you have several interactors watching out for the same events.
    
    Since:
    
    JViews 7.5
  - getGhostColor
```
public Color getGhostColor()
```
    Returns the color used during the ghost drawing operation.
  - setGhostColor
```
public void setGhostColor(Color color)
```
    Sets the color used during the ghost drawing operation.
    
    See Also:
    
    drawGhost()
  - getXORColor
```
public final Color getXORColor()
```
    Returns the XOR color.
    
    See Also:
    
    setXORColor(java.awt.Color)
  - setXORColor
```
public void setXORColor(Color xorColor)
```
    Sets the XOR color. This color is passed to java.awt.Graphics.setXORMode(). The default value is Color.black.
  - isAllowDrawGhost
```
protected final boolean isAllowDrawGhost()
```
    Returns whether a ghost can be drawn. The default value is false (nothing to redraw). This property is used to know if a repaint event should be forwarded to the active interactor to draw the ghost.
  - setAllowDrawGhost
```
protected void setAllowDrawGhost(boolean allow)
```
    Sets whether a ghost can be drawn.
  - isXORGhost
```
public final boolean isXORGhost()
```
    Returns whether the interactor draws its ghost in XOR mode.
  - setXORGhost
```
public void setXORGhost(boolean useXOR)
```
    Sets whether the interactor draws its ghost in XOR mode.
    
    See Also:
    
    isXORGhost()
  - getGhostBounds
```
protected Rectangle getGhostBounds()
```
    Returns the ghost bounds. The default implementation returns null, meaning that no ghost is drawn. Since this method is used to compute the clipping rectangle, you should override this method if your interactor performs drawing operations during the interaction.
  - isHandling
```
public boolean isHandling(int x,
                          int y)
```
    Returns whether the mouse event that occurred at the specified location should be handled by the interactor. The default implementation returns true if the event occurred inside the projection area. You can override this method to modify the sensitive area of an interactor.
  - getData
```
public final IlvDoublePoint getData(MouseEvent event)
```
    Returns the data values corresponding to the coordinates of the specified mouse event.
  - getData
```
public final IlvDoublePoint getData(int x,
                                    int y)
```
    Returns the data values corresponding to the specified display coordinates.
  - toDisplay
```
public final IlvDoublePoint toDisplay(IlvDoublePoint pt)
```
    Returns the display coordinates corresponding to the specified data value.
    
    Since:
    
    JViews 8.1
  - processMouseEvent
```
public void processMouseEvent(MouseEvent event)
```
    Handles a mouse event. When an event is received by the chart, it is dispatched to all of its interactors until one of them consumes the event.
  - processMouseMotionEvent
```
public void processMouseMotionEvent(MouseEvent event)
```
    Handles a mouse motion event. When an event is received by the chart, it is dispatched to all of its interactors until one of them consumes the event.
  - processKeyEvent
```
public void processKeyEvent(KeyEvent event)
```
    Handles a KeyEvent event. When an event is received by the chart, it is dispatched to all of its interactors until one of them consumes the event.
  - handleExpose
```
public void handleExpose(Graphics g)
```
    Called by the chart when the chart area is drawn. This method first initializes the graphics context according to the interactor ghost properties and then calls drawGhost(java.awt.Graphics).
    
    Parameters:
    
    g - The graphic context.
    
    See Also:
    
    drawGhost(java.awt.Graphics)
  - drawGhost
```
protected final void drawGhost()
```
    Calls drawGhost(java.awt.Graphics). You should call this method in your interactor subclass when you want to perform a ghost drawing operation.
  - drawGhost
```
protected void drawGhost(Graphics g)
```
    This method may be overridden to do some temporary drawing during the interaction.
  - initGhostGraphics
```
protected void initGhostGraphics(Graphics g)
```
    Initializes the g according to the ghost properties.
  - interactionStarted
```
public void interactionStarted(IlvChartInteractor inter,
                               MouseEvent event)
```
    Called when the given interactor is about to start an interaction on the given event. The default implementation does nothing. You may override this method if your interactor needs to perform some work before another interaction starts.
  - startOperation
```
protected void startOperation(MouseEvent event)
```
    Called when the interaction starts. This method notifies all interactors that this interactor is about to start an interaction. You may override this method to add your own initialization code.
    
    Parameters:
    
    event - The event that starts the interaction.
    
    See Also:
    
    interactionStarted(ilog.views.chart.IlvChartInteractor, java.awt.event.MouseEvent)
  - endOperation
```
protected void endOperation(MouseEvent event)
```
    Called when the interaction ends. You may override this method to add your own reinitialization code.
    
    Parameters:
    
    event - The event that ends the interaction.
  - abort
```
protected void abort()
```
    Called when the interaction has been aborted. You may override this method to add your own reinitialization code.
  - setCursor
```
protected Cursor setCursor(Cursor cursor)
```
    Sets the current mouse cursor. Passing null removes the current cursor and installs the previous one.
    
    Returns:
    
    The previous cursor (may be the removed cursor if the parameter is null).
  - addChartInteractionListener
```
public final void addChartInteractionListener(ChartInteractionListener l)
```
    Adds a new interactor listener.
  - removeChartInteractionListener
```
public final void removeChartInteractionListener(ChartInteractionListener l)
```
    Removes l from the interactor listeners.
  - fireChartInteractionEvent
```
protected final void fireChartInteractionEvent(ChartInteractionEvent event)
```
    Fires a ChartInteractionEvent
    
    Parameters:
    
    event - The event to fire.
  - has3DSupport
```
public boolean has3DSupport()
```
    Indicates whether the interactor can be used with a 3D chart. The default implementation returns true.
    
    Specified by:
    
    has3DSupport in interface IlvChart3DSupport
    
    Since:
    
    JViews 5.5

Class IlvChartInteractor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

INTERNAL_HIGH

NORMAL

INTERNAL_LOW

Constructor Detail

IlvChartInteractor

IlvChartInteractor

Method Detail

register

getInteractorClassByName

getShortName

create

create

getRegisteredInteractorsByName

getLocalizedName

getPriority

setPriority

getXAxis

getYAxis

getCoordinateSystem

getChart

setChart

chartConnected

getAWTEventMask

enableEvents

disableEvents

isAborted

setAborted

isInOperation

setInOperation

getYAxisIndex

setYAxisIndex

getEventMask

getEventMaskEx

setEventMask

isConsumeEvents

setConsumeEvents

getGhostColor

setGhostColor

getXORColor

setXORColor

isAllowDrawGhost

setAllowDrawGhost

isXORGhost

setXORGhost

getGhostBounds

isHandling

getData

getData

toDisplay

processMouseEvent

processMouseMotionEvent

processKeyEvent

handleExpose

drawGhost

drawGhost

initGhostGraphics

interactionStarted

startOperation

endOperation

abort

setCursor

addChartInteractionListener

removeChartInteractionListener

fireChartInteractionEvent

has3DSupport