com.esri.arcgis.carto
Class MapDocument

java.lang.Object
  com.esri.arcgis.carto.MapDocument

All Implemented Interfaces:

IMapDocument, com.esri.arcgis.interop.RemoteObjRef, IDocumentVersion, Serializable

public class MapDocument
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IMapDocument, IDocumentVersion

The MapDocument coclass is used to read and write map document files.

Description

The MapDocument CoClass encapsulates map document files (*.mxd, *mxt, *.pmf) and layer files (*.lyr) and provides properties and methods for: accessing and updating the contents of a document; determining document properties; and reading, writing and saving map documents files (*.mxd).

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

See Also:

Serialized Form

Constructor Summary

MapDocument()
Constructs a MapDocument using ArcGIS Engine.

MapDocument(Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
MapDocument theMapDocument = (MapDocument) obj;

Method Summary

void	close() Close the map document.
boolean	equals(Object o) Compare this object with another
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.
static String	getClsid() getClsid.
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.
int	hashCode() the hashcode for this object
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.
void	setDocumentVersion(int docVersion) The version of the document to save.

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

MapDocument

public MapDocument()
            throws IOException,
                   UnknownHostException

Constructs a MapDocument using ArcGIS Engine.

Throws:

IOException - if there are interop problems

UnknownHostException - if there are interop problems

MapDocument

public MapDocument(Object obj)
            throws IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
MapDocument theMapDocument = (MapDocument) obj;

Construct a MapDocument using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to MapDocument.

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

IOException - if there are interop problems

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

isMapDocument

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

Specified by:

isMapDocument in interface IMapDocument

Parameters:

sDocument - The sDocument (in)

Returns:

The isMapDocument

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isPresent

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

Specified by:

isPresent in interface IMapDocument

Parameters:

sDocument - The sDocument (in)

Returns:

The isPresent

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isReadOnly

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

Specified by:

isReadOnly in interface IMapDocument

Parameters:

sDocument - The sDocument (in)

Returns:

The isReadOnly

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isRestricted

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

Specified by:

isRestricted in interface IMapDocument

Parameters:

sDocument - The sDocument (in)

Returns:

The isRestricted

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isPasswordProtected

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

Specified by:

isPasswordProtected in interface IMapDocument

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

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

Specified by:

esri_new in interface IMapDocument

Parameters:

sDocument - The sDocument (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

open

public 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

Specified by:

open in interface IMapDocument

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

public 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

Specified by:

getDocumentFilename in interface IMapDocument

Returns:

The sDocument

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDocumentType

public 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

Specified by:

getDocumentType in interface IMapDocument

Returns:

A com.esri.arcgis.carto.esriMapDocumentType constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isUsesRelativePaths

public 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

Specified by:

isUsesRelativePaths in interface IMapDocument

Returns:

The bUsesRelativePaths

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDocumentVersion

public 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

Specified by:

getDocumentVersion in interface IMapDocument

Specified by:

getDocumentVersion in interface IDocumentVersion

Returns:

A com.esri.arcgis.carto.esriMapDocumentVersionInfo constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getPageLayout

public 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

Specified by:

getPageLayout in interface IMapDocument

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

public 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

Specified by:

getActiveView in interface IMapDocument

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

public 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

Specified by:

getMapCount in interface IMapDocument

Returns:

The mapCount

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMap

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

Specified by:

getMap in interface IMapDocument

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

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

Specified by:

getLayer in interface IMapDocument

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

public 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

Specified by:

getPrinter in interface IMapDocument

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

public 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

Specified by:

getThumbnail in interface IMapDocument

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

public 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

Specified by:

close in interface IMapDocument

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getVersionInfo

public 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

Specified by:

getVersionInfo in interface IMapDocument

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

public 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

Specified by:

replaceContents in interface IMapDocument

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

public 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

Specified by:

setActiveView in interface IMapDocument

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

public 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

Specified by:

save in interface IMapDocument

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

public 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

Specified by:

saveAs in interface IMapDocument

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.

setDocumentVersion

public void setDocumentVersion(int docVersion)
                        throws IOException,
                               AutomationException

The version of the document to save.

Product Availability

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

Specified by:

setDocumentVersion in interface IDocumentVersion

Parameters:

docVersion - A com.esri.arcgis.system.esriArcGISVersion constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.