Public Member Functions | List of all members
ElementHandle Struct Reference

A readonly "handle" to an element. More...

#include <ElementHandle.h>

Inheritance diagram for ElementHandle:
ChildElemIter EditElementHandle ChildEditElemIter ElemAgendaEntry

Public Member Functions

 ElementHandle ()
 construct a blank, invalid, ElementHandle More...
 
 ~ElementHandle ()
 
 ElementHandle (ElementRefP elRef, DgnModelRefP modelRef=0)
 Construct an ElementHandle from an ElementRefP and a DgnModelRefP. More...
 
 ElementHandle (ElementId id, DgnModelRefP modelRef)
 Construct an ElementHandle from an ElementId and a DgnModelRefP. More...
 
 ElementHandle (MSElementDescrCP elDscr, bool owned, bool isUnmodified=false, DgnModelRefP modelRef=0)
 Construct an ElementHandle from an MSElementDescr. More...
 
 ElementHandle (MSElementCP el, DgnModelRefP modelRef)
 Construct an ElementHandle from an MSElement and a DgnModelRef. More...
 
 ElementHandle (ElementHandleCR from)
 Copy an ElementHandle. More...
 
ElementId GetElementId () const
 Get the element ID of the element contained in the ElementHandle. More...
 
Handler Queries
void ResetHandler () const
 
HandlerGetHandler (MissingHandlerPermissions perm=MISSING_HANDLER_PERMISSION_None) const
 Get the Handler for this ElementHandle. More...
 
DisplayHandlerP GetDisplayHandler () const
 A shortcut method to get a DisplayHandler pointer for the Handler of this ElementHandle, or NULL if the element's Handler does not derive from DisplayHandler. More...
 
IDependencyHandlerP GetIDependencyHandler () const
 A shortcut method to get the IDependencyHandler interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...
 
ITransactionHandlerP GetITransactionHandler () const
 A shortcut method to get the ITransactionHandler interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...
 
ITextQueryCP GetITextQuery () const
 A shortcut method to get the ITextQuery interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...
 
ITextEditP GetITextEdit () const
 A shortcut method to get the ITextEdit interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface. More...
 
Element Data Queries
ElementRefP GetElementRef () const
 Get the ElementRefP for this ElementHandle. More...
 
DgnModelP GetDgnModelP () const
 Get a DgnModelP for this ElementHandle. More...
 
DgnFileP GetDgnFileP () const
 Get the DgnFile of the DgnModel for this ElementHandle. More...
 
DgnModelRefP GetModelRef () const
 Get the DgnModelRef for this ElementHandle. More...
 
MSElementCP GetElementCP () const
 Get a const pointer to the MSElement associated with this ElementHandle. More...
 
bool IsValid () const
 Determine whether this ElementHandle is currently valid. More...
 
bool IsPersistent () const
 Determine whether this ElementHandle references an unmodified element in the cache. More...
 
int GetElementType () const
 Get the element type of the element referenced by this ElementHandle. More...
 
void GetElementHeader (Elm_hdr &hdr) const
 Get a copy of the Elm_hdr of the element referenced by this ElementHandle. More...
 
MSElementDescrCP PeekElementDescrCP () const
 Peek to see whether this ElementHandle currently has an MSElementDescr. More...
 
MSElementDescrCP GetElementDescrCP () const
 Get an MSElementDescrCP from this ElementHandle. More...
 
Element Linkage Queries
ConstElementLinkageIterator BeginElementLinkages (UInt16 rl=0) const
 Get an iterator over the element's user data linkages. More...
 
ConstElementLinkageIterator EndElementLinkages () const
 Get an iterator that marks the end of the element's user data linkages. More...
 

Detailed Description

A readonly "handle" to an element.

Collections and Iterators

Constructor & Destructor Documentation

construct a blank, invalid, ElementHandle

References NULL.

ElementHandle ( ElementRefP  elRef,
DgnModelRefP  modelRef = 0 
)
explicit

Construct an ElementHandle from an ElementRefP and a DgnModelRefP.

Parameters
[in]elRefThe ElementRefP of the element for this ElementHandle.
[in]modelRefOptional DgnModelRefP used to access the element (Only needed to associate with a reference).
ElementHandle ( ElementId  id,
DgnModelRefP  modelRef 
)

Construct an ElementHandle from an ElementId and a DgnModelRefP.

Parameters
[in]idThe ElementId of the element for this ElementHandle.
[in]modelRefThe DgnModelRefP used to access the element.
Remarks
NOTE: test IsValid to determine whether the element was found!
ElementHandle ( MSElementDescrCP  elDscr,
bool  owned,
bool  isUnmodified = false,
DgnModelRefP  modelRef = 0 
)

Construct an ElementHandle from an MSElementDescr.

Parameters
[in]elDscrMSElementDescr to be referenced by this ElementHandle.
[in]ownedIf true, destructor of this ElementHandle will free elDscr. Otherwise, caller maintains ownership of elDscr.
[in]isUnmodifiedif true, elDscr is an exact image of the element in the cache. When this is true, users of this ElementHandle may choose to use the cache image instead of elDscr. For example, the display code may choose to use a previously-cached presentation to draw the element. If you're not sure, pass false.
[in]modelRefWill be used if elDscr.h.dgnModelRef is NULL.
ElementHandle ( MSElementCP  el,
DgnModelRefP  modelRef 
)

