ElementHandle Struct Reference

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

#include <ElementHandle.h>

Inheritance diagram for ElementHandle:

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
Handler &	GetHandler (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

• BeginElementLinkages / EndElementLinkages to iterate the element's linkages

Constructor & Destructor Documentation

ElementHandle

(

)

construct a blank, invalid, ElementHandle

References NULL.

~ElementHandle

(

)

ElementHandle ( ElementRefP  elRef, DgnModelRefP  modelRef = 0  )

explicit

Construct an ElementHandle from an ElementRefP and a DgnModelRefP.

Parameters

[in]	elRef	The ElementRefP of the element for this ElementHandle.
[in]	modelRef	Optional 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]	id	The ElementId of the element for this ElementHandle.
[in]	modelRef	The 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]	elDscr	MSElementDescr to be referenced by this ElementHandle.
[in]	owned	If true, destructor of this ElementHandle will free elDscr. Otherwise, caller maintains ownership of elDscr.
[in]	isUnmodified	if 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]	modelRef	Will 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]	el	Element from which the MSElementDescr for this ElementHandle should be created.
[in]	modelRef	DgnModelRef for element.

Remarks

NOTE: This means that the ElementHandle points to a copy of the input element.

ElementHandle

(

ElementHandleCR

from

)

Copy an ElementHandle.

Member Function Documentation

ConstElementLinkageIterator BeginElementLinkages

(

UInt16

rl = 0

)

const

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

Parameters

rl	Linkage 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

Handler& GetHandler

(

MissingHandlerPermissions

perm = MISSING_HANDLER_PERMISSION_None

)

const

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]

perm

The 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:

• ElementHandle.h