com.esri.arcgis.addins.desktop
Class Tool

java.lang.Object
  extended by com.esri.arcgis.addins.desktop.Button
      extended by com.esri.arcgis.addins.desktop.Tool

public abstract class Tool
extends Button

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:


Constructor Summary
Tool()
           
 
Method Summary
abstract  void activate()
          Called when the tool is activated by clicking it.
 boolean deactivate()
          Called by ArcGIS framework when the the tool is active and the user selects another tool instead of using the active tool.
 void init(IApplication app)
          Initializes this button with the ArcGIS application it is hosted in.
 boolean isChecked()
          Returns whether this button is checked.
 boolean isEnabled()
          Returns whether this button is enabled.
 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.
 void onClick()
          Called when the button is clicked.
 boolean onContextMenu(int x, int y)
          Called when a Context menu event occurs at the given xy location.
 void onDoubleClick()
          Called when a mouse button is double clicked when this tool is active.
 void refresh()
          Called when the screen display in the application is refreshed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Tool

public Tool()
Method Detail

onClick

public final void onClick()
                   throws java.io.IOException,
                          AutomationException
Description copied from class: Button
Called when the button is clicked. Subclasses must implement this method to define the action performed when the button is clicked

Specified by:
onClick in class Button
Throws:
java.io.IOException - if there are interop problems.
AutomationException - if the component throws an ArcObjects exception.

activate

public abstract 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
Called by ArcGIS framework when the the tool is active and the user selects another tool instead of using the active tool.

Override this method and return false if this tool should not be interrupted by another tool.

If the tool returns false, the application will not allow the other tool to become active. You may want to return false from deactivate if your tool performs some setup actions in activate() that leave the application in an 'unfinished' state, which can only be completed by using the tool events. Also, you may not want the tool to be deactivated if it is in the middle of an important operation.

Generally, tools should return true when they perform a simple one-step operation and do not change the state of the application beyond their main function. The default implementation returns true.

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

init

public void init(IApplication app)
          throws java.io.IOException,
                 AutomationException
Initializes this button with the ArcGIS application it is hosted in.

This method is automatically called by the host ArcGIS application when the button is initialized. It marks the start of the button's lifecycle. Clients must not call this method.

Overrides:
init in class Button
Parameters:
app - the ArcGIS application that hosts this button
Throws:
java.io.IOException - if there are interop problems.
AutomationException - if the component throws an ArcObjects exception.

isChecked

public boolean isChecked()
                  throws java.io.IOException,
                         AutomationException
Returns whether this button is checked.

The default implementation returns false to indicate that the button is always unchecked.

Override this method if the button is not always unchecked.

Overrides:
isChecked in class Button
Returns:
true if checked, and false if unchecked
Throws:
java.io.IOException
AutomationException

isEnabled

public boolean isEnabled()
                  throws java.io.IOException,
                         AutomationException
Returns whether this button is enabled.

The default implementation returns true to indicate that the button is always enabled.

Override this method if the button is not always enabled.

Overrides:
isEnabled in class Button
Returns:
true if enabled, and false if disabled
Throws:
java.io.IOException
AutomationException

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
Called when a Context menu event occurs at the given xy location.

When creating a custom tool, override this method to display a custom context menu when the right mouse button is pressed when this tool is the active tool.

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 onContextMenu function. If you don't do this, the standard context menu will be displayed after your custom context menu.

Parameters:
x - - the X coordinate, in device units, where the right mouse button was pressed.
y - - the Y coordinate, in device units, where the right mouse button was pressed.
Returns:
true if the custom tool has handled the context menu event
false if the custom tool has not completely handled the context menu event. The standard context menu will be displayed after your custom context menu if you return false. Seeing two context menus for one right click is confusing for users and not recommended.
Throws:
java.io.IOException - if there are interop problems.
AutomationException - if the component throws an ArcObjects exception.

refresh

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

The default implementation does nothing. It ignores the event. Tool developers should override this method if they wish to perform some action when the screen display in the application is refreshed while this tool is the active tool.

Throws:
java.io.IOException
AutomationException