com.esri.arcgis.addinframework
Class InternalTool

java.lang.Object
  extended by com.esri.arcgis.addinframework.AddIn
      extended by com.esri.arcgis.addinframework.InternalButton
          extended by com.esri.arcgis.addinframework.InternalTool
All Implemented Interfaces:
ICommand, ITool, java.io.Serializable
Direct Known Subclasses:
InternalToolComponentTip

public class InternalTool
extends InternalButton
implements ITool

Abstract base implementation of ArcGIS application tools.

This class should be subclassed by clients wishing to define new tools. The name of the subclass should be given as the "class" attribute in a Tool extension contributed to ArcGIS framework. For example, the add-in's XML markup might contain:

      <Commands>
        <Tool id="com.acme.addins.AcmeTool" 
            class="com.acme.addins.AcmeTool" 
            caption="Zoom in" 
            category="Navigation tools" 
            image="Images/zoomin.png">
          <Tip>Zooms in to the specified extent</Tip>
          <Message>Zooms in</Message>
        </Tool>
      </Commands>  
 

Subclasses must implement the following methods:

Subclasses may override the following methods as required:

See Also:
Serialized Form

Constructor Summary
InternalTool()
           
 
Method Summary
 void activate()
          Called when the tool is activated by clicking it.
 boolean deactivate()
          Causes the tool to no longer be the active tool.
 void keyPressed(java.awt.event.KeyEvent keyEvent)
          Called when a key is pressed on the keyboard while the tool is active.
 void keyReleased(java.awt.event.KeyEvent keyEvent)
          Called when a key is released on the keyboard while the tool is active.
 void mouseMoved(java.awt.event.MouseEvent mouseEvent)
          Called when the mouse is moved while the tool is active.
 void mousePressed(java.awt.event.MouseEvent mouseEvent)
          Called when a mouse button is pressed while the tool is active.
 void mouseReleased(java.awt.event.MouseEvent mouseEvent)
          Called when a mouse button is released while the tool is active.
 boolean onContextMenu(int x, int y)
          Context menu event occured at the given xy location.
 void onDoubleClick()
          Called when a mouse button is double clicked when this tool is active.
 void refresh(int hDC)
          Occurs when a screen display in the application is refreshed.
 void seed(java.lang.Object delegate)
           
 
Methods inherited from class com.esri.arcgis.addinframework.InternalButton
init, isChecked, isEnabled, onClick
 
Methods inherited from class com.esri.arcgis.addinframework.AddIn
getApp, nativeGetPictureFromIStream, nativeGetPictureFromStream, read, readCursorFromStream, readPictureFromIStream, readPictureFromStream, readSubnode, setParameters
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.esri.arcgis.systemUI.ITool
getCursor, onDblClick, onKeyDown, onKeyUp, onMouseDown, onMouseMove, onMouseUp
 
Methods inherited from interface com.esri.arcgis.systemUI.ICommand
getBitmap, getCaption, getCategory, getHelpContextID, getHelpFile, getMessage, getName, getTooltip, onCreate
 

Constructor Detail

InternalTool

public InternalTool()
Method Detail

seed

public void seed(java.lang.Object delegate)
Overrides:
seed in class InternalButton

activate

public void activate()
              throws java.io.IOException,
                     AutomationException
Called when the tool is activated by clicking it. Subclasses must implement this method to define the action performed when the tool is activated

Throws:
java.io.IOException - if there are interop problems.
AutomationException - if the component throws an ArcObjects exception.

deactivate

public boolean deactivate()
                   throws java.io.IOException,
                          AutomationException
Causes the tool to no longer be the active tool.

Remarks

When implementing ITool to create a custom tool, add some logic to the Deactivate method to specify whether this tool can be deactivated. If ITool_Deactivate is set to False, the default, you cannot interact with any other tools because this tool cannot be interrupted by another tool.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
deactivate in interface ITool
Returns:
The complete
Throws:
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

keyPressed

public void keyPressed(java.awt.event.KeyEvent keyEvent)
Called when a key is pressed on the keyboard while the tool is active.

The keyEvent parameter can be queried to obtain the key pressed using keyEvemt.getChar() or keyEvent.getKeyCode().

The keyEvent also contains the state of the Shift, Ctrl and Alt keys. This parameter can be used to query the state of these modifier keys using keyEvent.isAltDown() and similar methods.

The parameter does not provide additional information on source of the event

The default implementation does nothing. It ignores the event. Tool developers should override this method if they wish to get notified of this event.

Parameters:
keyEvent - - the KeyEvent corresponding to the key pressed

keyReleased

