Supported with: ArcGIS Desktop

Library dependencies: System, SystemUI, Geometry, Display, Server, Output, GeoDatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, GeoDatabaseDistributed, Carto, NetworkAnalyst, Schematic, Location, NetworkAnalysis, Controls, GeoAnalyst, 3DAnalyst, GlobeCore, SpatialAnalyst, Framework, GeoDatabaseUI, DisplayUI, OutputUI, Catalog

The CatalogUI library provides user interfaces (UIs), including property pages, to support objects contained in the Catalog library. In addition to the property pages there are a number of dialogs, including the GxDialog that can be used when interacting with catalogs and their contents. The GxDialog object supports the "Add Data" functionality of the ArcGIS Desktop applications. The FindDialog is also implemented by this library. In fact, many of the commands and context menus seen in the ArcCatalog application are defined in this library.

Developers extend this library when they create UIs for corresponding components they created in the Catalog library.

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

• GxViews
• GxDialog
• MetadataEditors
• SearchEngines

GxViews

ArcCatalog offers a simple framework for hosting GxViews. GxViews represent different user interfaces to the various GxObjects. Different GxViews are used for different tasks. The tree view is always available (even though it can be shown and hidden by the user as desired). It is the primary navigation tool within ArcCatalog and is used to establish the current selection location. The selection location governs what is shown by the other GxViews such as GxContentsView or GxGeographicView.

GxView abstract class

There are two types of views: tabbed views and previews. They are implemented exactly the same but are registered in separate component categories depending on the look and feel desired.

Tabbed views show up as individual tabs in the ArcCatalog main window. They are always available regardless of the type of the current selection.

Previews are different; they are only available on the Preview tab and only display if appropriate for the type of the current selection. The Applies property determines this. If the view does apply, it shows up as a possible choice in the preview dropdown combo box. If it doesn't apply, its option is unavailable. Applies has no effect when the view is registered as a tabbed view.

At appropriate times, ArcCatalog calls Activate and Deactivate on the GxView to inform it that it is becoming active or inactive. In response, the view typically refreshes itself and establishes or releases references to any resources needed for interaction with the user.

A GxView must minimally support the IGxView interface, which ArcCatalog uses to negotiate with the view. It asks the view for an hWnd to display through the hWnd property. It reparents this hWnd so that it is a child of an ArcCatalog hWnd. It also guarantees events are passed to the hWnd correctly and that it is resized when the ArcCatalog window is resized. If you wish to create your own custom views, you must implement this interface.

Use the Activate property to hold on to the GxApplication and GxCatalog objects that are passed in as parameters. The Deactivate property releases these references.

DefaultToolbarCLSID provides a reference to the default toolbar for the particular view. The default toolbar for a view contains tools that are appropriate for the current type of GxView.

If the SupportsTools property returns True, ArcCatalog will intercept mouse events normally destined for the view and instead send them to the active tool.

Dim pApp As IGxApplication, pGxView As IGxView
Set pApp = Application
Set pGxView = pApp.View
If UCase(pGxView.Name) = "PREVIEW" Then
  'The above line could be replaced with "If TypeOf pGxView Is IGxPreview Then"
  Dim pPrev As IGxPreview, pUID As New UID
  Set pPrev = pGxView
  Debug.Print pPrev.ViewClassID
  pUID = "{9C34344D-99DC-11D2-AF6A-080009EC734B}"
  pPrev.ViewClassID = pUID
End If

GxViews optionally support the IGxViewPrint interface to allow the user to print the current display. This is especially handy for the metadata view as it allows users to create scripts that print well-formatted metadata for a batch of objects at once.

GxContentsView and GxContentsView Column

The GxContentsView coclass shows the children of the current selection location in a variety of styles: large icons, list, report, and thumbnails. You can set the style it uses by changing the DisplayStyle property on IGxContentsView.

Sub test1()
Dim pApp As IGxApplication, pView As IGxView
Dim pContView As IGxContentsViewColumns, pCol As IGxContentsViewColumn
Set pApp = Application
Set pView = pApp.View
  If TypeOf pView Is IGxContentsViewColumns Then
    Set pContView = pView
    Set pCol = pContView.ColumnByIndex(0)
    Debug.Print pCol.Caption & ", " & pCol.PropertyName
  End If
