com.esri.arcgis.controls
Class GlobeHookHelper

java.lang.Object
  com.esri.arcgis.controls.GlobeHookHelper

All Implemented Interfaces:

IConnectionPointContainer, IGlobeHookHelper, IHookActions, ISupportErrorInfo, java.io.Serializable

public class GlobeHookHelper

extends java.lang.Object

implements IGlobeHookHelper, IConnectionPointContainer, ISupportErrorInfo, IHookActions

Helps commands work with the GlobeControl, ArcGlobe, custom controls and applications.

Product Availability

Available with ArcGIS Engine.

Description

The GlobeHookHelper 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 GlobeHookHelper object can do this. The GlobeHookHelper is used to hold the hook and return the Globe, GlobeDisplay, ISceneViewer and Camera objects regardless of whether the hook is a GlobeControl, ToolbarControl (with a 'buddy' GlobeControl), the ArcGlobe application or a custom control or application implementing IGlobeCommandHook.

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

• Use the GlobeHookHelper when the command is to support a variety of hook objects. If the command is to support one type of hook object only (e.g. a command that only works with IGMxApplication in ArcGlobe) the GlobeHookHelper does not offer anything over a simple interface pointer stored as a member variable in the command implementation.
• The GlobeHookHelper is useful for writing ArcGIS Engine commands as it can handle the GlobeControl or the ToolbarControl passed as a hook. In the case of the ToolbarControl, the HookHelper contains the logic for testing the ToolbarControl's Buddy to retieve Globe, GlobeDisplay, ISceneViewer and Camera objects.
• If the custom command is to work with the ArcGIS Controls on an ArcGIS Engine installation and inside the ArcGlobe desktop application, the GlobeHookHelper can provide generic access to Globe, GlobeDisplay, ISceneViewer and Camera objects. There is a good chance an Engine command that starts from these objects will also work within ArcGlobe, providing that the IToolbarControl interface and other ArcGIS Control specific interfaces have not been used.
• If the custom command requires the use of additional objects and interfaces that are only present in an ArcGlobe Desktop installation, then ArcGlobe must be installed in order for these references to be resolved and for the code to compile. If the command makes use of desktop only objects the command will not work on a machine with only an ArcGIS Engine installation. One possible solution is for the command logic to test whether the hook object is a type of ArcGIS Control, and if so provide an alternative implemetation for an ArcGIS Engine only installation.

See Also:

Serialized Form

Constructor Summary

GlobeHookHelper()
Constructs a GlobeHookHelper using ArcGIS Engine.

