com.esri.arcgis.carto
Interface IMapDocument

All Superinterfaces:
Serializable
All Known Implementing Classes:
MapDocument

public interface IMapDocument
extends Serializable

Provides access to members that control the reading and writing of map document files.

Description

The IMapDocument interface provides properties and methods for reading map document files (*.mxd, *mxt, *.pmf) and writing and saving changes to map document files (*.mxd). However, since it is not tied to the ArcMap application, application-specific functionality in the MapDocument will not be persisted. Examples of application specific functionality are toolbar settings, UI customizations, VBA projects, and ArcMap graphs. For desktop developers who need to use this functionality, the MxDocument interface located in the ArcMapUI library is a better choice.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux


Method Summary
 void close()
          Close the map document.
 void esri_new(String sDocument)
          Creates and opens a new map document in preparation for the contents to be retrieve or updated.
 IActiveView getActiveView()
          The ActiveView of the map document.
 String getDocumentFilename()
          The map document filename that the MapDocument coclass is linked to.
 int getDocumentType()
          The type of map document currently loaded in the object.
 int getDocumentVersion()
          Indicates if the version of the map document is compatible with the current version of software.
 ILayer getLayer(int mapIndex, int layerIndex)
          The Layer object at the specified index for the specified map.
 IMap getMap(int mapIndex)
          The Map object at the specified index.
 int getMapCount()
          The number of Map objects contained within the map document.
 IPageLayout getPageLayout()
          The PageLayout object.
 IPrinter getPrinter()
          The printer object.
 IPicture getThumbnail()
          The thumbnail stored in the map document.
 void getVersionInfo(boolean[] versionInfoMissing, int[] lMajor, int[] lMinor, int[] lRevision, int[] lBuild)
          Retrieve the detailed version information of the map document.
 boolean isMapDocument(String sDocument)
          Indicates if the map document is a valid map document.
 boolean isPasswordProtected(String sDocument)
          Indicates if the map document is protected by a passsword.
 boolean isPresent(String sDocument)
          Indicates if the map document is present.
 boolean isReadOnly(String sDocument)
          Indicates if the map document is read only.
 boolean isRestricted(String sDocument)
          Indicates if the use of the map document is restricted to certain applications.
 boolean isUsesRelativePaths()
          Indicates if the data in the map document is referenced using relative paths.
 void open(String sDocument, String bsPassword)
          Open the map document in preparation for the contents to be retrieve or updated.
 void replaceContents(IMxdContents pObject)
          Replace the contents of the map document.
 void save(boolean bUseRelativePaths, boolean bCreateThumnbail)
          Save the contents of the map document to the bound file.
 void saveAs(String sDocument, boolean bUseRelativePaths, boolean bCreateThumnbail)
          Save the contents of the map document to the specified file name.
 void setActiveView(IActiveView pActiveView)
          Set the ActiveView content of the map document.
 

Method Detail

isMapDocument

boolean isMapDocument(String sDocument)
                      throws IOException,
                             AutomationException
Indicates if the map document is a valid map document.

Product Availability

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

Parameters:
sDocument - The sDocument (in)
Returns:
The isMapDocument
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isPresent

boolean isPresent(String sDocument)
                  throws IOException,
                         AutomationException
Indicates if the map document is present.

Product Availability

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

Parameters:
sDocument - The sDocument (in)
Returns:
The isPresent
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isReadOnly

boolean isReadOnly(String sDocument)
                   throws IOException,
                          AutomationException
Indicates if the map document is read only.

Product Availability

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

Parameters:
sDocument - The sDocument (in)
Returns:
The isReadOnly
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isRestricted

boolean isRestricted(String sDocument)
                     throws IOException,
                            AutomationException
Indicates if the use of the map document is restricted to certain applications.

Product Availability

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

Parameters:
sDocument - The sDocument (in)
Returns:
The isRestricted
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isPasswordProtected

boolean isPasswordProtected(String sDocument)
                            throws IOException,
                                   AutomationException
Indicates if the map document is protected by a passsword.

Product Availability

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

Parameters:
sDocument - The sDocument (in)
Returns:
The isPasswordProtected
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

esri_new

void esri_new(String sDocument)
              throws IOException,
                     AutomationException
Creates and opens a new map document in preparation for the contents to be retrieve or updated.

Product Availability

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

