IMap.ActiveGraphicsLayer Property

Three different objects contain and persist graphic elements: a Map, the PageLayout, and an FDOGraphicsLayer.  Both the Map and the PageLayout store (persist) their graphics in the document; FDOGraphicsLayers store their graphics in a database (an FDOGraphics layer is a feature annotation layer).

In ArcMap, graphic elements are kept in graphics layers (GraphicLayers objects).  To manage all of the graphic layers, the Map has the CompositeGraphicsLayer object.  The CompositeGraphicsLayer object has a collection of GraphicsLayers and it implements the ICompositeGraphicsLayer interface which provides methods for creating, finding, and deleting GraphicsLayers.  New graphics layers are sometimes called 'Groups' or 'Annotation Target Layers'. 

Not only does the CompositeGraphicsLayer object have a collection of graphics layers, but it is itself a graphics layer - like the FDOGraphicsLayer object, it inherits from the GraphicsLayer object.  This means that the CompositeGraphicsLayer object has its own graphics container where graphic elements can be stored.  The graphics layer it provides is called the 'Basic Graphics Layer'.  This Basic Graphics Layer is the default graphics layer and it cannot be deleted.

The CompositeGraphicsLayer objects implements the ICompositeLayer interface, among others, which has the properties Count and Layer .  The Count does not include the Basic Graphics Layer and the Layer property cannot be used to access the basic graphics layer.  This is because the Basic Graphics Layer is essentially the CompositeGraphicsLayer object whereas the Groups are separate GraphicsLayer objects.  The BasicGraphicsLayer property always returns a reference to the Basic Graphics Layer (the CompositeGraphicsLayer object) and from here you can query interface for the other interfaces implemented by the object including those on the GraphicsLayer object.

The Map's ActiveGraphicsLayer property provides a reference to the graphics layer currently active (sometimes this is called the 'Active Annotation Target Layer).  By default the basic graphics layer is the active layer but any Group or FDOGraphicsLayer is also settable as the active layer.

The CompositeGraphicsLayer and none of its GraphicsLayers (Groups) are real layers like a FeatureLayer, a GroupLayer, or an FDOGraphicsLayer.  None of these layers can be accessed with the Map's Layers property and are not included in the LayerCount.