IInstancingContext and IHierarchicalInsertionContext Interfaces

Table of Contents IInstancingContext Interface IHierarchicalInsertionContext Interface Topics in this section

Instancing is implemented in two interfaces: primarily in IInstancingContext and also with IHierarchicalInsertionContext.

IInstancingContext Interface

The IInstancingContext interface provides all the editing commands customarily available under application Edit menus. It is primarily used for contexts without any kind of hierarchy to the objects. It contains these methods:

• CanCopy(): Return whether the context can copy the selection.
• Copy(): Copy the selection, returning a data object representing the copied items.
• CanInsert(): Return whether the context can insert the data object.
• Insert(): Insert the data object into the context.
• CanDelete(): Return whether the context can delete the selection.
• Delete(): Delete the selection.

Note that these methods all operate on the current selection, so the current context must allow selection. As previously mentioned in What is Instancing, you need to implement some mechanism for selection, as well as instancing.

These methods are very general, so they apply to editing objects of any type. IInstancingContext could apply to graphic objects on a canvas as for ATF Fsm Editor Sample and ATF State Chart Editor Sample. It can also apply to objects dragged from a palette, as in the ATF Simple DOM Editor Sample. It can apply to composite objects, such as prototypes, as in the ATF Fsm Editor Sample.

This interface is used in various editing mechanisms, too. Instancing supports both editing with menu items from either the Edit menu or context menus, as well as drag and drop editing.

IHierarchicalInsertionContext Interface

The IHierarchicalInsertionContext interface is used for contexts that can insert new objects under a specific parent object, by drag and drop for example. Its methods are a subset of IInstancingContext:

• CanInsert(): Can the child object be inserted under the given parent.
• Insert(): Insert the child object under the given parent.

IHierarchicalInsertionContext works with objects of any type that can be selected, just as for IInstancingContext.

If implementing instancing in a context with hierarchical items, it can be more appropriate to use the insertion methods of IHierarchicalInsertionContext rather than IInstancingContext.

For instance, the ApplicationUtil class provides utilities for inserting objects in contexts. This class is used by several hierarchical editor components:

• ListViewEditor: Base class for list editors.
• TreeControlEditor: Base class for tree editors.
• TreeListViewEditor: Tree editor with right click context menu editing. It is used in the ATF Tree List Editor Sample.

These components use ApplicationUtil's CanInsert() and Insert() methods, which have parameters for context, child, and parent objects. If the given context implements IHierarchicalInsertionContext, the IHierarchicalInsertionContext interface's CanInsert() and Insert() methods are used to insert the child under the parent. If only IInstancingContext is implemented in the context, then its methods are used.

In addition, the LayeringContext class implements IHierarchicalInsertionContext for contexts with a hierarchy of layer objects. The ATF Circuit Editor Sample uses this context for its Layers window, which allows you to create layers of objects. You can control a layer and its individual object's visibility with check boxes in this window. You can also drag layers under other layers, so there is a hierarchy of layers, as shown in this illustration:

The visibility of lower layers is controlled its parent layers' visibility.

Topics in this section