com.esri.arcgis.framework
Class AppRef

java.lang.Object
  extended by com.esri.arcgis.framework.AppRef
All Implemented Interfaces:
IApplication, com.esri.arcgis.interop.RemoteObjRef, Serializable

public class AppRef
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IApplication

A reference to the currently running application.

Remarks

If for some reason you can't easily get a reference to the Application object in your code, you can create a new AppRef object. For example, there are cases where you may implement an object that exists within the application framework but there is no way to traverse the application hierarchy from that object. In order to provide developers access to the application object there is a singleton object that provides a pointer to the running application object.

Note you can only use the AppRef object if your code is running inside one of the ArcGIS application processes.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Singleton:

This type is a singleton.

See Also:
Serialized Form

Constructor Summary
AppRef()
          Constructs a AppRef using ArcGIS Engine.
AppRef(Object obj)
          Construct a AppRef using a reference to such an object returned from ArcGIS Engine or Server.
 
Method Summary
 boolean equals(Object o)
          Compare this object with another
 IExtension findExtensionByCLSID(IUID extensionCLSID)
          Finds an extension by its CLSID.
 IExtension findExtensionByName(String extensionName)
          Finds an extension by its name.
 String getCaption()
          The caption of this application.
static String getClsid()
          getClsid.
 ICommandItem getCurrentTool()
          The currently selected tool.
 IDocument getDocument()
          The document that is currently loaded in the application.
 int getHWnd()
          The handle of the application's window.
 String getName()
          The name of this application.
 IStatusBar getStatusBar()
          The statusbar of this application.
 ITemplates getTemplates()
          The templates collection.
 Object getVBE()
          The Visual Basic Environment.
 int hashCode()
          the hashcode for this object
 boolean isDialogVisible(int dialogID)
          Indicates if the specified dialog is visible in the application.
 boolean isVisible()
          Indicates if the application window is visible.
 void lockCustomization(String password, ICustomizationFilter custFilter)
          Locks the application's user interface against any customizations.
 void newDocument(boolean selectTemplate, String templatePath)
          Creates a new document in this application.
 void openDocument(String path)
          Opens a document in this application.
 void printDocument()
          Displays the Print dialog.
 void printPreview()
          Displays how the document will look like when it is printed.
 void refreshWindow()
          Redraws the application window.
 void saveAsDocument(String saveAsPath, boolean saveAsCopy)
          Saves the document that is currently open in this application to a different file.
 void saveDocument(String saveAsPath)
          Saves the document that is currently open in this application.
 void setCaption(String caption)
          The caption of this application.
 void setCurrentToolByRef(ICommandItem tool)
          The currently selected tool.
 void setVisible(boolean visible)
          Indicates if the application window is visible.
 Object showDialog(int dialogID, Object bShow)
          Displays the specified dialog in the application.
 void shutdown()
          Terminates the application.
 void unlockCustomization(String password)
          Unlocks previous user interface customization lock.
 
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

AppRef

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

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

AppRef

public AppRef(Object obj)
       throws IOException
Construct a AppRef using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to AppRef.

Parameters:
obj - an object returned from ArcGIS Engine or Server
Throws:
IOException - if there are interop problems AppRef theAppRef = (AppRef) obj;
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

getName

public String getName()
               throws IOException,
                      AutomationException
The name of this application.

Remarks

Returns the string ArcMap for the ArcMap application.

Returns the string ArcCatalog for the ArcCatalog application.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
getName in interface IApplication
Returns:
The name
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDocument

public IDocument getDocument()
                      throws IOException,
                             AutomationException
The document that is currently loaded in the application.

Remarks

In ArcMap, the Document is the currently loaded document.
In ArcCatalog, the Document is the Normal template.

Both ArcMap and ArcCatalog applications are composed of several things including a document. The document is an object which controls the representation of data. In ArcMap, the document object is the MxDocument CoClass and in ArcCatalog it is the GxDocument CoClass. Access to these CoClasses is provided through this property.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
getDocument in interface IApplication
Returns:
A reference to a com.esri.arcgis.framework.IDocument
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IDocument, GxDocument, com.esri.arcgis.arcmapUI.MxDocument

getStatusBar

public IStatusBar getStatusBar()
                        throws IOException,
                               AutomationException
The statusbar of this application.

Remarks

The status bar is the horizontal area at the bottom of an ArcGIS application window. It provides information about the selected command. For example, if you select a layer in the table of contents in ArcMap, the status bar will tell you how many features are currently selected. It may also display a progress bar while something is being processed.

The IStatusBar interface allows you to set the properties of the status bar.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
getStatusBar in interface IApplication
Returns:
A reference to a com.esri.arcgis.system.IStatusBar
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IStatusBar

showDialog

public Object showDialog(int dialogID,
                         Object bShow)
                  throws IOException,
                         AutomationException
Displays the specified dialog in the application.

Description

Refer to the esriMxDlgIDs Constants help topic for a listing of the dialog ids in ArcMap.

