Handler defines the standard queries and operations available on all elements, whether graphical or non-graphical, internal or application defined. More...

#include <Handler.h>

Inheritance diagram for Handler:

Classes
struct	Extension
	A Handler::Extension can be used to add additional interfaces to a Handler at runtime. More...

Public Member Functions
void	GetDescription (ElementHandleCR el, WStringR string, UInt32 desiredLength)
	Get a brief string describing the element. More...

void	GetTypeName (WStringR string, UInt32 desiredLength)
	Get the type name for this handler. More...

Dynamic Cast Functions
DisplayHandlerP	GetDisplayHandler ()
	Use this method instead of dynamic_cast<DisplayHandlerP> (handler) More...

ITransactionHandlerP	GetITransactionHandler ()
	Use this method instead of dynamic_cast<ITransactionHandlerP> (handler) More...

IDependencyHandlerP	GetIDependencyHandler ()
	Use this method instead of dynamic_cast<IDependencyHandlerP> (handler) More...

Transform and Fence Operations
StatusInt	ApplyTransform (EditElementHandleR element, TransformInfoCR transform)
	Transform the element. More...

StatusInt	FenceStretch (EditElementHandleR element, TransformInfoCR transform, FenceParamsP fp, FenceStretchFlags options)
	The handler is requested to "stretch" the specified element, that is, to transform the portions of the element that meet the clip criteria. More...

StatusInt	FenceClip (ElementAgendaP inside, ElementAgendaP outside, ElementHandleCR element, FenceParamsP fp, FenceClipFlags options)
	The handler is requested to clip the specified element, that is, to return the portions of the element that are inside/outside the clip criteria. More...

void	ConvertTo3d (EditElementHandleR eeh, double elevation)
	Convert a 2d element to it's 3d form. More...

void	ConvertTo2d (EditElementHandleR eeh, TransformCR flattenTrans, DVec3dCR flattenDir)
	Convert a 3d element to it's 2d form. More...

Property query and mutate
void	QueryProperties (ElementHandleCR eh, PropertyContextR context)
	Method for enummerating the common properties of elements such as color and level. More...

void	EditProperties (EditElementHandleR eeh, PropertyContextR context)
	Method for changing the common properties of elements such as color and level. More...

Public Children
bool	ExposeChildren (ElementHandleCR el, ExposeChildrenReason reason)
	Determine whether the children of this element should be exposed to the caller for the intended purpose. More...

Detailed Description

Handler defines the standard queries and operations available on all elements, whether graphical or non-graphical, internal or application defined.

Every element in MicroStation has a Handler. A handler may have more capabilities than what is defined by Handler, but it will have at least these capabilities.

See also: ElementHandle::GetHandler

Remarks: Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib

Member Function Documentation

StatusInt ApplyTransform	(	EditElementHandleR	element,
		TransformInfoCR	transform
	)

Transform the element.

Returns: SUCCESS if the element could be transformed.

Parameters

[in]	element	The element to be transformed.
[in]	transform	The transform to be applied.

Remarks: Even though element may have an associated DgnModelRefP, this method should not base its logic in any way on that or any other particular model. This method applies to the element's intrinsic geometry, which can be viewed through many model refs.; Invokes the OnTransform method. Subclasses should override OnTransform to apply the transform to the element data that they control.

See also: OnTransform OnTransformFinish

void ConvertTo2d	(	EditElementHandleR	eeh,
		TransformCR	flattenTrans,
		DVec3dCR	flattenDir
	)

Convert a 3d element to it's 2d form.

Parameters

[out]	eeh	The element to convert.
[in]	flattenTrans	Transform to apply to flatten the element to a plane.
[in]	flattenDir	Direction used to compute flatten transform.

Note: A 3d only element like CONE_ELM will be converted into a cell containing curve geometry.

void ConvertTo3d	(	EditElementHandleR	eeh,
		double	elevation
	)

Convert a 2d element to it's 3d form.

Parameters

[out]	eeh	The element to convert.
[in]	elevation	The z component to apply to 2d point data.

void EditProperties	(	EditElementHandleR	eeh,
		PropertyContextR	context
	)

Method for changing the common properties of elements such as color and level.

The supplied PropertyContext holds an object that supports the IEditProperties interface. The edit object tells the handler what properties it is interested in and the handler then announces them to the edit object through callback methods. The edit object can decided to replace the property value with a new value which the handler will then use to update itself.

Parameters

[out]	eeh	The element to update the properties of.
[in]	context	The property context that holds the IEditProperties object.

See also: PropertyContext IEditProperties

bool ExposeChildren	(	ElementHandleCR	el,
		ExposeChildrenReason	reason
	)

Determine whether the children of this element should be exposed to the caller for the intended purpose.

