Creating Custom Elements

In this section

Creating a subtype of Element

You can see from the ArcMap object model diagram that the existing element coclasses are all subtypes of the Element abstract class.

Any custom element, therefore, should implement a minimum of IElement, IElementProperties, IBoundsProperties, and ITransform2D. IElementProperties2 may also be implemented for completeness, although this is not essential for an element to function.

In addition, elements should always implement IClone and either IPersist and IPersistStream or IPersistVariant, depending on your development environment. You may also want to implement IPropertySupport, as this will increase compatibility with existing graphics tools; however, it is not mandatory and cannot be implemented in VB.

Elements are clonable and persistable. They are stored in the document.

FrameElement or GraphicElement

In the object model diagram, elements are split further, with coclasses inheriting either from the GraphicElement or FrameElement abstract classes.

Your next design decision should be whether your custom element is a FrameElement or GraphicElement.

A FrameElement is an element that implements IFrameElement and forms a border around other elements or objects. Many FrameElements, such as MapFrame and TableFrame, can only appear on a page layout.

A GraphicElement draws simple graphic shapes, pictures, or text, for example, the MarkerElement, LineElement, and TextElement. The IGraphicElement interface adds the ability for an element to appear in either page layout or data view.

Some elements, such as GroupElement and BMPPictureElement, implement both IFrameElement and IGraphicElement. They can appear both as simple graphics and can also draw with a surrounding frame and can be placed in either a page layout or data view.

ArcGIS uses different kinds of elements.
Some elements can only appear in page layout view. GraphicElements can be added to a map and will account for changes in the map's coordinate system. FrameElements have a surrounding neatline.

General design issues for a custom element

Below is a brief review of some design decisions you might need to make when creating a custom element.

Does the element need to appear in the data view? If so, create a subtype of GraphicElement. Does the element need a neatline to surround it? If so, create a subtype of FrameElement.
Do you need access to the current map for the element to draw or behave correctly? If so, you should consider using VC++ and create a subtype of MapSurround instead.
If you decide your graphic element needs access to the current document (like this example), make sure your element can degrade its behavior safely if instantiated in a process outside ArcMap, for example, the MapControl or PageLayoutControl.
When deciding which existing element interfaces to implement, in addition to the functionality you want to add, consider which existing property pages will apply to your element (see the sections on element property pages later in this section).