com.esri.arcgis.controls
Class HookHelper

java.lang.Object
  extended by com.esri.arcgis.controls.HookHelper
All Implemented Interfaces:
IHookActions, IHookHelper, IConnectionPointContainer, com.esri.arcgis.interop.RemoteObjRef, ISupportErrorInfo, Serializable

public class HookHelper
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IHookHelper, IConnectionPointContainer, ISupportErrorInfo, IHookActions

Helps commands work with the MapControl, PageLayoutControl, ArcMap, custom controls and applications.

Description

The HookHelper is designed to help developers write custom commands that will work with some ArcGIS Engine Controls and applications.

When creating a custom command the ICommand::OnCreate event is passed a hook to the control or application that the command will work with. The command needs to determine the type of hook that is passed so it knows how to handle itself. Rather than adding code into the ICommand::OnCreate event to determine the type of hook a HookHelper object can do this. The HookHelper is used to hold the hook and return the IActiveView, PageLayout or FocusMap regardless of whether the hook is a MapControl, PageLayoutControl, ToolbarControl (with a 'buddy' MapControl or PageLayoutControl), the ArcMap application or a custom control or application implementing ICommandHook.

When using the HookHelper in the ICommand::OnCreate event of custom commands the following must be considered:

Product Availability

Available with ArcGIS Engine.

See Also:
Serialized Form

Constructor Summary
HookHelper()
          Constructs a HookHelper using ArcGIS Engine.
HookHelper(Object obj)
          Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
HookHelper theHookHelper = (HookHelper) obj;
 
Method Summary
 void addIHookHelperEventsListener(IHookHelperEvents theListener)
          addIHookHelperEventsListener.
 void doAction(Object pUnknown, int action)
          Perform the action on the object.
 void doActionOnMultiple(IArray pArray, int action)
          Perform the action on the array of objects.
 void doActionWithName(Object pUnknown, String name, int action)
          Perform the action on the object using the name.
 void doActionWithNameOnMultiple(IArray pArray, IStringArray pNamesArray, int action)
          Perform the action on the array of objects using the array of names.
 void enumConnectionPoints(IEnumConnectionPoints[] ppEnum)
          enumConnectionPoints
 boolean equals(Object o)
          Compare this object with another
 void findConnectionPoint(GUID riid, IConnectionPoint[] ppCP)
          findConnectionPoint
 IActiveView getActiveView()
          Active view of hooked control or application.
static String getClsid()
          getClsid.
 IMap getFocusMap()
          Focus map of hooked control or application.
 Object getHook()
          Hook object that should be the same as the hook object passed in ICommand::OnCreate.
 IOperationStack getOperationStack()
          Operation stack of hooked control or application used for undo/redo operations.
 IPageLayout getPageLayout()
          Page layout of hooked control or application.
 int hashCode()
          the hashcode for this object
 void interfaceSupportsErrorInfo(GUID riid)
          interfaceSupportsErrorInfo
 boolean isActionSupported(Object pUnknown, int action)
          Indicates whether the specified action can be performed on the object.
 boolean isActionSupportedOnMultiple(IArray pArray, int action)
          Indicates whether the specified action can be performed on the array of objects.
 void removeIHookHelperEventsListener(IHookHelperEvents theListener)
          removeIHookHelperEventsListener.
 void setHookByRef(Object ppHook)
          Hook object that should be the same as the hook object passed in ICommand::OnCreate.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef
getJintegraDispatch, release
 

Constructor Detail

HookHelper

public HookHelper()
           throws IOException,
                  UnknownHostException
Constructs a HookHelper using ArcGIS Engine.

Throws:
IOException - if there are interop problems
UnknownHostException - if there are interop problems

HookHelper

public HookHelper(Object obj)
           throws IOException
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
HookHelper theHookHelper = (HookHelper) obj;

Construct a HookHelper using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to HookHelper.

Parameters:
obj - an object returned from ArcGIS Engine or Server
Throws:
IOException - if there are interop problems
Method Detail

getClsid

public static String getClsid()
getClsid.


equals

public boolean equals(Object o)
Compare this object with another

Overrides:
equals in class Object

hashCode

public int hashCode()
the hashcode for this object

Overrides:
hashCode in class Object

addIHookHelperEventsListener

public void addIHookHelperEventsListener(IHookHelperEvents theListener)
                                  throws IOException
addIHookHelperEventsListener. Listen to events generated by this class.

Parameters:
theListener - An object that implements the com.esri.arcgis.controls.IHookHelperEvents interface.
Throws:
IOException - If there are communications problems.

removeIHookHelperEventsListener

public void removeIHookHelperEventsListener(IHookHelperEvents theListener)
                                     throws IOException
removeIHookHelperEventsListener. Stop listening to events generated by this class.

Parameters:
theListener - An object that implements the com.esri.arcgis.controls.IHookHelperEvents interface.
Throws:
IOException - If there are communications problems.

setHookByRef