End Sub

The IGxContentsView interface is implemented by the GxContentsView object. It provides the ability to change how users interact with a view of that type. What types of files are displayed, how they are displayed, and whether more than one can be selected at a time are all controlled through this interface.

Constrain the set of objects displayed by supplying an object filter through the ObjectFilter property. For a discussion of what filters are available and how to create your own, see the sections on GxDialog and GxObjectFilters.

The IGxContentsViewColumns interface serves as a container for the GxContentsViewColumn objects contained within the GxContentsView object. The objects in the collection represent the columns in the tabbed display area of the view (when Contents is the active tab).

After using the InsertColumn method to add your new column, execute the UpdateColumn method to refresh the column list.

RemoveAllColumns will not remove the Name and Type columns. These columns cannot be removed. Keep in mind that removal of columns is not just for that session, it is permanent.

GxContentsViewColumn objects represent the columns of information displayed when the Contents tab is the active view. The developer has the ability to create and add additional columns of information to customize the contents view for displaying specific information.

The IGxContentsViewColumn interface provides access to the properties of the columns contained within the GxContentsView object. The column properties allow you to set the width, visibility, and caption of the column.

Intrinsic properties (Intrinsic property set to True) are properties such as Name, Category, and Size. These are not really useful unless you add your own GxObject through a new workspace factory; if you do this, you have the ability to add object-specific special properties.

The PropertyName property is based on keywords within the metadata for the object. Make sure you have metadata with the specific keyword before using it as a PropertyName.

GxDocumentationView coclass

The metadata view in ArcCatalog is represented by GxDocumentationView. Since it is a GxView, it naturally supports IGxView. However, to manipulate it, you will want to work with IGxDocumentationView. This interface allows you to do three things: edit the metadata using a custom editor through Edit, edit the metadata properties with a default editor via EditProperties, and force the metadata to be updated with respect to the objects current attributes through Synchronize.

To build a custom editor, create an object that implements IMetadataEditor interface, then inform the metadata extension object to use it through its IMetadataHelper::Editor property.

GxDocumentationView also implements IGxViewPrint to enable you to print the well-formatted metadata.

IGxDocumentationView is implemented by GxDocumentationView. It provides a set of methods for manipulating the metadata associated with an object. Through this interface, the developer can open the editor associated with the metadata, access the metadata properties, or apply the edits made to the metadata.

Dim pApp As IGxApplication, pGxView As IGxView, _
  pDocView As IGxDocumentationView
Set pApp = Application
Set pGxView = pApp.View
If TypeOf pGxView Is IGxDocumentationView Then
  Set pDocView = pGxView
  pDocView.Edit
End If

GxGeographicView coclass

When you want to preview your data, use GxGeographicView. It is available through the Preview tab in ArcCatalog. It displays the geography of the selected dataset in its window. By default, the GxGeographicView object shows up on the Preview tab page; however, the object implements IGxView like the other GxView objects and can be used as its own tab.

A set of standard manipulation tools is provided for zooming, panning, and performing identifications. However, you can easily add your own tools which work with this view in whatever fashion you would like. You can do this by accessing the Map or MapDisplay objects from the IGxGeographicView interface. Internally, the view uses the services of these two objects to display the selected item, and you can manipulate them as well.

Public Sub ZoomIn()
  Dim pApp As IGxApplication
  Set pApp = Application
  If Not TypeOf pApp.View Is IGxPreview Then Exit Sub

  Dim pPreview As IGxPreview
  Set pPreview = pApp.View
  If Not TypeOf pPreview.View Is IGxGeographicView Then Exit Sub

  Dim pGeoView As IGxGeographicView
  Set pGeoView = pPreview.View
  Dim pActiveView As IActiveView
  Set pActiveView = pGeoView.Map

  Dim pExtent As IEnvelope
  Set pExtent = pActiveView.Extent
  pExtent.Expand 0.75, 0.75, True
  pActiveView.Extent = pExtent
  pActiveView.Refresh