In general it is a VERY BAD idea to expose your internal children to outside callers. Handler implementers are encouraged to be very careful about ever returning true from this method, other than for counting. Generally, only orphan cells or other loose grouping elements should return true.

Parameters

[in]	el	The element to test
[in]	reason	The intended purpose for visiting the children of this element

Returns: true if the children should be exposed (made visible) for this purpose

See also: ChildElemIter ChildEditElemIter

StatusInt FenceClip	(	ElementAgendaP	inside,
		ElementAgendaP	outside,
		ElementHandleCR	element,
		FenceParamsP	fp,
		FenceClipFlags	options
	)

The handler is requested to clip the specified element, that is, to return the portions of the element that are inside/outside the clip criteria.

status parameter will be set to the outcome of the operation.

Parameters

[out]	inside	Part(s) of element inside fence.
[out]	outside	Part(s) of element outside fence.
[in]	element	The element to clip
[in]	fp	The fence parameters to apply
[in]	options

Returns: SUCCESS if the element could be clipped.

Remarks

Normally, subclasses should not override this method, but should override OnFenceClip instead.

This method checks for system asynchs and handles special cases, as follows:

 *   if (callAsynchs == true && some SYSTEM_FENCE_CLIP asynch returns SUCCESS)
 *       return SUCCESS
 * 
 *   If optimized clipping is enabled
 *       if optimized clipping succeeds
 *           return SUCCESS
 *   otherwise
 *       return OnFenceClip */

/**

See also: OnFenceClip

StatusInt FenceStretch	(	EditElementHandleR	element,
		TransformInfoCR	transform,
		FenceParamsP	fp,
		FenceStretchFlags	options
	)

The handler is requested to "stretch" the specified element, that is, to transform the portions of the element that meet the clip criteria.

If entire element is inside fence it should be transformed. status parameter will be set to the outcome of the operation.

Parameters

[in]	element	The element to stretch.
[in]	transform	The transform to apply to the portions of the element that meet the clip criteria
[in]	fp	The fence parameters to apply.
[in]	options

Returns: SUCCESS if the element could be stretched.

Remarks

Normally, subclasses should not override this method, but should override OnFenceStretch instead.

This method handles special cases, as follows:

*   Call mdlClip_isElemInsideExt
* 
*   if element is entirely outside the fence
*       return SUCCESS;
* 
*   if element is entirely inside the fence
*       return ApplyTransform (element, transform)
* 
*   Otherwise, the element overlaps the fence.
* 
*   return OnFenceStretch
*

See also: OnFenceStretch OnFenceStretchFinish

void GetDescription	(	ElementHandleCR	el,
		WStringR	string,
		UInt32	desiredLength
	)

Get a brief string describing the element.

Parameters

el	IN the element for this handler.
string	OUT description string to be filled in.
desiredLength	IN the largest number of characters the caller wishes to see in the description. Implementers should endeavor to honor this if possible, and should return the most elaborate description possible within the desired length. However, implementers should never truncate the description to nonsense, even if the minimum sensible length exceeds desiredLength. Callers must be prepared for strings that exceed desiredLength.

Remarks: el may point to a changed or history state of the element's data. This happens when GetDescription is called by design history.

DisplayHandlerP GetDisplayHandler ( )

Use this method instead of dynamic_cast<DisplayHandlerP> (handler)

Returns: this if the class is derived from DisplayHandler; NULL otherwise.

Referenced by ElementHandle::GetDisplayHandler().

IDependencyHandlerP GetIDependencyHandler ( )

Use this method instead of dynamic_cast<IDependencyHandlerP> (handler)

Returns: this if the class implements IDependencyHandler; NULL otherwise.

ITransactionHandlerP GetITransactionHandler ( )

Use this method instead of dynamic_cast<ITransactionHandlerP> (handler)

Returns: this if the class implements ITransactionHandler; NULL otherwise.

void GetTypeName	(	WStringR	string,
		UInt32	desiredLength
	)

Get the type name for this handler.

Currently used to populate the select tool's element type category. Handlers that want their elements selected by type need to implement this method. A sub-type handler should return a unique name and not the base class name.

Parameters

[out]	string	Description string to be filled in.
[in]	desiredLength	The largest number of characters the caller wishes to see in the description.

void QueryProperties	(	ElementHandleCR	eh,
		PropertyContextR	context
	)

Method for enummerating the common properties of elements such as color and level.

The supplied PropertyContext holds an object that supports the IQueryProperties interface. The query object tells the handler what properties it is interested in and the handler then announces them to the query object through callback methods.

Parameters

[in]	eh	The element to extract the properties of.
[in]	context	The property context that holds the IQueryProperties object.

See also: PropertyContext IQueryProperties

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

Handler.h

Classes

Public Member Functions

Detailed Description

Member Function Documentation