Construct an ElementHandle from an MSElement and a DgnModelRef.

This technique is rarely useful or necessary. This constructor merely allocates an owned MSElementDescr from the element.

Parameters
[in]elElement from which the MSElementDescr for this ElementHandle should be created.
[in]modelRefDgnModelRef for element.
Remarks
NOTE: This means that the ElementHandle points to a copy of the input element.

Copy an ElementHandle.

Member Function Documentation

ConstElementLinkageIterator BeginElementLinkages ( UInt16  rl = 0) const

Get an iterator over the element's user data linkages.

Parameters
rlLinkage ID filter value identifies the linkages of interest. Defaults to all linkages.
ConstElementLinkageIterator EndElementLinkages ( ) const

Get an iterator that marks the end of the element's user data linkages.

DgnFileP GetDgnFileP ( ) const

Get the DgnFile of the DgnModel for this ElementHandle.

Returns
the DgnModelRef.
Note
This method CAN (and sometimes will) return NULL.

References DgnModel::GetDgnFileP(), and NULL.

DgnModelP GetDgnModelP ( ) const

Get a DgnModelP for this ElementHandle.

Returns
the DgnModelP. First checks ElementRefP, if present, and then resorts to using DgnModelRef.
Note
This method CAN (and sometimes will) return NULL.
DisplayHandlerP GetDisplayHandler ( ) const

A shortcut method to get a DisplayHandler pointer for the Handler of this ElementHandle, or NULL if the element's Handler does not derive from DisplayHandler.

References Handler::GetDisplayHandler(), and Bentley::DgnPlatform::MISSING_HANDLER_PERMISSION_None.

MSElementCP GetElementCP ( ) const

Get a const pointer to the MSElement associated with this ElementHandle.

Returns
a const pointer the MSElement associated with this ElementHandle.
Remarks
The pointer returned by this method must be treated as const. It is never valid or legal to cast away the const-ness of this pointer. Doing so will result in either an access violation or a corrupted cache.
MSElementDescrCP GetElementDescrCP ( ) const

Get an MSElementDescrCP from this ElementHandle.

If this ElementHandle does not already have an MSElementDescr, allocate one using the ElementRefP/DgnModelRef.

Remarks
This call should only be used where necessary, and should be avoided in readonly, time critical cases. In particular DisplayHandler::Draw methods should avoid this call since the alloc/free overhead can be substantial.
Use PeekElementDescrCP to see whether this ElementHandle already has an MSElementDescr.
This method returns a pointer to the MSElementDescr in the ElementHandle. It is still owned by the ElementHandle and must not be released by the caller.
void GetElementHeader ( Elm_hdr &  hdr) const

Get a copy of the Elm_hdr of the element referenced by this ElementHandle.

ElementId GetElementId ( ) const

Get the element ID of the element contained in the ElementHandle.

ElementRefP GetElementRef ( ) const

Get the ElementRefP for this ElementHandle.

Returns
the ElementRefP, or NULL.
int GetElementType ( ) const

Get the element type of the element referenced by this ElementHandle.

Returns
the type of the element referenced by this ElementHandle

Get the Handler for this ElementHandle.

Every element must have a handler. This method returns a reference to the Handler for this element. If this ElementHandle has an ElementRefP, its handler is returned. Otherwise, the MSElementDescr is used.

Parameters
[in]permThe requsted permission for the task for which the Handler will be used. This is only relevant when the element's Handler is not present on the system and no appropriate Enabler can be located. In that case, the system will return a Handler that respects the "missing handler" permissions specified when the element was created.
Note
If you attempt to get the Handler for an Invalid ElementHandle, it will return a "NullHandler" that does nothing.
IDependencyHandlerP GetIDependencyHandler ( ) const

A shortcut method to get the IDependencyHandler interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface.

ITextEditP GetITextEdit ( ) const

A shortcut method to get the ITextEdit interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface.

ITextQueryCP GetITextQuery ( ) const

A shortcut method to get the ITextQuery interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface.

ITransactionHandlerP GetITransactionHandler ( ) const

A shortcut method to get the ITransactionHandler interface on the Handler for this ElementHandle, or NULL if the element's Handler does not implement that interface.

DgnModelRefP GetModelRef ( ) const

Get the DgnModelRef for this ElementHandle.

Returns
the DgnModelRef.
Note
This method CAN (and often will) return NULL.
bool IsPersistent ( ) const

Determine whether this ElementHandle references an unmodified element in the cache.

Returns
true if ElementHandle is unmodified representation of element in the cache.
bool IsValid ( ) const

Determine whether this ElementHandle is currently valid.

Returns
true if this ElementHandle references a valid element. If not, all other methods on this ElementHandle will either fail or crash.

References NULL.

MSElementDescrCP PeekElementDescrCP ( ) const

Peek to see whether this ElementHandle currently has an MSElementDescr.

Returns
the current MSElementDescr or NULL.
void ResetHandler ( ) const

The documentation for this struct was generated from the following file:

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.