public void keyReleased(java.awt.event.KeyEvent keyEvent)
Called when a key is released on the keyboard while the tool is active.

The keyEvent parameter can be queried to obtain the key released using keyEvemt.getChar() or keyEvent.getKeyCode().

The keyEvent also contains the state of the Shift, Ctrl and Alt keys. This parameter can be used to query the state of these modifier keys using keyEvent.isAltDown() and similar methods.

The parameter does not provide additional information on source of the event

The default implementation does nothing. It ignores the event. Tool developers should override this method if they wish to get notified of this event.

Parameters:
keyEvent - - the KeyEvent corresponding to the key released

mousePressed

public void mousePressed(java.awt.event.MouseEvent mouseEvent)
Called when a mouse button is pressed while the tool is active.

The mouseEvent parameter can be queried to obtain the mouse button pressed using mouseEvemt.getButton(). The position of the mouse can be queried using mouseEvent.getX() and mouseEvent.getY().

The mouseEvent also contains the state of the Shift, Ctrl and Alt keys. This parameter can be used to query the state of these modifier keys using mouseEvent.isAltDown() and similar methods.

The parameter does not provide additional information on source of the event

The default implementation does nothing. It ignores the event. Tool developers should override this method if they wish to get notified of this event.

Parameters:
mouseEvent - - the MouseEvent corresponding to the mouse pressed event

mouseReleased

public void mouseReleased(java.awt.event.MouseEvent mouseEvent)
Called when a mouse button is released while the tool is active.

The mouseEvent parameter can be queried to obtain the mouse button pressed using mouseEvemt.getButton(). The position of the mouse can be queried using mouseEvent.getX() and mouseEvent.getY().

The mouseEvent also contains the state of the Shift, Ctrl and Alt keys. This parameter can be used to query the state of these modifier keys using mouseEvent.isAltDown() and similar methods.

The parameter does not provide additional information on source of the event

The default implementation does nothing. It ignores the event. Tool developers should override this method if they wish to get notified of this event.

Parameters:
mouseEvent - - the MouseEvent corresponding to the mouse released event

mouseMoved

public void mouseMoved(java.awt.event.MouseEvent mouseEvent)
Called when the mouse is moved while the tool is active.

The mouseEvent parameter can be queried to obtain the mouse button pressed using mouseEvent.getButton(). The position of the mouse can be queried using mouseEvent.getX() and mouseEvent.getY().

The mouseEvent also contains the state of the Shift, Ctrl and Alt keys. This parameter can be used to query the state of these modifier keys using mouseEvent.isAltDown() and similar methods.

The parameter does not provide additional information on source of the event

The default implementation does nothing. It ignores the event. Tool developers should override this method if they wish to get notified of this event.

Parameters:
mouseEvent - - the MouseEvent corresponding to the mouse pressed event

onDoubleClick

public void onDoubleClick()
Called when a mouse button is double clicked when this tool is active. The default implementation does nothing. It ignores the event. Tool developers should override this method if they wish to get notified when a mouse button is double-clicked when this tool is the active tool.


onContextMenu

public boolean onContextMenu(int x,
                             int y)
                      throws java.io.IOException,
                             AutomationException
Context menu event occured at the given xy location.

Description

X is the X coordinate, in device units, where the right mouse button was pressed.

Y is the Y coordinate, in device units, where the right mouse button was pressed.

Remarks

When implementing ITool to create a custom tool, write code to display a custom context menu when the right mouse button is pressed when this tool is the active tool in the OnContext method.

If your tool displays a custom context menu, it should let the application know that it handled the OnContextMenu event by returning True from the OnContext function. If you don't do this, the standard context menu will be displayed after your custom context menu.

This method does not fire in ArcGIS Engine. A context menu is implemented using IToolbarMenu in ArcGIS Engine as illustrated by the ControlsEditingSketchContextMenu command.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
onContextMenu in interface ITool
Parameters:
x - The x (in)
y - The y (in)
Returns:
The handled
Throws:
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

refresh

public void refresh(int hDC)
             throws java.io.IOException,
                    AutomationException
Occurs when a screen display in the application is refreshed.

Description

hDC is the handle to the display context which just got refreshed in the application.

Remarks

When implementing ITool to create a custom tool, write the code in the Refresh method that performs some action when a screen display in the application is refreshed while this tool is the active tool. When the current screen display in the application is refreshed, the handle to the device context that is associated with that screen display is passed into the Refresh method as an argument.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
refresh in interface ITool
Parameters:
hdc - The hdc (A COM typedef) (in)
Throws:
java.io.IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.