End Sub

Newer versions of ArcCatalog also support previewing a map documents page layout within the geographic view. In these cases, you can use the new IGxGeographicView2 interface and access its ActiveView property. It will contain a reference to a page layout object if the selected item refers to a map document (GxMap). You can manipulate this object in any way you desire.

The IGxGeographicView interface is implemented by the GxGeographicView object. It provides access to the map and screen display that preview the currently selected object. Through this interface, you can retrieve the layer being displayed, then use the Map and MapDisplay properties to show additional information within the view.

The DisplayedLayer property is set to Nothing when the selected object cannot be previewed in the GxGeographicView.

Sub GxGeographicViewDisplayLayer()
  Dim pApp As IGxApplication
  Dim pView As IGxView
  Dim pPreview As IGxPreview
  Dim pGeo As IGxGeographicView
  Set pApp = Application
  Set pView = pApp.View
  If TypeOf pView Is IGxPreview Then
    Set pPreview = pView
    If TypeOf pPreview.View Is IGxGeographicView Then
      Set pGeo = pPreview.View
      If pGeo.DisplayedLayer Is Nothing Then
        Debug.Print "nothing is displayed"
      Else
        Debug.Print "something is there"
      End If
    End If
  End If
End Sub

The IGxGeographicView2 interface provides access to the IActiveView of the map being used to preview the current selection.

GxTableView and GxTreeView coclasses

The GxTableView object is similar to the GxGeographicView in that it is used to preview data. By default, it is accessed through the Preview tab. As the name implies, the GxTableView coclass is used to preview the table associated with the selected object. The coclass is a type of GxView, so it implements the IGxView interface, but it does not implement any additional interfaces.

The tree view is represented by GxTreeView; it shows a hierarchical organization of your data holdings as parents and children. It is unlikely you will need to interact programmatically with the tree view other than to force it to reveal a particular GxObject (through the IGxTreeView::EnsureVisible method) or to initiate a renaming operation (through BeginRename).

The IGxTreeView interface is implemented only by the GxTreeView object. It provides the ability to manipulate the object selected in the tree view. Through this interface, you can begin a rename process, ensure the visibility of the object, or expand the node in the tree view.

Dim pApp As IGxApplication, pTreeView As IGxTreeView
Set pApp = Application
Set pTreeView = pApp.TreeView
pTreeView.BeginRename

GxViewContainer abstract class

The GxViewContainer object permits a GxView object to be a container for additional views. The GxPreview coclass is the only type of GxViewContainer object currently implemented in ArcCatalog. Out of the box, the GxPreview object contains the GxGeographicView and GxTableView objects. This functionality is exposed in the user interface through the Geography and Table options on the Preview tab in ArcCatalog.

The IGxViewContainer interface provides access to the views within the container. It is not possible to add additional views to the container through this interface. Additional views must be added by registering a component in the ESRI GxPreviews category.

The Views property returns an enumeration of all the valid views in the container for the currently selected object.

Dim pApp As IGxApplication, pGxView As IGxView
Set pApp = Application
Set pGxView = pApp.View
If TypeOf pGxView Is IGxViewContainer Then
  Dim pViewCont As IGxViewContainer, pUID As New UID, pView As IGxView
  Set pViewCont = pGxView
  pUID = "{9C34344D-99DC-11D2-AF6A-080009EC734B}"
  Set pView = pViewCont.FindView(pUID, False)
  If pView Is Nothing Then
    MsgBox "could not find it"
  End If
End If

GxPreview coclass

The GxPreview coclass is the only type of GxView that is also a type of GxViewContainer. The class is implemented as a tab within ArcCatalog, but within that tab is a container for additional views. These views provide previews of the selected object, depending on which ones are applicable. For example, the geography and table previews are available for a shapefile, while only the table preview is available for a table.

The IGxPreview interface is implemented by the GxPreview object. It provides access to the supported views for the selected object. Use this interface when you want to find out what the supported views are, or to retrieve or set the current view.

