Extending ArcObjects

TOC Catalog View Example

In this section:

1. TOC catalog view example
2. The case for a custom TOC view
3. Creating the CatalogView
4. Plugging CatalogView into ArcMap

TOC catalog view example

Example Code Click here

Description This project provides a custom contents view for ArcMap, displaying a GxTreeView; datasets from this view can be dragged and dropped from the TOC onto the map.

Design CatalogView class implements IContentsView and contains an instance of GxTreeView. A helper class, GxApplication, implements IGxApplication.

License ArcView or above.

Libraries ArcMapUI, Catalog, CatalogUI, Geometry, and System.

Languages Visual Basic, Visual C++; discussion follows the VB implementation.

Categories ESRI Contents Views.

Interfaces IContentsView, IGxApplication.

How to use

1. If using VB, register TocVB.dll and double-click the TocVB.reg file to register the TOC view class to the required component category.
   If using VC++, first register the TocVB.dll. Then open and build the project TocVC.dsp to register the DLL and also to register the TOC view class to the required component category.
2. Open ArcMap.
3. You should see a tab named Catalog in the TOC. Click this tab.
   You can now browse to a dataset using the TOC, choose a dataset, and drag-and-drop it onto the map to add the data as a new layer.

The case for a custom TOC view

The standard ArcGIS configuration offers two different ways to browse datasets on disk and add them to ArcMap.

You can open ArcCatalog, which allows you to browse data in a tree view. You can then drag-and-drop the selected datasets into ArcMap.

Alternatively, you can open the standard GxDialog in ArcMap by clicking the Add Data button. You can browse data sets in the dialog box one folder at a time and select datasets to add to the map.

However, many users may want to use the convenient browsing of the ArcCatalog tree view but may not find it convenient to open an entirely separate application, for example, if layers are continually being added and removed from the map.

