Catalog

Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, ArcWeb, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst, Animation, Maplex, Geoprocessing, NetworkAnalyst, Schematic, SpatialAnalyst, 3DAnalyst, GlobeCore, Publisher, TrackingAnalyst, Framework, GeoDatabaseUI, DisplayUI, OutputUI

Additional library information: Contents, Object Model Diagram

The Catalog library contains objects and defines interfaces to support data catalogs. The catalog is a representation of persistent data. The data can be both local and remote. Using the objects within Catalog, you can browse data holdings and, if required, obtain connections to the data. Many of the objects defined in catalog are referred to as GxObjects, as they inherit from the GxObject abstract class. All GxObjects implement the interface IGxObject. Objects that implement this interface can be manipulated within a catalog. GxFilters allow you to browse for certain types of data and are also defined in this library.
 
Developers commonly extend this library to add catalog support for a data type not already supported by the ArcGIS system.

The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:

GxCatalog

The GxCatalog object represents your actual tree of data, as shown in the tree view (the top-level object in the tree view). From the GxCatalog object, you can navigate to any of its descendants in order to access and manipulate them. The GxCatalog object is a type of GxObject and a type of GxObjectContainer because it is an item in the tree view and it contains additional GxObjects.
 
The GxCatalog object is also an event source that monitors the adding, deleting, and changing of the GxObjects within the catalog through the IGxCatalogEvents interface.
The GxCatalog object implements the IGxCatalog interface. It lets you connect and disconnect folder objects. It also maintains the file filter associated with ArcCatalog.
GetObjectFromFullName returns a variant because it is possible to get more than one GxObject back from this method. For example, if you use this method on a CAD file, it returns two objects: one for the CAD file and one for the CAD dataset.
 
The SelectedObject method returns the first selected object in the tabbed view of ArcCatalog.
 
The following code uses the Location property to change the selected folder in the tree view to "d:\tools":


GxObjects
GxObject is perhaps the most important abstract class in the Catalog library. Every item that shows up in the catalog is a GxObject of one sort or another. There are several dozen types of GxObjects. Different types of GxObjects are used for different types of data. For example, the GxLayer object represents layer files, whereas the GxMap object encapsulates map documents.
 
GxObject is extensible, meaning, you can implement your own GxObjects so that they display in ArcCatalog. If you want to create your own custom GxObject, you need to first implement IGxObjectFactory, which actually returns GxObjects. Then, you need to implement the IGxObject and IGxObjectUI interfaces to show the GxObject within ArcCatalog using your custom icons. You can implement various methods under the IGxObject interface to provide specific operations on this object. For example, implementing the Category property displays the object's category in the Type column of ArcCatalog's Details view. The IGxObjectUI interface allows you to specify a bitmap for your custom GxObject that is viewable in the tree view. It includes methods to use small or large icons according to the type of view being displayed--details, list, or icons.
 
In order to be a GxObject, an object only needs to support IGxObject, although it will usually implement a number of other interfaces as well. It must support IGxObject since ArcCatalog uses this interface to set up and tear down the object, as well as to retrieve certain critical information from it during its lifetime. The IGxObject interface provides read-only access to the descriptors of the object, such as name, parent, and category.
 
Using the IGxObject interface, ArcCatalog calls Attach to initialize the object, passing in references to its parent and the GxCatalog object. The object should hold on to these references, releasing them when ArcCatalog calls the Detach method. This behavior is necessary to guarantee that no circular dependencies develop between the object and its parent or the GxCatalog coclass.
 
ArcCatalog relies on three separate properties to retrieve information about the textual name of the object:
 
The easiest way for an object to assemble and return this path is to call the ConstructFullName utility method on the GxCatalog object, passing in itself as a parameter.
InternalObjectName is used for data-transfer operations. If you want your object to participate in drag-and-drop or copy-and-paste operations, you need to return something for this property. This property represents the actual data object that your GxObject manages. For example, database objects, such as GxDatabase and GxDataset, wrap underlying geodatabase entities, such as workspaces and datasets. It is these underlying objects that InternalObjectName references, not the GxObject itself. Moreover, this property indirectly references these underlying objects via a Name object (sometimes also called a moniker).
 
ArcCatalog calls Refresh on your object whenever it needs to ensure your state is up-to-date. In most cases, this happens as a direct result of the user forcing a refresh of a part of the GxCatalog tree. It is your object’s responsibility to release and recreate its internal state, then propagate the Refresh call on to any children it has.
IsValid is called periodically by ArcCatalog to verify that your object is in a legitimate state.
 
Typically, it does so prior to performing critical operations involving your object, such as data transfer.
 
Here is some code to loop through the selected objects in the tabbed view and print their categories.

During an object’s lifetime, ArcCatalog uses the SmallImage, SmallSelectedImage, LargeImage, and LargeSelectedImage properties of the optional IGxObjectUI interface to determine what images to use when displaying the object in the tree and contents views. Your object should return HBITMAPs for these properties. Since these properties are requested frequently, you should load the images only once and cache them for later retrieval, rather than loading them each time they are requested. If you choose not to implement IGxObjectUI, ArcCatalog can still display and work with your object, but it will use a generic icon in the various views.
 
