The ToC could be considered as another way to show the user the MapContext. In the ToC we can see the collection of layers that are contained by the MapContext and that are drawn over the View MapControl. The layers located below in the ToC are the first ones to be drawn and those at the top are the last ones to draw.

Other information shown by the ToC:

• Tree structure of the layers (those that are grouped and how).
• The type of layer (Vectorial, Raster)
• If it is visible or not.
• If it is active or not. (The active layers are highlighted. This is used for processes involving only active layers, e.g., to make a selection).
• The legend applied to each layer (symbols, colors, etc).
• Other type of information (if there it has been an error with a layer or if there is a process running in the background, etc).

Most of the time, we will not need to modify the ToC behavior, except to create and/or disable the contextual menu options (those that show up when we right-click with the mouse over a particular layer or group of layers). Because of it, we will look at how the mechanism to create these menu options work first.

Example: Add contextual menu that zoom in the layer over which we click.

Firstly to do is to register an extension point for the contextual menu. This is necessary so all the contextual menus show together.

ExtensionPoints extensionPoints = ExtensionPointsSingleton.getInstance();
extensionPoints.add("View_TocActions","ZoomAlTema",new ZoomAlTemaTocMenuEntry());

The ExtensionPointsSingleton class is a record (inherits of TreeMap) where we can register classes so they can be created by the framework when needed. The idea in this case is to give an entry list of the contextual menu and of the classes that inherits the AbstractContextMenuAction. This abstract class has functions to obtain the layer over which we have clicked (if it is a layer), the MapContext associate to the ToC (useful to refresh the map, for example), to know if have click over a “leaf” or a “branch” (isTocItemBranch, isTocItemLeaf) in the ToC tree…

In our case, the class we have created is ZoomAlTemaTocMenuEntry, in the package com.iver.cit.gvsig.project.documents.view.toc.actions.

The code that executes upon selecting this option is:

public void execute(ITocItem item, FLayer[] selectedItems) {
    if (selectedItems.length==1) {
        try {
            if (!selectedItems[0].isAvailable()) return;
                    getMapContext().zoomToExtent(selectedItems[0].getFullExtent());
        } catch (com.iver.cit.gvsig.fmap.DriverException e1) {
            e1.printStackTrace();
        }   
    } else {
        try {
            Rectangle2D maxExtent = setMaxExtent(selectedItems);
            getMapContext().zoomToExtent(maxExtent);
        } catch (com.iver.cit.gvsig.fmap.DriverException e1) {
            e1.printStackTrace();
        }
    }
}

The method execute() gets as parameters the ToC item over which we had clicked and the list of selected layers. In any case, the method more useful is getMapContext(), since it gives access to the real model of what we are looking at in the view (Layers + ViewPort).

The TOC class (com.iver.cit.gvsig.project.documents.view.toc.gui) is a panel containing the tree of layers and the main component inherits from a JTree => DnDJTree (it is added a support for drag and release, among other things).

The items representing the layers follow a Composite pattern, where the branches represent the layers and the groups of layers and the leaves represent the symbols with their corresponding descriptions. Visually they are an icon + a label.