Such a customization is clearly application-level, as users always require access to this functionality. Implementing the solution as a TOC would ensure that screen `real estate' is conserved; a new dockable or overview window would require extra screen space, but the TOC window is always available. The customization would be applicable to any data source, as it is independent of the layers already in a map. Last, the solution would ideally be available from both map and page layout views. Therefore, it seems that a custom TOC view may be an appropriate solution for the requirements.

Creating a table of contents view to add data to the map ensures the functionality is always present while preserving screen real estate.

Creating a tree view

The requirements for this example state that you must provide browse and drag-and-drop access to datasets, similar to that shown in the tree view in ArcCatalog.

By reviewing the ArcCatalog object model and the online reference, you can see that the GxTreeView coclass provides ArcCatalog with its browsable tree view of data. You will make use of this class to create your custom TOC view. Since the objects in the tree view and the map both support drag-and-drop functionality, it will also be possible to drag data directly from the tree view into ArcMap.

For the GxTreeView to function, the Activate method must be called and references to valid GxApplication and GxCatalog objects must be passed to it. When the GxTreeView is activated inside ArcCatalog (via the Activate method), this connects the tree view to its parent application. However, you do not have an instance of ArcCatalog available, and to create one would defeat the purpose of the customization.

The GxTreeView coclass provides the tree view of data used in ArcCatalog.

The GxApplication coclass

To successfully call the IGxView::Activate method on the GxTreeView, you will create a helper class called GxApplication, that implements IGxApplication and contains an instance of a GxCatalog.

Full details of the implementation of the GxApplication helper class can be found in the accompanying source code as its implementation is not directly relevant to the creation of a TOC view. The source code shows how to implement the minimum functionality to allow the GxApplication class to function correctly.

You will create a helper class, GxApplication, to allow the GxTreeView to be activated.

Creating a subtype of TOCView

Looking at the ArcMap object model, you can see that the existing TOC viewsTOCCatalogView, TOCDisplayView, and TOCSelectionVieware all subtypes of the TOCView abstract class.

The primary interface implemented by all TOCView classes is IContentsViewthis interface provides the main TOC view functionality. You can also see that a TOCView does not need to be clonable or persistable.

The existing TOC coclasses also sink the event interfaces IComPropertySheetEvents, IActiveViewEvents and IDocumentEvents.

The TOCView abstract class is the basis for all table of contents views.

Creating the CatalogView

To achieve the requirements described, you will create a class called CatalogView and implement the IContentsView interface. You will register this class to the ESRI Contents Views component category, which will allow the system to create a TOC tab and embed your TOC view onto it at runtime.

As the CatalogView does not need to respond to changes in the active view, in relation to document events or in response to property page changes, you will not implement any of these interfaces. However, the section 'Implementing Different Kinds of TOC Views' later in this chapter gives advice on how you might implement these interfaces, if you adapt this example to create different custom TOC view implementations.

The CatalogView class will create an instance of a GxTreeView. To correctly Activate this GxTreeView instance, you will also create a class called GxApplication to emulate an instance of ArcCatalog, which implements the IGxApplication interface (see earlier section 'The GxApplication Coclass').

You will create a CatalogView class, which will display a GxTreeView in the ArcMap table of contents.

Setting up the view

The majority of the work required in a TOC view can be done in the class initialization code.

1. Declare member variables to hold IGxApplication, IGxCatalog, and IGxView references.
   [Visual Basic 6]

   Private m_pGxApp As IGxApplication
   Private m_pGxCatalog As IGxCatalog
   Private m_pGxView As IGxView

2. When the CatalogView class is initialized, create an instance of the custom GxApplication class and store references to this object and its Catalog and TreeView properties.
   [Visual Basic 6]

   Private Sub Class_Initialize()
     Set m_pGxApp = New TOCView.GxApplication
     Set m_pGxCatalog = m_pGxApp.Catalog
     Set m_pGxView = m_pGxApp.TreeView

3. Activate the tree view ready for use by calling the IGxView::Activate method on the m_pGxView member variable—you will need to use the reference to the custom GxApplication object in order to activate the tree view.
   [Visual Basic 6]

   m_pGxView.Activate m_pGxApp, m_pGxCatalog

4. Store the window handle in another member variable—it will be used later by IContentsView::hWnd.
   [Visual Basic 6]

   m_lHWnd = m_pGxView.hwnd

5. In the class termination function, release the object references.
   [Visual Basic 6]

   Private Sub Class_Terminate()
     Set m_pGxCatalog = Nothing
     Set m_pGxView = Nothing
     Set m_pGxApp = Nothing
   End Sub

Implementing IContentsView

For a TOC view the only interface that must be implemented is IContentsView. This interface has all the controlling members that allow the TOC view window to be activated and deactivated by the system.

IContentsView is the only mandatory interface for a TOC view class.

Activation and deactivation of the window

Only one TOC view may be active in ArcMap at any given time. When the system or a user activates a view, the IContentsView::Activate method of the appropriate view is called. A reference to the current document (Document) is passed in to the method along with the handle of the parent window (parentHWnd).

Declare the Windows API function ShowWindow and the constants for showing and hiding windows using this function.

Private Const SW_HIDE = 0
Private Const SW_SHOW = 9
 
Private Declare Function ShowWindow Lib "user32" (ByVal hwnd As Long, _
 ByVal nCmdShow As Long) As Long

Place the GxTreeView onto the screen by calling the Windows API function ShowWindowpass in the window handle you stored in the class initialization code.

Private Sub IContentsView_Activate(ByVal parentHWND As esriSystem.OLE_HANDLE, ByVal Document As esriArcMapUI.IMxDocument)
  ShowWindow m_lhwnd, SW_SHOW
End Sub

When a custom TOC view is activated, it should display its window. You can use Windows API calls to show and hide the GxTreeView.

ShowWindow can be used to change the state of any window, for example, to minimize, maximize, hide, or show a window—where you use it to show the GxTreeView window on the screen.

IContentsView::Deactivate is called by the system on the currently active view when a user or code selects a different TOC view.

Private Sub IContentsView_Deactivate()
  ShowWindow m_lHWnd, SW_HIDE
End Sub

If you stored a reference to the current MxDocument by using the reference passed to Activate or by sinking events interfaces, you should also release the reference at this point.

When a TOCView is called to deactivate itself, you should hide the GxTreeView window. You should also release any references to any items in the document or map.

The handle of a TOC view window is returned to ArcMap via the IContentsView::hWnd property. In this case, you should pass the handle of the GxTreeView using the member variable that you set in the Activate method.

Private Property Get IContentsView_hWnd() As esriSystem.OLE_HANDLE
  IContentsView_hWnd = m_lHWnd
End Property

Other members of IContentsView

Some of the members of IContentsView were designed to be used particularly by the Display and Source view, as they apply particularly to the behavior and functionality provided by these views. However, you should add code to the implementation of at least the Name, SelectedItem, and Visible properties, which are discussed below.

Although it is not essential for every custom TOC view to fully implement each member of IContentsView, you should implement at least the Name, SelectedItem, and Visible properties.

The Name property must return the text that identifies your TOC view tab in the TOCDockableWindowit is a good idea to keep this short for display purposes.

Private Property Get IContentsView_Name() As String
  IContentsView_Name = "Catalog"
End Property

The Name property is used in the TOCDockableWindow as the tab caption.

The Visible property relates to the settings in the TOC tab of the Options dialog box. This dialog box displays all the currently registered TOC views. Users can select and deselect each TOC view to determine if the view is displayed in the TOC. This setting is stored at the document level. By default the CatalogView is visible, but you can allow users to change this by storing a boolean value.

Private m_bIsVisible As Boolean
...
Private Property Let IContentsView_Visible(ByVal bValue As Boolean)
  m_bIsVisible = bValue
End Property

The Visible property allows users to turn a TOC view on and off.

The SelectedItem property is designed to link TOC views with other calling code. The TOCDisplayView, for example, may return either a reference to a map layer, legend item, or map frame depending on which item is selected.

From SelectedItem, return a reference to the SelectedObject of the contained GxApplication.

You will implement IContentsView::SelectedItem to allow other code to access the currently selected item in the CatalogView. The SelectedItem property passes a Variant back to the calling object; therefore, any type of object can safely be returned; in this case, SelectedItem returns an IGxObject reference.

Private Property Get IContentsView_SelectedItem() As Variant
  If (m_pGxApp Is Nothing) Then Exit Property
 
  If (Not m_pGxApp.SelectedObject Is Nothing) Then
    Set IContentsView_SelectedItem = m_pGxApp.SelectedObject
  Else
    Set IContentsView_SelectedItem = Nothing
  End If
End Property

The GxTreeView only allows a single object to be selected at any one time; therefore, you can only return a single item from this property.

The Refresh method is called after a TOC view is activated. It is also called by the system at certain other times—for example, when layers are added to the map. The TOC view should update its contents at this point. In CatalogView, simply forward the refresh call to the contained GxApplicationthis will ensure that any changes in the file system (for example, data which has been created, deleted, or moved) are reflected in the view.

Private Sub IContentsView_Refresh(ByVal Item As Variant)
  If (Not m_pGxApp Is Nothing) Then m_pGxApp.Refresh ("")
End Sub

Plugging CatalogView into ArcMap

Once the component is compiled, you need to register the CatalogView to the ESRI Contents View component category. See Chapter 2, 'Developing Objects', for more information on how you can register to component categories.

When ArcMap starts it creates a list of all the TOC views in this category. It then creates a new display tab in the TOC window for each view.

For each view, if IContentsView::Visible returns True, then that view will automatically be made visible in the TOC.

After the TOC view window is created, ArcMap will use the hWnd property to embed your client window into the TOC tab view.

After registering your TOC view, you should find your TOC looks something like that shown here.

Back to top

Go to example code

See Also Creating different kinds of TOC views, Creating Custom TOC Views, and Creating Cartography.