ArcObjects Library Reference (Carto)

IMap.BasicGraphicsLayer Property

[Visual Basic .NET]
Public ReadOnly Property BasicGraphicsLayer As IGraphicsLayer

[C#]
public IGraphicsLayer BasicGraphicsLayer {get;}

[C++]
HRESULT get_BasicGraphicsLayer(
  IGraphicsLayer** GraphicsLayer
);

[C++]

Parameters
GraphicsLayer [out, retval]

  GraphicsLayer is a parameter of type IGraphicsLayer**

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

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 can also be set as the active layer.

Neither the CompositeGraphicsLayer nor any 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 they are not included in the Map's LayerCount.