Refer to the esriGxDlgIDs Constants help topic for a listing of the dialog ids in ArcCatalog.

Remarks

This example shows the TOC in ArcMap if it is not already visible. You would get m_app from the hook in ICommand::OnCreate().

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
showDialog in interface IApplication
Parameters:
dialogID - The dialogID (in)
bShow - A Variant (in, optional, pass null if not required)
Returns:
A Variant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
com.esri.arcgis.arcmapUI.esriMxDlgIDs, com.esri.arcgis.arccatalogui.esriGxDlgIDs

isDialogVisible

public boolean isDialogVisible(int dialogID)
                        throws IOException,
                               AutomationException
Indicates if the specified dialog is visible in the application.

Description

Refer to the esriMxDlgIDs Constants help topic for a listing of the dialog ids in ArcMap.

Refer to the esriGxDlgIDs Constants help topic for a listing of the dialog ids in ArcCatalog.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
isDialogVisible in interface IApplication
Parameters:
dialogID - The dialogID (in)
Returns:
The bVisible
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
com.esri.arcgis.arcmapUI.esriMxDlgIDs, com.esri.arcgis.arccatalogui.esriGxDlgIDs

getCurrentTool

public ICommandItem getCurrentTool()
                            throws IOException,
                                   AutomationException
The currently selected tool.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
getCurrentTool in interface IApplication
Returns:
A reference to a com.esri.arcgis.framework.ICommandItem
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommandItem

setCurrentToolByRef

public void setCurrentToolByRef(ICommandItem tool)
                         throws IOException,
                                AutomationException
The currently selected tool.

Remarks

