An ElementHandle is indirect reference to an element's current state. More...
Classes | |
| struct | ElementHandle |
| A readonly "handle" to an element. More... | |
| struct | EditElementHandle |
| A writeable "handle" to an MSElement. More... | |
| struct | ChildElemIter |
| An Iterator for the children of an ElementHandle for query purposes. More... | |
| struct | ChildEditElemIter |
| An Iterator for the children of an EditElementHandle that allows modification. More... | |
Detailed Description
An ElementHandle is indirect reference to an element's current state.
It permits access to the element transparently, whether the underlying element data is held in an MSElementDescr or merely referenced through an ElementRefP. An ElementHandle is the "this" pointer for all methods of Element Handlers.
An ElementHandle provides readonly access to the underlying element. The subclass EditElementHandle adds methods that allow modification of the underlying element.
It should be obvious that for time critical bulk operations that merely read but don't change existing elements, access through an ElementRefP is more efficient and preferable to MSElementDescr. An ElementRefP contains a direct pointer to the element's cached representation in memory, whereas an MSElementDescr is a alloced/freed copy of the data. However, if you already have an MSElementDescr, or if the element is being modified or created in memory via an MSElementDescr, then it is not possible to use an ElementRefP. ElementHandle provides the mechanism to abstract access to an element, using the ElementRefP where possible and reading the MSElementDescr only when necessary.
ElementHandle Lifecycle
ElemHandles are lightweight objects and are usually stack-based. ElemHandles can be constructed from either an ElementRefP/ModelRef pair or via an existing MSElementDescr. When constructing an ElementHandle from an existing MSElementDescr (which should be avoided if possible - its far better to create an ElementHandle from an ElementRefP/ModelRef and let the ElementHandle read the MSElementDescr when necessary), you must indicate whether the ElementHandle is to "own" the MSElementDescr or not. If an ElementHandle holds an "owning" reference to an MSElementDescr, its destructor releases the reference and frees the MSElementDescr. Whenever an ElementHandle reads an MSElementDescr on behalf of a caller, it saves the MSElementDescr as an owning reference. In this manner, ElemHandles can be used much like a "smart pointer" for MSElementDescr's.
- Remarks
- Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib