com.esri.arcgis.controls
Interface IGlobeControl

All Superinterfaces:

Serializable

All Known Implementing Classes:

GlobeBean, GlobeControl, IGlobeControlProxy

public interface IGlobeControl
extends Serializable

Provides access to members that control the GlobeControl.

Description

The IGlobeControl interface is a starting point for any tasks related to the GlobeControl, such as setting general appearance, adding globe documents, managing the globe, globe display and globe camera, and setting the current tool.

Product Availability

Available with ArcGIS Engine.

Method Summary

void	aboutBox() Displays a dialog of information about the GlobeControl.
boolean	check3dFile(String fileName) Checks if a filename is a Globe document.
boolean	esri_isEnabled() Indicates whether the GlobeControl can respond to user generated events.
void	esri_setEnabled(boolean pbool) Indicates whether the GlobeControl can respond to user generated events.
int	getAppearance() The appearance of the GlobeControl.
int	getBackColor() Background color of the GlobeControl.
int	getBorderStyle() The border style of the GlobeControl.
ITool	getCurrentTool() Current active tool for the GlobeControl.
Object	getCustomProperty() A property to associate data with a control.
String	getDocumentFilename() The filename of the last globe document loaded into the control.
IGlobe	getGlobe() The Globe object associated with the GlobeControl.
IGlobeCamera	getGlobeCamera() The GlobeCamera object associated with the GlobeControl.
IGlobeDisplay	getGlobeDisplay() The GlobeDisplay object associated with the GlobeControl.
IGlobeViewer	getGlobeViewer() The GlobeViewer associated with the GlobeControl.
int	getHWnd() Handle to the window associated with the GlobeControl.
int	getKeyIntercept() A property that specifies interception of key strokes that are normally handled by the container.
Picture	getMouseIcon() Custom mouse icon used if MousePointer is 99.
int	getMousePointer() The mouse pointer displayed over the GlobeControl.
Object	getObject() A property that returns the underlying control.
int	getShowGlobeTips() Indicates the type of globe tips that are shown.
int	getTipDelay() The delay before globe tips are shown.
int	getTipStyle() The style of globe tips.
boolean	isNavigate() Indicates if the GlobeControl performs default scene navigation in response to mouse events.
boolean	isOverrideBackColor() Indicates whether to override the background color of the globe document.
void	load3dFile(String fileName) Loads a Globe document into the GlobeControl.
void	setAppearance(int pappearance) The appearance of the GlobeControl.
void	setBackColor(int pclr) Background color of the GlobeControl.
void	setBorderStyle(int pstyle) The border style of the GlobeControl.
void	setCurrentToolByRef(ITool pVal) Current active tool for the GlobeControl.
void	setCustomProperty(Object pVal) A property to associate data with a control.
void	setDocumentFilename(String documentFilename) The filename of the last globe document loaded into the control.
void	setGlobeCameraByRef(IGlobeCamera pVal) The GlobeCamera object associated with the GlobeControl.
void	setGlobeDisplayByRef(IGlobeDisplay pVal) The GlobeDisplay object associated with the GlobeControl.
void	setKeyIntercept(int pVal) A property that specifies interception of key strokes that are normally handled by the container.
void	setMouseIconByRef(Picture ppMouseIcon) Custom mouse icon used if MousePointer is 99.
void	setMousePointer(int ppointer) The mouse pointer displayed over the GlobeControl.
void	setNavigate(boolean pVal) Indicates if the GlobeControl performs default scene navigation in response to mouse events.
void	setOverrideBackColor(boolean pVal) Indicates whether to override the background color of the globe document.
void	setShowGlobeTips(int type) Indicates the type of globe tips that are shown.
void	setTipDelay(int delay) The delay before globe tips are shown.
void	setTipStyle(int style) The style of globe tips.

Method Detail

setBackColor

void setBackColor(int pclr)
                  throws IOException,
                         AutomationException

Background color of the GlobeControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