The ViewClassID property sets and retrieves the current view through its UID. Setting the UID is the only way to change the current view within the GxPreview object.

Sub UpdateViewClassID()
Dim pApp As IGxApplication, pGxView As IGxView
Set pApp = Application
Set pGxView = pApp.View
If TypeOf pGxView Is IGxPreview Then
  Dim pPrev As IGxPreview, pUID As New UID
  Set pPrev = pGxView
  Debug.Print pPrev.ViewClassID
  pUID = "{9C34344D-99DC-11D2-AF6A-080009EC734B}" 'GUID for GxTableView
  pPrev.ViewClassID = pUID
End If
End Sub

GxDialog

The GxDialog object controls the browser functionality of ArcCatalog. For example, when a user right-clicks a dataset, points to Import, then clicks Coverage to Geodatabase, the GxDialog object is employed in the browser that pops up, allowing the user to select a coverage.

The GxDialog object can be used within ArcCatalog and ArcMap to provide browser capabilities. The Intersect sample tool provides the capability to intersect two layers in the map and create a new geodatabase layer or a shapefile. The GxDialog object is used in that tool to allow the user to browse to a location for the layer or shapefile to create.

What the user can select or specify when using a GxDialog browser is based on the filters (GxObjectFilter) held by the object. The GxDialog object maintains a collection of these filters, and you have the ability to create your own filter to add to the collection.

The IGxDialog interface is implemented by the GxDialog object and provides access to the properties of the dialog box object and methods for displaying the dialog box during open or save operations. Use this interface when you want to access the properties of the dialog box or when you wish to display the dialog box for input from the end user.

ObjectFilter returns the filter that is currently active in the dialog box. If the dialog box is not currently open (through DoModalOpen or DoModalSave), this property will return the default filter.

The GxDialog object implements the IGxObjectFilterCollection interface. It provides access to the set of filters used by the GxDialog object. Even though a collection of filters can be attached to a GxDialog object, only one filter is actually active at a time. The active filter is specified through the dialog box when DoModalOpen or DoModalSave is executed through the IGxDialog interface. Use the IGxObjectFilterCollection interface when you want to remove all of the filters or when you want to add an additional filter to the object.

Dim pGxDialog As IGxDialog
Dim pShpFilter As IGxObjectFilter
Dim pLyrFilter As IGxObjectFilter
Dim pFilterCol As IGxObjectFilterCollection
Dim pEnumGx As IEnumGxObject

Set pShpFilter = New GxFilterShapefiles
Set pLyrFilter = New GxFilterLayers

Set pGxDialog = New GxDialog
Set pFilterCol = pGxDialog

pFilterCol.AddFilter pShpFilter, False
pFilterCol.AddFilter pLyrFilter, True 'pLyrFilter is the default filter.
pGxDialog.Title = "Browse Data"
pGxDialog.DoModalOpen 0, pEnumGx

MetadataEditors

Metadata can be edited in ArcCatalog using a metadata editor. Two metadata editors are supplied with ArcCatalog: FGDCEditor and ISO Wizard. You can build your own custom metadata editor, which can be opened in place of supplied metadata editors when the Edit Metadata button is clicked. You might do this to allow users to create metadata following a different metadata standard or to add specific information used by your organization to the metadata, such as the current state of a data-creation project. To build your own editor, create a class that implements IMetadataEditor and register it with the Component Categories Manager utility in the Metadata Editors category.

SearchEngines

Several search engines allow ArcCatalog to find data. Several search engines are supplied in ArcCatalog. For example, the CatalogSearchEngine lets you search for any object that appears in ArcCatalog, including objects that are stored within geodatabases. It is the default search engine. The FileSystemXmlSearchEngine lets you search for file-based objects stored on disk for which metadata has been created. It is faster than the CatalogSearchEngine. You can build your own custom search engine by creating a class that implements ISearchEngine and registering it with the Component Categories Manager utility in the ESRI GX Search Engines category. You might do this to support custom searching application that communicates with metadata stored within a relational database rather than within XML files on disk.