Parameters:
sDocument - The sDocument (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

open

void open(String sDocument,
          String bsPassword)
          throws IOException,
                 AutomationException
Open the map document in preparation for the contents to be retrieve or updated.

Description

Opens the specified MapDocument in preparation for reading it. The MapDocument can be an an ArcMap document (*.mxd), ArcMap template (*.mxt), Published Map File (*.pmf) or Layer File (*.lyr). The MapDocument will be cached so no other users will be able to access the MapDocument until it has been closed.

Before using the Open methods check whether the specified document IsPresent, IsRestricted, IsMapDocument and IsPasswordProtected. If the MapDocument is password protected, specify the password in the Open method.

If a Layer File (*.lyr) is opened a portriat PageLayout containing one Map with the layer added to it is created.

Remarks

When opening or creating a map document with the IMapDocument Open() or New() methods, you should always make subsequent calls to IActiveView::Activate() in order to properly initialize the display of the PageLayout and Map objects. Call Activate() once for the PageLayout and once for each Map you will be working with. If your application has a user interface, you should call Activate() with the hWnd of the application's client area. If your application runs in the background and has no windows, you can always get a valid hWnd from the GDI GetDesktopWindow() function, part of the Win32 API.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
sDocument - The sDocument (in)
bsPassword - The bsPassword (in, optional, pass if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDocumentFilename

String getDocumentFilename()
                           throws IOException,
                                  AutomationException
The map document filename that the MapDocument coclass is linked to.

Description

Returns the DocumentFilename of the last map document that was successfully opened with the Open method. An empty string will be returned if no document has been opened.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The sDocument
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDocumentType

int getDocumentType()
                    throws IOException,
                           AutomationException
The type of map document currently loaded in the object.

Description

Returns the type of MapDocument that is open.

Remarks

If a map template (*.mxt) is open esriMapDocumentTypeMxd will be returned.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.carto.esriMapDocumentType constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isUsesRelativePaths

boolean isUsesRelativePaths()
                            throws IOException,
                                   AutomationException
Indicates if the data in the map document is referenced using relative paths.

Description

Determines whether the MapDocument that is open stores paths to data sources as relative path names (relative to the MapDocument) or absolute path names.

Remarks

If a Published Map File (*.pmf) is Open that was published with ArcGIS 8.x or a Layer File (*.lyr) is Open the UsesRelativePaths will always return false.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The bUsesRelativePaths
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDocumentVersion

int getDocumentVersion()
                       throws IOException,
                              AutomationException
Indicates if the version of the map document is compatible with the current version of software.

Description

Returns whether the version of the MapDocument that is open is compatible with the current software accessing the document.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.carto.esriMapDocumentVersionInfo constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPageLayout

IPageLayout getPageLayout()
                          throws IOException,
                                 AutomationException
The PageLayout object.

Description

Returns the PageLayout of the MapDocument that is open.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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.

getActiveView

IActiveView getActiveView()
                          throws IOException,
                                 AutomationException
The ActiveView of the map document.

Description

Returns the ActiveView of the MapDocument that is open. This can can be a PageLayout or a Map. If a map document (*.mxd) is Open the ActiveView will be the map or page layout that was the ActiveView when the document was last saved. If a Published Map File (*.pmf) is Open the ActivewView will be the default view specified at the time the document was published. If a layer file (*.lyr) is Open the ActiveView will be a map.

Remarks

When working with the IActiveView interface on a MapDocument object, you should always first call IActiveView::Activate() in order to properly initialize the display of the PageLayout or Map object. If your application has a user interface, you should call Activate() with the hWnd of the application's client area. If your application runs in the background and has no windows, you can always get a valid hWnd from the GDI GetDesktopWindow() function, part of the Win32 API.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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.

getMapCount

int getMapCount()
                throws IOException,
                       AutomationException
The number of Map objects contained within the map document.

Description

Returns the number of map's within the PageLayout.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The mapCount
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMap

IMap getMap(int mapIndex)
            throws IOException,
                   AutomationException
The Map object at the specified index.

Product Availability

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

Parameters:
mapIndex - The mapIndex (in)
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.

getLayer

ILayer getLayer(int mapIndex,
                int layerIndex)
                throws IOException,
                       AutomationException
The Layer object at the specified index for the specified map.

Product Availability

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

Parameters:
mapIndex - The mapIndex (in)
layerIndex - The layerIndex (in)
Returns:
A reference to a com.esri.arcgis.carto.ILayer
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPrinter

IPrinter getPrinter()
                    throws IOException,
                           AutomationException
The printer object. If no printer object is stored in the map document this returns NULL.

Description

The Printer stored in the MapDocument. If a map document (*.mxd) or map template (*.mxt) is Open the Printer returned will be the printer stored in the document when it was last saved. If no printer is saved in the document the Printer will be nothing. If a Published Map File (*.pmf) or layer file (*.lyr) is Open the Printer will be nothing. Creating a New MapDocument will set the Printer to nothing.

Remarks

If the Printer cannot be found on the system, a message box will display indicating that the printer is not installed. The MessageLogger can be used to switch this message off.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.output.IPrinter
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getThumbnail

IPicture getThumbnail()
                      throws IOException,
                             AutomationException
The thumbnail stored in the map document. If this is empty E_FAIL is returned.

Description

Returns the Thumbnail stored in the MapDocument that is open. Not every MapDocument has a thumbnail. The Thumnail is a small bitmap picture representation of the contents of the MapDocument.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.support.ms.stdole.IPicture
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

close

void close()
           throws IOException,
                  AutomationException
Close the map document.

Description

Closes the MapDocument. This sets the DocumentFilename property to an empty string and resets the ActiveView, PageLayout, Map, MapCount, Printer and Thumbnail properties.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getVersionInfo

void getVersionInfo(boolean[] versionInfoMissing,
                    int[] lMajor,
                    int[] lMinor,
                    int[] lRevision,
                    int[] lBuild)
                    throws IOException,
                           AutomationException
Retrieve the detailed version information of the map document.

Description

Returns the major, minor, revision and build numbers of the MapDocument if the map document version information is present.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
versionInfoMissing - The versionInfoMissing (in/out: use single element array)
lMajor - The lMajor (in/out: use single element array)
lMinor - The lMinor (in/out: use single element array)
lRevision - The lRevision (in/out: use single element array)
lBuild - The lBuild (in/out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

replaceContents

void replaceContents(IMxdContents pObject)
                     throws IOException,
                            AutomationException
Replace the contents of the map document.

Description

Replaces the contents of the MapDocument with the contents of the specified Map, PageLayout, MapControl or PageLayoutControl. Before using the ReplaceContents method a New MapDocument must be created or an existing MapDocument must be Open.

If a MapControl is passed to the ReplaceContents method the MapDocument will be replaced with the IMapControl2::Map. Likewise, if a PageLayoutControl is passed to the ReplaceContents method the MapDocument will be replaced with the IPageLayoutControl::PageLayout.

If the MapDocument contents is replaced with the contents of a Map or MapControl a portriat PageLayout containing the map will be created.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
pObject - A reference to a com.esri.arcgis.carto.IMxdContents (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setActiveView

void setActiveView(IActiveView pActiveView)
                   throws IOException,
                          AutomationException
Set the ActiveView content of the map document.

Description

Use this method to set the ActiveView of the MapDocument. Use the PageLayout and Map properties to specify the ActiveView.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
pActiveView - A reference to a com.esri.arcgis.carto.IActiveView (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

save

void save(boolean bUseRelativePaths,
          boolean bCreateThumnbail)
          throws IOException,
                 AutomationException
Save the contents of the map document to the bound file.

Description

Saves the MapDocument that is Open and any changes that have been made to it. Before using the Save method check whether the document IsReadOnly. If a MapDocument is read only use the SaveAs method to create a new MapDocument. By default MapDocuments are saved without relative paths and thumbnails.

Specifying thumbnails as True can delay saving complex map documents as the view of the document is generated for the thumbnail. However, thumbnails are guides for users browsing map documents using ArcCatalog and Windows Explorer.

Remarks

If a Published Map File (*.pmf) or Layer File (*.lyr) is Open use the SaveAs method to create a new Map Document (*.mxd), as attempting to use the Save method will return an error.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
bUseRelativePaths - The bUseRelativePaths (in, optional, pass true if not required)
bCreateThumnbail - The bCreateThumnbail (in, optional, pass true if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

saveAs

void saveAs(String sDocument,
            boolean bUseRelativePaths,
            boolean bCreateThumnbail)
            throws IOException,
                   AutomationException
Save the contents of the map document to the specified file name.

Description

Saves the MapDocument that is Open and any changes that have been made to it to a new MapDocument with the specified filename. The filename that is supplied must be valid and inlcude the *.mxd extension. By default MapDocuments are saved without relative paths and thumbnails.

Specifying thumbnails as True can delay saving complex map documents as the view of the document is generated for the thumbnail. However, thumbnails are guides for users browsing map documents using ArcCatalog and Windows Explorer.

Remarks

The SaveAs method cannot be used to save the MapDocument as an earlier ArcGIS 8.3 map document.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
sDocument - The sDocument (in)
bUseRelativePaths - The bUseRelativePaths (in, optional, pass true if not required)
bCreateThumnbail - The bCreateThumnbail (in, optional, pass true if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.