com.esri.arcgis.carto
Interface IMapDocument

All Superinterfaces:

Serializable

All Known Implementing Classes:

MapDocument, MxDocument

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.

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 with 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.