pclr - The pclr (A COM typedef) (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getBackColor

int getBackColor()
                 throws IOException,
                        AutomationException

Background color of the GlobeControl.

Description

Returns or sets the Background Color of the GlobeControl. Internally the OLE_Color is stored as a long integer where the value may be calculated for any RGB combination as follows:

OLE_Color = (Red) + (Green * 256) + (Blue * 256 * 256)

Where Red, Green and Blue are Long Integers within the range 0 - 255.

To ensure the BackColor property overrides any background color set in a globe document, set the OverrideBackColor to true.

Product Availability

Available with ArcGIS Engine.

Returns:

The pclr (A COM typedef)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setBorderStyle

void setBorderStyle(int pstyle)
                    throws IOException,
                           AutomationException

The border style of the GlobeControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

pstyle - A com.esri.arcgis.controls.esriControlsBorderStyle constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getBorderStyle

int getBorderStyle()
                   throws IOException,
                          AutomationException

The border style of the GlobeControl.

Description

Returns or sets the border style of a GlobeControl. By default a border is drawn.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriControlsBorderStyle constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

esri_setEnabled

void esri_setEnabled(boolean pbool)
                     throws IOException,
                            AutomationException

Indicates whether the GlobeControl can respond to user generated events.

Product Availability

Available with ArcGIS Engine.

Parameters:

pbool - The pbool (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

esri_isEnabled

boolean esri_isEnabled()
                       throws IOException,
                              AutomationException

Indicates whether the GlobeControl can respond to user generated events.

Product Availability

Available with ArcGIS Engine.

Returns:

The pbool

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setAppearance

void setAppearance(int pappearance)
                   throws IOException,
                          AutomationException

The appearance of the GlobeControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

pappearance - A com.esri.arcgis.controls.esriControlsAppearance constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getAppearance

int getAppearance()
                  throws IOException,
                         AutomationException

The appearance of the GlobeControl.

Description

Returns or sets the paint style of a GlobeControl to either Flat or 3D. By default the appearance is flat.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriControlsAppearance constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMousePointer

void setMousePointer(int ppointer)
                     throws IOException,
                            AutomationException

The mouse pointer displayed over the GlobeControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

ppointer - A com.esri.arcgis.controls.esriControlsMousePointer constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMousePointer

int getMousePointer()
                    throws IOException,
                           AutomationException

The mouse pointer displayed over the GlobeControl.

Description

Use this property when you want to indicate changes in functionality as the mouse pointer passes over the GlobeControl. The esriPointerArrowHourglass setting (11) is useful for indicating that the user should wait for a process or operation to finish.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriControlsMousePointer constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMouseIconByRef

void setMouseIconByRef(Picture ppMouseIcon)
                       throws IOException,
                              AutomationException

Custom mouse icon used if MousePointer is 99.

Product Availability

Available with ArcGIS Engine.

Parameters:

ppMouseIcon - A reference to a com.esri.arcgis.support.ms.stdole.Picture (A com.esri.arcgis.support.ms.stdole.Picture COM typedef) (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMouseIcon

Picture getMouseIcon()
                     throws IOException,
                            AutomationException

Custom mouse icon used if MousePointer is 99.

Description

The MouseIcon property provides a custom icon that is used when the MousePointer property is set to esriPointerArrowHourglass (99).

Remarks

In most development evironments the control's property pages can be used to load either a cursor (.cur) or icon (.ico) file. A cursor contains a custom 'hotspot' location and can be any size. The 'hotspot' location for an icon file defaults to the center of the icon. This property cannot be used to load animated cursor (.ani) files.

To programatically create an object implementing IPictureDisp there is the win32 function OleLoadPicture or helper methods depending on the development environment.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to a com.esri.arcgis.support.ms.stdole.Picture (A com.esri.arcgis.support.ms.stdole.Picture COM typedef)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHWnd

int getHWnd()
            throws IOException,
                   AutomationException

Handle to the window associated with the GlobeControl.

Description

The operating environment identifies each window, form and control in an application by assigning it a handle, or hWnd. Many ArcObjects methods and Windows API calls require the hWnd as an argument.

Product Availability

Available with ArcGIS Engine.

Returns:

The hWnd

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

aboutBox

void aboutBox()
              throws IOException,
                     AutomationException

Displays a dialog of information about the GlobeControl.

Description

The AboutBox method causes a modal dialog box to display on top of the GlobeControl, containing information about the version and creation date of the GlobeControl as well as listing relevant legal and copyright information from ESRI.

Product Availability

Available with ArcGIS Engine.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

load3dFile

void load3dFile(String fileName)
                throws IOException,
                       AutomationException

Loads a Globe document into the GlobeControl.

Description

Loads a globe document (*.3dd) into the GlobeControl. Use the Check3dFile method to determine if the specified globe document is a valid globe document.

Product Availability

Available with ArcGIS Engine.

Parameters:

fileName - The fileName (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGlobe

IGlobe getGlobe()
                throws IOException,
                       AutomationException

The Globe object associated with the GlobeControl.

Description

This is a shortcut to the IGlobeDisplay::Globe property.

Product Availability

Available with ArcGIS Engine.

Returns:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGlobeDisplay

IGlobeDisplay getGlobeDisplay()
                              throws IOException,
                                     AutomationException

The GlobeDisplay object associated with the GlobeControl.

Description

This is a shortcut to the IGlobeViewer::GlobeDisplay property.

Product Availability

Available with ArcGIS Engine.

Returns:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setGlobeDisplayByRef

void setGlobeDisplayByRef(IGlobeDisplay pVal)
                          throws IOException,
                                 AutomationException

The GlobeDisplay object associated with the GlobeControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - A reference to a com.esri.arcgis.globecore.IGlobeDisplay (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGlobeViewer

IGlobeViewer getGlobeViewer()
                            throws IOException,
                                   AutomationException

The GlobeViewer associated with the GlobeControl.

Description

This is the GlobeViewer contained within the GlobeControl.

Product Availability

Available with ArcGIS Engine.

Returns:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGlobeCamera

IGlobeCamera getGlobeCamera()
                            throws IOException,
                                   AutomationException

The GlobeCamera object associated with the GlobeControl.

Description

This is a shortcut to the ISceneViewer::Camera property.

Product Availability

Available with ArcGIS Engine.

Returns:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setGlobeCameraByRef

void setGlobeCameraByRef(IGlobeCamera pVal)
                         throws IOException,
                                AutomationException

The GlobeCamera object associated with the GlobeControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - A reference to a com.esri.arcgis.globecore.IGlobeCamera (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCurrentTool

ITool getCurrentTool()
                     throws IOException,
                            AutomationException

Current active tool for the GlobeControl. Set to nothing to clear the tool.

Description

The CurrentTool is the tool used to interact will the GlobeControl's display. Always check if a tool is enabled before setting it to the CurrentTool property, otherwise a user will be able to use a tool that is actually disabled.

Remarks

When the CurrentTool is set the following events occur:

1. The ITool::Deactivate event is triggered on the 'old' CurrentTool if one was set. If this event returns false a trappable error ocurrs. If this event returns true the 'old' CurrentTool is removed and replaced.
2. The ICommand::OnClick event is triggered on the 'new' CurrentTool and its cursor is picked up.

Within an ITool implementation it is recommended that the ITool::Deactivate event returns true. This allows a 'new' CurrentTool to be set, and allows the release of the CurrentTool when an application is shutting down.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to a com.esri.arcgis.systemUI.ITool

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setCurrentToolByRef

void setCurrentToolByRef(ITool pVal)
                         throws IOException,
                                AutomationException

Current active tool for the GlobeControl. Set to nothing to clear the tool.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - A reference to a com.esri.arcgis.systemUI.ITool (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isNavigate

boolean isNavigate()
                   throws IOException,
                          AutomationException

Indicates if the GlobeControl performs default scene navigation in response to mouse events.

Description

The Navigate property determines whether the default GlobeControl navigation functionality is enabled at run time. By default the Navigate property is set to false. When the Navigate property is set to true, the end user can use the left mouse button to navigate backwards and forwards and to the left and right of the display, and the right mouse button to zoom in and out on the display.

Remarks

When the Navigate property is set to true, the OnMouseDown, OnMouseMove, OnMouseUp events are being intercepted. As such, care must be taken by developers to avoid the display becoming confused when:

• The OnMouseDown, OnMouseMove, OnMouseUp events contain code that interacts with the GlobeCamera.
• The GlobeControl is being used in conjunction with the ToolbarControl with Control Commands or custom commands hosted on it. When a command hosted on the ToolbarControl is selected by the end user to become the CurrentTool, both the Navigate functionality and the CurrentTool are catching the OnMouseDown, OnMouseMove, OnMouseUp events.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setNavigate

void setNavigate(boolean pVal)
                 throws IOException,
                        AutomationException

Indicates if the GlobeControl performs default scene navigation in response to mouse events.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - The pVal (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

check3dFile

boolean check3dFile(String fileName)
                    throws IOException,
                           AutomationException

Checks if a filename is a Globe document.

Description

Determines whether the specified Globe Document (*.3dd) is a valid globe document and can be loaded into the GlobeControl. The method verifies the file exists and verifies the file internals conform to an expected storage format. The method does not read and validate the entire contents of the file; use the Load3dFile to do this.

Product Availability

Available with ArcGIS Engine.

Parameters:

fileName - The fileName (in)

Returns:

The result

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCustomProperty

Object getCustomProperty()
                         throws IOException,
                                AutomationException

A property to associate data with a control.

Description

Use the CustomProperty to associate any useful data with the GlobeControl. This is similar to a 'Tag' property, and can be use to store strings, numbers and objects.

Product Availability

Available with ArcGIS Engine.

Returns:

A Variant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setCustomProperty

void setCustomProperty(Object pVal)
                       throws IOException,
                              AutomationException

A property to associate data with a control.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - A Variant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setDocumentFilename

void setDocumentFilename(String documentFilename)
                         throws IOException,
                                AutomationException

The filename of the last globe document loaded into the control.

Product Availability

Available with ArcGIS Engine.

Parameters:

documentFilename - The documentFilename (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDocumentFilename

String getDocumentFilename()
                           throws IOException,
                                  AutomationException

The filename of the last globe document loaded into the control.

Description

Returns the DocumentFilename of the last document loaded into the GlobeControl with the Load3dFile method. An empty string will be returned if no document is loaded.

Product Availability

Available with ArcGIS Engine.

Returns:

The documentFilename

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getObject

Object getObject()
                 throws IOException,
                        AutomationException

A property that returns the underlying control. This can be used when the control is inside a wrapper object that has been added by a development environment.

Description

In some development environments it is not possible to query interface directly on the control to other COM interfaces, beacuse the control is contained within a wrapper object. To get the real control use the Object property.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to another Automation Object (IDispatch)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setOverrideBackColor

void setOverrideBackColor(boolean pVal)
                          throws IOException,
                                 AutomationException

Indicates whether to override the background color of the globe document.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - The pVal (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isOverrideBackColor

boolean isOverrideBackColor()
                            throws IOException,
                                   AutomationException

Indicates whether to override the background color of the globe document.

Description

The OverrideBackColor property determines whether the background color of any document loaded into the GlobeControl is overriden and replaced with the GlobeControl's BackColor. By default this property is false.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setShowGlobeTips

void setShowGlobeTips(int type)
                      throws IOException,
                             AutomationException

Indicates the type of globe tips that are shown.

Product Availability

Available with ArcGIS Engine.

Parameters:

type - A com.esri.arcgis.globecore.esriGlobeTipsType constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getShowGlobeTips

int getShowGlobeTips()
                     throws IOException,
                            AutomationException

Indicates the type of globe tips that are shown.

Description

The type of globe tips that are displayed as the mouse moves over the globe. The globe tip can display decimal degree coordinates or elevation or a combination of both. By default the ShowGlobeTips property is set to esriGlobeTipsNone.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.globecore.esriGlobeTipsType constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setTipStyle

void setTipStyle(int style)
                 throws IOException,
                        AutomationException

The style of globe tips.

Product Availability

Available with ArcGIS Engine.

Parameters:

style - A com.esri.arcgis.systemUI.esriTipStyle constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getTipStyle

int getTipStyle()
                throws IOException,
                       AutomationException

The style of globe tips.

Description

Returns or sets the TipStyle used by the globe tips. By default the TipStyle is solid.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.systemUI.esriTipStyle constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setTipDelay

void setTipDelay(int delay)
                 throws IOException,
                        AutomationException

The delay before globe tips are shown.

Product Availability

Available with ArcGIS Engine.

Parameters:

delay - The delay (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getTipDelay

int getTipDelay()
                throws IOException,
                       AutomationException

The delay before globe tips are shown.

Description

Returns or sets the time delay in milliseconds before globe tips are displayed. By default TipDelay is 500 milliseconds.

Product Availability

Available with ArcGIS Engine.

Returns:

The delay

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getKeyIntercept

int getKeyIntercept()
                    throws IOException,
                           AutomationException

A property that specifies interception of key strokes that are normally handled by the container. When intercepted the OnKeyDown and OnKeyUp events will be called. This value can be a combined bit mask of esriKeyIntercept enum values.

Description

Returns or sets keys on the keyboard that will be intercepted by the GlobeControl, triggering the OnKeyDown and OnKeyUp events when pressed. These keys are often hidden from the GlobeControl by the development environment container. By default the KeyIntercept is set to esriKeyInterceptNone.

Many development environment containers use the up, down, left and right arrow keys to change control focus on a form. These keys can also be useful for navigating around the display. To intercept the arrow keys and the Tab key combine the enum values using a logical OR operation (esriKeyInterceptArrowKeys OR esriKeyInterceptTabKey, which is 1 OR 4 = 5).

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setKeyIntercept

void setKeyIntercept(int pVal)
                     throws IOException,
                            AutomationException

A property that specifies interception of key strokes that are normally handled by the container. When intercepted the OnKeyDown and OnKeyUp events will be called. This value can be a combined bit mask of esriKeyIntercept enum values.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - The pVal (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.