ContextMenu and NewMenu return globally unique identifiers (GUIDs) that indicate the menus that will display when the user attempts to manipulate the object through the ArcCatalog user interface.
 
An object should implement the IGxObjectEdit interface if its properties can be edited by the user within the context of ArcCatalog. This interface consists of several important properties and methods.
 
Rename assigns a new short name to the object (if you return True for the CanRename property).
 
If you return True for the CanDelete property, Delete physically deletes the object and all its associated underlying data; ArcCatalog handles deleting the GxObject, but it is the object’s responsibility to delete all underlying and associated data that the object represents or wraps.
 
CanCopy indicates if the object is a valid source for a copy operation; a return value of True enables the Copy command or menu item in ArcCatalog. (However, to fully enable an object to participate in data transfer operations, you also need to implement the IGxObject::InternalObjectName property as described in the earlier discussion on data transfer.)
 
The EditProperties method brings up a dialog box appropriate to the object that allows the user to manipulate its internal properties and state. It is entirely up to you to decide what can and cannot be manipulated through this dialog box, but a good rule of thumb is that properties about the object, not the actual data contained by the object, should appear here. For example, if the object is a table, this dialog box might show a list of all the columns present and their data types, and permit the user to edit this information. However, the actual rows of data in the table would not be presented in this dialog box.
 
The IGxPasteTarget interface is implemented by those GxObjects that can have other objects pasted into them. For example, GxDataset implements IGxPasteTarget because it is possible to paste feature classes into an object of this type through the ArcCatalog user interface. The interface provides methods for testing whether or not a set of Name objects can be pasted and methods to actually perform the paste.
Use CanPaste to determine if at least one object in the current set can be pasted before executing the Paste method.
 
IGxObjectInternalName is an optional interface for the different types of GxObjects. This interface provides access to the internal name of the object that implements it through the InternalObjectName interface.

GxObjectContainers
GxObjectContainer is an abstract class. This container class is for GxObjects that contain other GxObjects within them. For example, the GxDatabase object can contain GxDataset objects (among other things), so the GxDatabase object is also a type of GxObjectContainer. If an object can contain other objects as children, it must implement the IGxObjectContainer interface. This interface exposes methods and properties to access and manipulate the children of the object.
 
The HasChildren property indicates if the object presently has any children.
 
Children returns an enumeration of the current set of children.
 
AreChildrenViewable indicates if the children should show up as items in the tree view within ArcCatalog; usually, this makes sense, but in certain cases you might want to prevent this from happening.
 
The two methods, AddChild and DeleteChild, do not have to be implemented; they are only used when a container is up and running in ArcCatalog and the user wishes to either create new items in that container or remove items from it. They aren't required since doing a Refresh on the container (or one of its ancestors) will refresh its set of children as well.
 
The following code demonstrates how to loop through the children of a GxObjectContainer object:

GxObjectContainer objects that are based on remote connections implement the IGxRemoteContainer interface. The GxRemoteDatabaseFolder object is an example of a container object for remote database connections. The interface has no properties or methods, but it does identify the implementing object as a remote container object.

GxObjectFilters
There are over thirty types of GxObjectFilter objects the developer can use in the code. They can also create their own code depending on how they want their users to apply the GxDialog object. Through the use of objects of this type, the developer can determine which types of objects the user can choose for open and save operations when browsing data.
 
All GxObjectFilter objects implement the IGxFileFilter interface. This interface enables the specification of certain file types during open and save operations when using a GxDialog browser object. You would normally only access this interface when implementing it as part of a custom GxObjectFilter.
 
The following code demonstrates how to create a custom filter within a class:


MetadataExport
The MetadataExport objects works in the same way as the Export Metadata button in ArcCatalog. Each MetadataExport coclass corresponds to a different format for the output file.
You can build your own custom metadata exporter by creating a class that implements IMetadataExport and then registering it with the Component Categories Manager utility in the Metadata Exporters category.

Samples

The following example exports metadata for an ArcCatalog object to an XML file that satisfies mp’s requirements.


MetadataImport
The MetadataImport object works in the same way as the Import Metadata button in ArcCatalog, with one exception. The Import Metadata dialog box provides the option to synchronize imported metadata with the dataset after the importing is completed. When importing is initiated programmatically, this option isn't available; setting the appropriate Sync attributes and initiating synchronization must also be accomplished programmatically.
Each MetadataImport coclass corresponds to a different format of metadata in the input file (see the table in the MetadataExport .
 
There are more export than import formats because XML can be readily presented as HTML, but not vice versa. For more information about the FGDC’s metadata parser utility, mp, see http://geology.usgs.gov/tools/metadata/tools/doc/mp.html.
 
You can build your own custom metadata importer by creating a class that implements IMetadataImport and then registering it with the Component Categories Manager utility in the Metadata Importers category.
The following table summarizes the supported metadata export and import formats.

Samples

The following code shows how to import metadata for an ArcCatalog object from a text file that is formatted according to mp’s requirements.