GlobeHookHelper(java.lang.Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

Method Summary

void	addIHookHelperEventsListener(IHookHelperEvents theListener)
void	doAction(java.lang.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(java.lang.Object pUnknown, java.lang.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) Supported Platforms
boolean	equals(java.lang.Object o) Compare this object with another
void	findConnectionPoint(GUID riid, IConnectionPoint[] ppCP) Supported Platforms
ISceneViewer	getActiveViewer() Active scene viewer of hooked control or application.
IConnectionPointContainer	getAsIConnectionPointContainer() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
IGlobeHookHelper	getAsIGlobeHookHelper() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
IHookActions	getAsIHookActions() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
ISupportErrorInfo	getAsISupportErrorInfo() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
ICamera	getCamera() Camera of hooked control or application.
static java.lang.String	getClsid()
IGlobe	getGlobe() Globe of hooked control or application.
IGlobeDisplay	getGlobeDisplay() GlobeDisplay of hooked control or application.
java.lang.Object	getHook() Hook object that should be the same as the hook object passed in ICommand::OnCreate.
int	hashCode() the hashcode for this object
void	interfaceSupportsErrorInfo(GUID riid) Supported Platforms
boolean	isActionSupported(java.lang.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)
void	setHookByRef(java.lang.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

Constructor Detail

GlobeHookHelper

public GlobeHookHelper()
                throws java.io.IOException,
                       java.net.UnknownHostException

Constructs a GlobeHookHelper using ArcGIS Engine.

Throws:

java.io.IOException - if there are interop problems

java.net.UnknownHostException - if there are interop problems

GlobeHookHelper

public GlobeHookHelper(java.lang.Object obj)
                throws java.io.IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

Construct a GlobeHookHelper using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to GlobeHookHelper.
GlobeHookHelper theGlobeHookHelper = (GlobeHookHelper) obj;

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

java.io.IOException - if there are interop problems

Method Detail

getClsid

public static java.lang.String getClsid()

getAsIGlobeHookHelper

public IGlobeHookHelper getAsIGlobeHookHelper()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsIConnectionPointContainer

public IConnectionPointContainer getAsIConnectionPointContainer()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsISupportErrorInfo

public ISupportErrorInfo getAsISupportErrorInfo()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsIHookActions

public IHookActions getAsIHookActions()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

equals

public boolean equals(java.lang.Object o)

Compare this object with another

hashCode

public int hashCode()

the hashcode for this object

addIHookHelperEventsListener

public void addIHookHelperEventsListener(IHookHelperEvents theListener)
                                  throws java.io.IOException

Throws:

java.io.IOException

removeIHookHelperEventsListener

public void removeIHookHelperEventsListener(IHookHelperEvents theListener)
                                     throws java.io.IOException

Throws:

java.io.IOException

setHookByRef

public void setHookByRef(java.lang.Object ppHook)
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: IGlobeHookHelper

Hook object that should be the same as the hook object passed in ICommand::OnCreate.

Specified by:

setHookByRef in interface IGlobeHookHelper

Parameters:

ppHook - A reference to another Automation Object (IDispatch) (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getHook

public java.lang.Object getHook()
                         throws java.io.IOException,
                                AutomationException

Description copied from interface: IGlobeHookHelper

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 GlobeControl or ArcGlobe.

Specified by:

getHook in interface IGlobeHookHelper

Returns:

A reference to another Automation Object (IDispatch)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGlobe

public IGlobe getGlobe()
                throws java.io.IOException,
                       AutomationException

Description copied from interface: IGlobeHookHelper

Globe of hooked control or application.

Description

The IGlobe object of the hook passed to the ICommand::OnCreate event. The Globe is returned regardless of whether the hook is a GlobeControl, ToolbarControl (with a 'buddy' GlobeControl) or ArcGlobe.

Remarks

This property can return Nothing if the GlobeControl has not been initialized to share a GlobeDisplay with another GlobeControl.

Specified by:

getGlobe in interface IGlobeHookHelper

Returns:

A reference to a com.esri.arcgis.globecore.IGlobe

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGlobeDisplay

public IGlobeDisplay getGlobeDisplay()
                              throws java.io.IOException,
                                     AutomationException

Description copied from interface: IGlobeHookHelper

GlobeDisplay of hooked control or application.

Description

The IGlobeDisplay object of the hook passed to the ICommand::OnCreate event. The GlobeDisplay is returned regardless of whether the hook is a GlobeControl, ToolbarControl (with a 'buddy' GlobeControl) or ArcGlobe.

Remarks

This property can return Nothing if the GlobeControl has not been initialized to share a GlobeDisplay with another GlobeControl.

Specified by:

getGlobeDisplay in interface IGlobeHookHelper

Returns:

A reference to a com.esri.arcgis.globecore.IGlobeDisplay

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getActiveViewer

public ISceneViewer getActiveViewer()
                             throws java.io.IOException,
                                    AutomationException

Description copied from interface: IGlobeHookHelper

Active scene viewer of hooked control or application.

Description

The ISceneViewer interface of the IGlobeViewer object of the hook passed to the ICommand::OnCreate event. The SceneViewer is returned regardless of whether the hook is a GlobeControl, ToolbarControl (with a 'buddy' GlobeControl) or ArcGlobe.

Specified by:

getActiveViewer in interface IGlobeHookHelper

Returns:

A reference to a com.esri.arcgis.analyst3d.ISceneViewer

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getCamera

public ICamera getCamera()
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: IGlobeHookHelper

Camera of hooked control or application.

Description

The ICamera object of the hook passed to the ICommand::OnCreate event. The Camera is returned regardless of whether the hook is a GlobeControl, ToolbarControl (with a 'buddy' GlobeControl) or ArcGlobe.

Specified by:

getCamera in interface IGlobeHookHelper

Returns:

A reference to a com.esri.arcgis.analyst3d.ICamera

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

enumConnectionPoints

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

Description copied from interface: IConnectionPointContainer

Supported Platforms

Windows, Solaris, Linux

Description

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

Specified by:

enumConnectionPoints in interface IConnectionPointContainer

Parameters:

ppEnum - A reference to a com.esri.arcgis.display.IEnumConnectionPoints (out: use single element array)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

findConnectionPoint

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

Description copied from interface: IConnectionPointContainer

Supported Platforms

Windows, Solaris, Linux

Description

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

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:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws java.io.IOException,
                                       AutomationException

Description copied from interface: ISupportErrorInfo

Supported Platforms

Windows, Solaris, Linux

Description

Indicates whether the interface supports IErrorInfo.

Specified by:

interfaceSupportsErrorInfo in interface ISupportErrorInfo

Parameters:

riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

isActionSupported

public boolean isActionSupported(java.lang.Object pUnknown,
                                 int action)
                          throws java.io.IOException,
                                 AutomationException

Description copied from interface: IHookActions

Indicates whether the specified action can be performed on the object.

Description

Indicates whether the specified Action is supported on the specified object. Use ActionSupported before using the DoAction and DoActionWithName methods.

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

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:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

isActionSupportedOnMultiple

public boolean isActionSupportedOnMultiple(IArray pArray,
                                           int action)
                                    throws java.io.IOException,
                                           AutomationException

Description copied from interface: IHookActions

Indicates whether the specified action can be performed on the array of objects.

Description

Indicates whether the specified Action is supported on the objects in the specified array. Use ActionSupportedOnMultiple before using the DoActionOnMultiple and DoActionWithNameOnMultiple methods.

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

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:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

doAction

public void doAction(java.lang.Object pUnknown,
                     int action)
              throws java.io.IOException,
                     AutomationException

Description copied from interface: IHookActions

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.

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:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

doActionWithName

public void doActionWithName(java.lang.Object pUnknown,
                             java.lang.String name,
                             int action)
                      throws java.io.IOException,
                             AutomationException

Description copied from interface: IHookActions

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.

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:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

doActionOnMultiple

public void doActionOnMultiple(IArray pArray,
                               int action)
                        throws java.io.IOException,
                               AutomationException

Description copied from interface: IHookActions

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.

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:

java.io.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 java.io.IOException,
                                       AutomationException

Description copied from interface: IHookActions

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.

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:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.