public void setHookByRef(Object ppHook)
                  throws IOException,
                         AutomationException
Hook object that should be the same as the hook object passed in ICommand::OnCreate.

Product Availability

Available with ArcGIS Engine.

Specified by:
setHookByRef in interface IHookHelper
Parameters:
ppHook - A reference to another Automation Object (IDispatch) (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getHook

public Object getHook()
               throws IOException,
                      AutomationException
Hook object that should be the same as the hook object passed in ICommand::OnCreate.

Description

The hook that is passed to the ICommand::OnCreate event. The hook is a MapControl, PageLayoutControl, ToolbarControl or ArcMap.

Product Availability

Available with ArcGIS Engine.

Specified by:
getHook in interface IHookHelper
Returns:
A reference to another Automation Object (IDispatch)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getActiveView

public IActiveView getActiveView()
                          throws IOException,
                                 AutomationException
Active view of hooked control or application.

Description

The IActiveView of the hook passed to the ICommand::OnCreate event. The ActiveView is returned regardless of whether the hook is a MapControl, PageLayoutControl, ToolbarControl (with a 'buddy' MapControl or PageLayoutControl) or ArcMap.

Product Availability

Available with ArcGIS Engine.

Specified by:
getActiveView in interface IHookHelper
Returns:
A reference to a com.esri.arcgis.carto.IActiveView
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPageLayout

public IPageLayout getPageLayout()
                          throws IOException,
                                 AutomationException
Page layout of hooked control or application.

Description

The PageLayout of the hook passed to the ICommand::OnCreate event. The Pagelayout is returned regardless of whether the hook is a PageLayoutControl, ToolbarControl (with a 'buddy' PageLayoutControl) or ArcMap.

If the hook is a MapControl the property will return nothing as PageLayout objects are not supported.

Product Availability

Available with ArcGIS Engine.

Specified by:
getPageLayout in interface IHookHelper
Returns:
A reference to a com.esri.arcgis.carto.IPageLayout
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFocusMap

public IMap getFocusMap()
                 throws IOException,
                        AutomationException
Focus map of hooked control or application.

Description

The focus map's Map object of the hook passed to the ICommand::OnCreate event. The FocusMap is returned regardless of whether the hook is a MapControl, PageLayoutControl, ToolbarControl (with a 'buddy' MapControl or PageLayoutControl) or ArcMap.

Product Availability

Available with ArcGIS Engine.

Specified by:
getFocusMap in interface IHookHelper
Returns:
A reference to a com.esri.arcgis.carto.IMap
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getOperationStack

public IOperationStack getOperationStack()
                                  throws IOException,
                                         AutomationException
Operation stack of hooked control or application used for undo/redo operations.

Description

The IOperationStack of the hook passed to the ICommand::OnCreate event. The OperationStack is returned regardless of whether the hook is a ToolbarControl or ArcMap.

The property will return Nothing if the hook is a MapControl or PageLayoutControl that do not have an associated operation stack. If the hook is a ToolbarControl Nothing will be returned if the OperationStack has not been set into the ToolbarControl. A developer normally sets one ControlsOperationStack object into each IToolbarControl::OperationStack used in an application.

If the IToolbarControl::Buddy, IMapControl2::Map or IPageLayoutControl::PageLayout changes a new ControlsOperationStack object will need passing to the IToolbarControl::OperationStack. Use the following events to do this: IToolbarControlEvents::OnBuddyChanged, IMapControlEvents2::OnMapReplaced, IPageLayoutControlEvents::OnPageLayoutReplaced and IPageLayoutControlEvents::OnFocusMapChanged.

Product Availability

Available with ArcGIS Engine.

Specified by:
getOperationStack in interface IHookHelper
Returns:
A reference to a com.esri.arcgis.systemUI.IOperationStack
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

enumConnectionPoints

public void enumConnectionPoints(IEnumConnectionPoints[] ppEnum)
                          throws IOException,
                                 AutomationException
enumConnectionPoints

Description

IConnectionPointContainer is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
enumConnectionPoints in interface IConnectionPointContainer
Parameters:
ppEnum - A reference to a com.esri.arcgis.display.IEnumConnectionPoints (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

findConnectionPoint

public void findConnectionPoint(GUID riid,
                                IConnectionPoint[] ppCP)
                         throws IOException,
                                AutomationException
findConnectionPoint

Description

IConnectionPointContainer is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
findConnectionPoint in interface IConnectionPointContainer
Parameters:
riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)
ppCP - A reference to a com.esri.arcgis.display.IConnectionPoint (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws IOException,
                                       AutomationException
interfaceSupportsErrorInfo

Description

Indicates whether the interface supports IErrorInfo.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
interfaceSupportsErrorInfo in interface ISupportErrorInfo
Parameters:
riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isActionSupported

public boolean isActionSupported(Object pUnknown,
                                 int action)
                          throws IOException,
                                 AutomationException
Indicates whether the specified action can be performed on the object.

Product Availability

Available with ArcGIS Engine.

Specified by:
isActionSupported in interface IHookActions
Parameters:
pUnknown - A reference to another Object (IUnknown) (in)
action - A com.esri.arcgis.controls.esriHookActions constant (in)
Returns:
The pIsEnable
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isActionSupportedOnMultiple

public boolean isActionSupportedOnMultiple(IArray pArray,
                                           int action)
                                    throws IOException,
                                           AutomationException
Indicates whether the specified action can be performed on the array of objects.

Product Availability

Available with ArcGIS Engine.

Specified by:
isActionSupportedOnMultiple in interface IHookActions
Parameters:
pArray - A reference to a com.esri.arcgis.system.IArray (in)
action - A com.esri.arcgis.controls.esriHookActions constant (in)
Returns:
The pIsEnable
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

doAction

public void doAction(Object pUnknown,
                     int action)
              throws IOException,
                     AutomationException
Perform the action on the object.

Description

DoAction performs the specified Action on the specified object in the ActiveView. For example, pass esriHookActionsZoom to zoom to the extent of the specified object. Use the ActionSupported method before DoAction is ensure the specified Action is supported.

pUnknown must be an object implementing IEnvelope, IPoint, IPolygon or IPolyline and the geometry should not be empty.

Remarks

When passing DoAction an object implementing IPoint and esriHookActionsZoom, if the width of the specified geometry is zero, the display will be zoomed to 1/20th of the width of the full extent of the data. If the height of the current visible extent is less than 1/20th of the height of the full extent of the data, the current visible extent is used instead.

Product Availability

Available with ArcGIS Engine.

Specified by:
doAction in interface IHookActions
Parameters:
pUnknown - A reference to another Object (IUnknown) (in)
action - A com.esri.arcgis.controls.esriHookActions constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

doActionWithName

public void doActionWithName(Object pUnknown,
                             String name,
                             int action)
                      throws IOException,
                             AutomationException
Perform the action on the object using the name.

Description

DoActionWithName performs the specified Action on the specified object with the specified name string in the ActiveView. For example, pass esriHookActionsLabel to label the specified object with the specfied label. Use the ActionSupported method before DoActionWithName is ensure the specified Action is supported.

pUnknown must be an object implementing IEnvelope, IPoint, IPolygon or IPolyline and the geometry should not be empty.

Name is the string used by esriHookActionsLabel and esriHookActionsCallout actions.

Remarks

When passing DoActionWithName an object implementing IPoint and esriHookActionsZoom, if the width of the specified geometry is zero, the display will be zoomed to 1/20th of the width of the full extent of the data. If the height of the current visible extent is less than 1/20th of the height of the full extent of the data, the current visible extent is used instead.

Product Availability

Available with ArcGIS Engine.

Specified by:
doActionWithName in interface IHookActions
Parameters:
pUnknown - A reference to another Object (IUnknown) (in)
name - The name (in)
action - A com.esri.arcgis.controls.esriHookActions constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

doActionOnMultiple

public void doActionOnMultiple(IArray pArray,
                               int action)
                        throws IOException,
                               AutomationException
Perform the action on the array of objects.

Description

DoActionOnMultiple performs the specified Action on the objects in the specified array in the ActiveView. For example, pass esriHookActionsZoom to zoom to the extent of the specified objects. Use the ActionSupportedOnMultiple method before DoActionOnMultiple is ensure the specified Action is supported.

pArray must contain objects implementing IEnvelope, IPoint, IPolygon or IPolyline and the geometry of each object should not be empty.

Product Availability

Available with ArcGIS Engine.

Specified by:
doActionOnMultiple in interface IHookActions
Parameters:
pArray - A reference to a com.esri.arcgis.system.IArray (in)
action - A com.esri.arcgis.controls.esriHookActions constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

doActionWithNameOnMultiple

public void doActionWithNameOnMultiple(IArray pArray,
                                       IStringArray pNamesArray,
                                       int action)
                                throws IOException,
                                       AutomationException
Perform the action on the array of objects using the array of names.

Description

DoActionWithNameOnMultiple performs the specified Action on the objects in the specified array in the ActiveView. For example, pass esriHookActionsLabel to label the specified objects with the specfied labels. Use the ActionSupportedOnMultiple method before DoActionWithNameOnMultiple is ensure the specified Action is supported.

pArray must contain objects implementing IEnvelope, IPoint, IPolygon or IPolyline and the geometry of each object should not be empty.

pNamesArray is an array of strings used by esriHookActionsLabel and esriHookActionsCallout actions.

Ensure pArray and pNamesArray contain the same number of elements.

Product Availability

Available with ArcGIS Engine.

Specified by:
doActionWithNameOnMultiple in interface IHookActions
Parameters:
pArray - A reference to a com.esri.arcgis.system.IArray (in)
pNamesArray - A reference to a com.esri.arcgis.system.IStringArray (in)
action - A com.esri.arcgis.controls.esriHookActions constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.