com.esri.arcgis.addins.desktop
Class Tool

java.lang.Object
  com.esri.arcgis.addins.desktop.Button
      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:

• activate - to define the action performed when the tool is activated

Subclasses may override the following methods as required:

• init - to initializes this tool and get a reference to the hosting ArcGIS application
• deactivate - to perform some action when the user deactivates this tool, or to conditionally prevent the deactivation
• isChecked - if this tool is not always unchecked
• isEnabled - if this tool is not always enabled
• keyPressed - if this tool needs to respond to key presses
• keyReleased - if this tool needs to respond to key release events
• mousePressed - if this tool needs to respond to mouse button presses
• mouseReleased - if this tool needs to respond to mouse button release events
• mouseMoved - if this tool needs to respond to mouse move events
• onDoubleClick - if this tool needs to respond to double click events
• onContextMenu - if this tool shows a custom context menu
• refresh - is this tools needs to be notified when the screen display is refreshed

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(KeyEvent keyEvent) Called when a key is pressed on the keyboard while the tool is active.
void	keyReleased(KeyEvent keyEvent) Called when a key is released on the keyboard while the tool is active.
void	mouseMoved(MouseEvent mouseEvent) Called when the mouse is moved while the tool is active.
void	mousePressed(MouseEvent mouseEvent) Called when a mouse button is pressed while the tool is active.
void	mouseReleased(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 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:

IOException - if there are interop problems.

AutomationException - if the component throws an ArcObjects exception.

activate

public abstract void activate()
                       throws 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:

IOException - if there are interop problems.

AutomationException - if the component throws an ArcObjects exception.

deactivate

public boolean deactivate()
                   throws 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:

IOException - if there are interop problems.

AutomationException - if the component throws an ArcObjects exception.

init

public void init(IApplication app)
          throws 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:

IOException - if there are interop problems.

AutomationException - if the component throws an ArcObjects exception.

isChecked

public boolean isChecked()
                  throws 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:

IOException

AutomationException

isEnabled

public boolean isEnabled()
                  throws 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:

IOException

AutomationException

keyPressed

public void keyPressed(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(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(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(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(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 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:

IOException - if there are interop problems.

AutomationException - if the component throws an ArcObjects exception.

refresh

public void refresh()
             throws 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:

IOException

AutomationException