Creating different kinds of TOC views

In the previous topic you saw how to implement the CatalogView, a basic TOC view with straightforward functionality. You may want to add further functionality to this example, or you may want to implement an entirely different type of TOC view, using this as a starting point. The following sections discuss other issues of TOC view implementation not used in this example.

Selecting multiple items

Other members of IContentsView, such as ContextItem, AddToSelectedItems, and RemoveFromSelectedItems, can be implemented to manage a collection of multiple selected items.

In the CatalogView example, only a single selected item is allowed, and therefore, the class does not maintain a set of selected items. This is because the GxTreeView itself only allows the selection of a single GxObject at one time.

However, the example could be adapted to allow a user to select more than one item at once by using the approach discussed below, which bases a TOC view on a standard tree view control. The GxObjectArray coclass is suitable for creating and managing an enumeration of GxObjects that may be selected—return a reference to the enumerator from IContentsView::ContextItem.

If a user is able to select multiple items in your TOC view, you should fully implement the IContentsView members ContextItem, AddToSelectedItems, and RemoveFromSelectedItems.

Refreshing a TOC view

A client may call Refresh to force a TOC view to update itself at any point, for example, after data has been added to the map or after the initial activation of the view.

Refresh may be called by a client to indicate that a TOC view should update its contents.

To implement the Refresh method, first check the value of the incoming Variant parameter. If only one item needs to be acted on to perform the refresh, the calling function will pass in this one item. Your TOC should interrogate this item and make the appropriate changes to the view.

For example, the TOCDisplayView receives a map layer during the Refresh method when a layer is added to the map. This allows the TOCDisplayView to update the contents of the Legend by adding a LegendItem for that layer.

You may want to set the value of ProcessEvents to True while your TOC view is dealing with a call to Refresh to prevent other code from executing (see below).

Synchronizing the view with changes in ArcMap

The CatalogView does not need to respond to changes in ArcMap, as the display of the tree depends on the data available and not on the contents of the map or document.

However, if you decide it is appropriate for your TOC view to respond to changes in ArcMap by sinking event interfaces, you will need to correctly use the IContentsView::ProcessEvents property, described below.

To respond correctly to changes in ArcMap, you should use the ProcessEvents property of IContentsView together with event interfaces.

Generally, a TOC view should always check its ProcessEvents value before beginning potentially time-consuming processing.

Each member of a sinked event interface should check the value last passed to ProcessEvents to determine whether or not to perform any actions in the view.

The client (ArcMap) uses ProcessEvents on the currently active TOC view to suspend the actions in the TOCView. Later, the TOC view can again synchronize the state of an object in the TOC view with the state of that object somewhere else in the application.

For example, a TOC class may sink the IActiveViewEvents interface to update itself when a user adds or removes map layers. The Map will inform the TOC view it needs to be updated, allowing the TOC view to synchronize itself with the appropriate objects. ArcMap sets the ProcessEvents property of the active TOC view to False before displaying the Add Data dialog box to suspend changes while the dialog box is displayed. After adding the data to the map and completing the redraw, ArcMap will then set ProcessEvents back to True, indicating to the TOC view that it can now process information from events.

When to use IDocumentEvents and IActiveViewEvents

The existing TOC views respond to changes in ArcMap by sinking the IDocumentEvents interface. Changes within the map document are responded to by sinking the IActiveViewEvents interface. Although this example did not require this functionality, you could implement these interfaces if required.

If you store a reference to the current document (passed in to IContentsView::Activate), you should a minimum implement IDocumentEvents, as you will need to keep this reference up-to-date if the current document is changed.

Sinking events interfaces may help your TOC view synchronize with the changes in ArcMap.
You should sink IDocumentEvents if you store a reference to the current document in order to keep this reference up-to-date.

When to use IComPropertySheetEvents

The existing TOC views also sink the IComPropertySheetEvents interface. The OnApply member of this interface is called when changes in its associated property sheet have been applied by the user.

If your custom TOC view implementation includes a property sheet, you may want to sink this interface also.

Sink IComPropertySheetEvents if you provide a property sheet for your TOC view.

Using an alternative tree view

Throughout this book, it is most common to provide user interface components by creating a modeless form that contains various user controls. The handle of the form or of an individual control can then be returned as the client window.

This approach can typically be seen in many example implementations of IToolControl, where the handle of a control or form is returned via the IToolControl::hWnd property. Any window handle can be embedded in the view itself, although most often the handle returned belongs to a single ActiveX control or to a form or picture box that acts as a container for multiple controls.

This example, however, uses a somewhat different approach. The GxTreeView coclass is used to provide the client window, although it is not an ActiveX control. The GxTreeView class has been used here for convenience. Its use does impose certain limitations—the behavior of the view is fixed, only one item can be selected, a GxApplication helper class must be created, and the GxTreeView must be re-created each time the TOC is selected.

The CatalogView example differs from many examples in this book, as it provides a visual component without using a form, dialog box, or control.
You can adapt the example to display a form or control if required.

As an alternative solution, you can use an ActiveX control, for example, the standard tree view control, as the window of the CatalogView.

Add a form to your project, and place an ActiveX control on the form. Return the handle of this control from the IContentsView::HWnd property.

This approach offers much greater flexibility and control over the view—you can control the exact appearance and behavior of the tree view. You can display or exclude anything you want, allowing you to create a user-customizable view of the data.

However, you should consider the additional coding that would be required to implement the view from scratch—you would need to traverse the GxCatalog and add the appropriate GxObjects to the tree.

Each custom TOC view will require different components, depending on the functionality required and the information or items that need to be displayed. For example, you may decide to write a custom TOC view that can display a calculation of the area of selected features after a selection is performed—you could use a rich text box to display this information and return its window handle as the hWnd property.

Extending ArcObjects