This VBA macro makes the Identify tool the currently selected tool in ArcMap.

 Public Sub SetCurrentTool()

   Dim pItem As ICommandItem

   ' Use the built-in ArcId module to find unique identifier 

   ' for the Identify tool

   Set pItem = CommandBars.Find(arcid.Query_Identify)

   Set Application.CurrentTool = pItem

 End Sub

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
setCurrentToolByRef in interface IApplication
Parameters:
tool - A reference to a com.esri.arcgis.framework.ICommandItem (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommandItem

getVBE

public Object getVBE()
              throws IOException,
                     AutomationException
The Visual Basic Environment.

Remarks

The VBE is the root object that provides access to all other objects represented in Visual Basic for Applications that is embedded in the application.



Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

newDocument

public void newDocument(boolean selectTemplate,
                        String templatePath)
                 throws IOException,
                        AutomationException
Creates a new document in this application.

Description

selectTemplate Specify True if you want the New document dialog to be opened to allow the user to select a template. [Optional]

templatePath is a string representing the path and filename of the template to base the new document on if selectTemplate is False. [Optional]

Remarks

If selectTemplate is True, the New document dialog is displayed.

If templatePath is not specified, the New document dialog is displayed regardless of the value of selectTemplate.

Note, this method does not work in ArcCatalog.

The following example creates a new document in ArcMap using the Normal template. You would get m_app from the hook in ICommand::OnCreate().

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
newDocument in interface IApplication
Parameters:
selectTemplate - The selectTemplate (in, optional, pass false if not required)
templatePath - The templatePath (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

openDocument

public void openDocument(String path)
                  throws IOException,
                         AutomationException
Opens a document in this application.

Description

Path is a string representing the path and filename of the document to be opened. [Optional]

Remarks

If no Path is specified, the Open dialog is displayed.

Note, this method does not work in ArcCatalog.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
openDocument in interface IApplication
Parameters:
path - The path (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

saveDocument

public void saveDocument(String saveAsPath)
                  throws IOException,
                         AutomationException
Saves the document that is currently open in this application.

Description

saveAsPath is a string representing a path and filename for the document that is being saved. [Optional]

Remarks

If this document is a new document that has not been saved yet and a saveAsPath is not specified, the Save As dialog will be displayed.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
saveDocument in interface IApplication
Parameters:
saveAsPath - The saveAsPath (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

saveAsDocument

public void saveAsDocument(String saveAsPath,
                           boolean saveAsCopy)
                    throws IOException,
                           AutomationException
Saves the document that is currently open in this application to a different file.

Description

saveAsPath is a string representing a new path and filename for the document that is being saved. [Optional]

saveAsCopy specify True if you want to save a copy of the document to a new filename but keep the original document open in the application; otherwise False. [Optional]

Remarks

If no saveAsPath is specified, the Save As dialog will be displayed.

Note, this method does not work in ArcCatalog.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
saveAsDocument in interface IApplication
Parameters:
saveAsPath - The saveAsPath (in, optional, pass null if not required)
saveAsCopy - The saveAsCopy (in, optional, pass false if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

printPreview

public void printPreview()
                  throws IOException,
                         AutomationException
Displays how the document will look like when it is printed.

Remarks

Note, this method does not work in ArcCatalog.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
printPreview in interface IApplication
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

printDocument

public void printDocument()
                   throws IOException,
                          AutomationException
Displays the Print dialog.

Remarks

Note, this method does not work in ArcCatalog.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
printDocument in interface IApplication
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

lockCustomization

public void lockCustomization(String password,
                              ICustomizationFilter custFilter)
                       throws IOException,
                              AutomationException
Locks the application's user interface against any customizations.

Description

password is a string representing a password. The string must be at least five characters long.

custFilter is a customization filter object which implements the ICustomizationFilter interface. [Optional]

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
lockCustomization in interface IApplication
Parameters:
password - The password (in)
custFilter - A reference to a com.esri.arcgis.framework.ICustomizationFilter (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICustomizationFilter

unlockCustomization

public void unlockCustomization(String password)
                         throws IOException,
                                AutomationException
Unlocks previous user interface customization lock.

Description

password is a string representing the password that was used to lock customization. The string must be at least five characters long.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
unlockCustomization in interface IApplication
Parameters:
password - The password (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

refreshWindow

public void refreshWindow()
                   throws IOException,
                          AutomationException
Redraws the application window.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
refreshWindow in interface IApplication
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTemplates

public ITemplates getTemplates()
                        throws IOException,
                               AutomationException
The templates collection.

Remarks

The Templates object is a collection of the templates that are currently loaded in the application. In ArcCatalog, the Normal template, Normal.gxt, is the only template that is ever loaded. In ArcMap, there is either two or three templates loaded. The Normal template, Normal.mxt, is always loaded. Also, the document is considered a template is this case; there is always a document loaded in ArcMap. Optionally, the document can be based on another template referred to as a base template.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
getTemplates in interface IApplication
Returns:
A reference to a com.esri.arcgis.framework.ITemplates
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ITemplates

getHWnd

public int getHWnd()
            throws IOException,
                   AutomationException
The handle of the application's window.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
getHWnd in interface IApplication
Returns:
The hWnd (A COM typedef)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

findExtensionByName

public IExtension findExtensionByName(String extensionName)
                               throws IOException,
                                      AutomationException
Finds an extension by its name.

Description

extensionName specifies the name of an extension as a string.

Remarks

To find the Name of an ESRI extension, refer to the following technical document:

ArcGIS Developer Help > Technical Documents > Names and IDs > Extensions

If an extension is registered as a Just-In-Time extension, FindExtensionByName may return nothing. The safest way to get a reference to any extension is to use FindExtensionByCLSID.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
findExtensionByName in interface IApplication
Parameters:
extensionName - The extensionName (in)
Returns:
A reference to a com.esri.arcgis.system.IExtension
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IExtension

findExtensionByCLSID

public IExtension findExtensionByCLSID(IUID extensionCLSID)
                                throws IOException,
                                       AutomationException
Finds an extension by its CLSID.

Description

ExtensionCLSID specifies the unique identifier (UID) of an extension.

Remarks

COM coclasses are identified by a globally unique identifier (GUID). There are two formats for the GUID for a coclass: a class ID (CLSID) and a ProgID. The ProgID is a text alias for a CLSID. The UID coclass can be used to represent the GUID of an extension object. You can set the IUID.Value property to either the CLSID or the ProgID.

To find the CLSID and ProgID of an ESRI extension, refer to the following technical document:

ArcGIS Developer Help > Technical Documents > Names and IDs > Extensions

For your custom extensions, the ProgID is a string composed of the name of your project used to make the extension and the class name of the extension. For example if you have a Visual Basic project called MyCustomExt and there is a class module for your extension called clsMyExtension in that project, then the ProgID for this command would be "MyCustomExt.clsMyExtension". To find the CLSID for this command, you could search the system registry for this ProgID.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
findExtensionByCLSID in interface IApplication
Parameters:
extensionCLSID - A reference to a com.esri.arcgis.system.IUID (in)
Returns:
A reference to a com.esri.arcgis.system.IExtension
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IExtension, IUID

shutdown

public void shutdown()
              throws IOException,
                     AutomationException
Terminates the application.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
shutdown in interface IApplication
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isVisible

public boolean isVisible()
                  throws IOException,
                         AutomationException
Indicates if the application window is visible.

Remarks

Set the Visible property to True to make the application window visible.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
isVisible in interface IApplication
Returns:
The visible
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setVisible

public void setVisible(boolean visible)
                throws IOException,
                       AutomationException
Indicates if the application window is visible.

Remarks

Set the Visible property to True to make the application window visible.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
setVisible in interface IApplication
Parameters:
visible - The visible (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setCaption

public void setCaption(String caption)
                throws IOException,
                       AutomationException
The caption of this application.

Remarks

The Caption is the string that appears as the title of the application's main window.
This VBA macro sets the title of the main ArcMap or ArcCatalog application window.
 Public Sub SetCaption()

     Application.Caption = "My Custom Application"

 End Sub 

 

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
setCaption in interface IApplication
Parameters:
caption - The caption (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getCaption

public String getCaption()
                  throws IOException,
                         AutomationException
The caption of this application.

Description

The Caption is the string that appears as the title of the application's main window.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Specified by:
getCaption in interface IApplication
Returns:
The caption
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.