com.esri.arcgis.carto
Class MapDocument

java.lang.Object
  extended by 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.