DisplayPaths define a unique presentation of an element. More...

Modules
	HitPaths

Classes
struct	DisplayPath

Macros
#define	MAX_DISPLAYPATH_INFO_STRING 256
	Get a string that describes the contents of a DgnPlatform::DisplayPath. More...

Functions
DgnModelRefP	GetRoot () const
	Return the root DgnModelRefP for this path. More...

int	GetCount () const
	Return the number of entries in this path. More...

ElementRefP	GetPathElem (int index) const
	Return the ElementRefP at the supplied path index. More...

ElementRefP	GetHeadElem () const
	Return the ElementRefP at the head of the path (i.e. More...

ElementRefP	GetTailElem () const
	Return the ElementRefP at the end of the path (i.e. More...

ElementRefP	GetCursorElem () const
	Return the ElementRefP at the cursor index. More...

ElementRefP	GetComponentElem () const
	Return the ElementRefP of the innermost component of a complex element. More...

ElementRefP	GetChildElem (ExposeChildrenReason reason=ExposeChildrenReason::Query) const
	Return the ElementRefP of the innermost public component of a complex element for the given expose reason. More...

ElementRefP	GetSharedChildElem (ExposeChildrenReason reason=ExposeChildrenReason::Query) const
	Return the ElementRefP of the innermost public component of a shared cell definition element for the given expose reason. More...

void	SetRoot (DgnModelRefP ref)
	Set the root DgnModelRefP for a path being constructed. More...

void	PushPathElem (ElementRefP elRef)
	Add an ElementRefP to the end of a path being constructed. The cursor index will be set to this ElementRefP. More...

ElementRefP	PopPathElem ()
	Remove the element from the end of a path. The cursor index will adjusted if necessary. More...

void	SetCursorIndex (int index)
	Set the cursor index for this path. More...

static DisplayPathPtr	Create ()
	Construct a new/empty path. More...

DisplayPathCP	mdlDisplayPath_new (ElementRefP element, DgnModelRefP modelRef)
	Create a new display path from an ElementRefP and a DgnPlatform::DgnModelRef. More...

void	mdlDisplayPath_release (DisplayPathCP path)
	Release a reference to a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_addRef (DisplayPathCP path)
	Add a reference to a DgnPlatform::DisplayPath. More...

bool	mdlDisplayPath_contains (DisplayPathCP path, ElementRefP element)
	Test to see whether a DgnPlatform::DisplayPath has a specific ElementRefP in it. More...

int	mdlDisplayPath_getCount (DisplayPathCP path)
	Get the number of entries in a DgnPlatform::DisplayPath. More...

DgnPlatform::DisplayPathType	mdlDisplayPath_getPathType (DisplayPathCP path)
	Get the type of a DgnPlatform::DisplayPath. More...

ElementRefP	mdlDisplayPath_getElem (DisplayPathCP path, int index)
	Get the ElementRefP at a specific index in a DgnPlatform::DisplayPath. More...

ElementRefP	mdlDisplayPath_getCursorElem (DisplayPathCP path)
	Get the ElementRefP at the Cursor index. More...

int	mdlDisplayPath_getCursorElemIndex (DisplayPathCP path)
	Get the index of the Cursor for a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_setCursorElemIndex (DisplayPathCP path, int index)
	Set the index of the Cursor for a DgnPlatform::DisplayPath. More...

DgnModelRefP	mdlDisplayPath_getPathRoot (DisplayPathCP path)
	Get the Root DgnModelRefP of a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_getTransformToWorld (TransformP transP, DisplayPathCP path, int index, int viewNum)
	Get the transform for a given view of a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_getTransformedEdP (DisplayPathCP path, MSElementDescrH edPP, int index, int viewNum)
	Get a copy of the component element descriptor at a specific index in a DgnPlatform::DisplayPath, transformed into the world coordinate system of a specific view. More...

void	mdlDisplayPath_drawInViews (DisplayPathCP path, int viewMask, DgnPlatform::DgnDrawMode drawMode, DgnPlatform::DrawPurpose drawPurpose)
	Draw a DgnPlatform::DisplayPath in a particular set of views. More...

void	mdlDisplayPath_draw (DisplayPathCP path, DgnPlatform::DgnDrawMode drawMode, DgnPlatform::DrawPurpose drawPurpose)
	Draw a DgnPlatform::DisplayPath in all active views. More...

void	mdlDisplayPath_hilite (DisplayPathCP path, bool onOff)
	Hilite or unhilite a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_setRoot (DisplayPathCP path, DgnModelRefP root)
	Set the Root DgnPlatform::DgnModelRef for a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_setPath (DisplayPathCP path, ElementRefP newElem, DgnModelRefP newModel)
	Set a DgnPlatform::DisplayPath to a new Root and single-entry ElementRefP. More...

void	mdlDisplayPath_fromPath (DisplayPathCP path, DisplayPathCP fromPath)
	Make a copy of a DgnPlatform::DisplayPath into a different path. More...

void	mdlDisplayPath_pushElemRef (DisplayPathCP path, ElementRefP element)
	Add a new entry to a DgnPlatform::DisplayPath. More...

ElementRefP	mdlDisplayPath_popElemRef (DisplayPathCP path)
	Remove the last entry in a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_insertAtHead (DisplayPathCP path, ElementRefP element)
	Insert an ElementRefP into the beginning of a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_removeFromHead (DisplayPathCP path)
	Remove the first entry in a DgnPlatform::DisplayPath. More...

void	mdlDisplayPath_setPathElem (DisplayPathCP path, ElementRefP element, int index)
	Change a single entry in a DgnPlatform::DisplayPath. More...

int	mdlDisplayPath_getCursorIndex (DisplayPathCP path)
	Get the current Cursor index of a DgnPlatform::DisplayPath. More...

bool	mdlDisplayPath_isSubPathOf (DisplayPathCP path, DisplayPathCP containerPath)
	Check to see whether this DgnPlatform::DisplayPath is a subpath of another path (that is, does the other path begin with this path). More...

bool	mdlDisplayPath_isSamePath (DisplayPathCP path, DisplayPathCP otherPath, bool fullPath)
	Check to see if two paths are identical. More...

void	mdlDisplayPath_getInfoString (DisplayPathCP path, WChar *outString)

UInt32	mdlDisplayPath_getEffectiveElemLevel (DisplayPathCP path, int index)
	Get the effective level of an element in a DgnPlatform::DisplayPath. More...

Detailed Description

DisplayPaths define a unique presentation of an element.

To understand the purpose of DisplayPaths, you have to understand why a single ElementRefP, on it's own, does not define a unique presentation.

The answer is References and Shared Cells.

Since a single Model can be attached as a reference multiple times through DgnModelRefs (each with a different transform), each Element in the Model can be displayed multiple times - each with a different size and location. Similarly, Elements within a Shared Cell Definition are displayed every time a Shared Cell Instance is displayed. To uniquely specifiy one of Elements of a Shared Cell Instance, you have to know the ModelRef of the instance, the ElementRefP of the instance, and the ElementRefP of the Element in the definition. Since Shared Cells can be nested (that is, there can be Shared Cell Instances within a Shared Cell Definition), the number of ElementRefs required to uniquely specify an Element can vary.

Therefore, Display Paths are composed of a Root DgnPlatform::DgnModelRef, and a variable-length array of ElementRefs, each of which can specify a new coordinate system or clipping region for all subsequent entries in the path.

In addition to the Root DgnPlatform::DgnModelRef and the array of ElementRefs, DisplayPaths also hold a Cursor index. The Cursor of a DgnPlatform::DisplayPath determines the element of interest in a particular path.

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

Display Paths

DisplayPaths define a unique presentation of an element. To understand the purpose of DisplayPaths, you have to understand why a single ElementRefP, on it's own, does not define a unique presentation.

The answer is References and Shared Cells.

Since a single Model can be attached as a reference multiple times through DgnModelRefs (each with a different transform), each Element in the Model can be displayed multiple times - each with a different size and location. Similarly, Elements within a Shared Cell Definition are displayed every time a Shared Cell Instance is displayed. To uniquely specifiy one of Elements of a Shared Cell Instance, you have to know the ModelRef of the instance, the ElementRefP of the instance, and the ElementRefP of the Element in the definition. Since Shared Cells can be nested (that is, there can be Shared Cell Instances within a Shared Cell Definition), the number of ElementRefs required to uniquely specify an Element can vary.

Therefore, Display Paths are composed of a Root DgnPlatform::DgnModelRef, and a variable-length array of ElementRefs, each of which can specify a new coordinate system or clipping region for all subsequent entries in the path.

In addition to the Root DgnPlatform::DgnModelRef and the array of ElementRefs, DisplayPaths also hold a Cursor index. The Cursor of a DgnPlatform::DisplayPath determines the part of the path that is drawn. For example, suppose a DgnPlatform::DisplayPath consists of:

Example Display Path:
Index	ElementRefP
0	Shared Cell Instance ("ABC"), id=1224
1	Shared Cell Definiton ("ABC"), id= 100
2	Shared Cell Instance ("DEF"), id=122
3	Shared Cell Defintion ("DEF"), id=132
4	Arc Element, id=134

If the Cursor is set to index 0, the entire SCI id=1224 (and all of it's components) will be drawn.

If the Cursor is set to 2, only the SCI id=122 (and all of it's components), within SCI id=1224 will be drawn.

If the Cursor is set to 4, only the Arc Element id=134, within SCI 122, within SCI id=1224 will be drawn.

DisplayPaths are reference counted. Every time you save a pointer to a DgnPlatform::DisplayPath, you must call mdlDisplayPath_addRef, and every time you release a pointer to a DgnPlatform::DisplayPath, you must call mdlDisplayPath_release. DisplayPaths are deleted when their reference count goes to zero.

Macro Definition Documentation

#define MAX_DISPLAYPATH_INFO_STRING 256

Get a string that describes the contents of a DgnPlatform::DisplayPath.

Parameters

[in]	path	path of interest.
[out]	outString	the description of path. Should be at least 256 MSWChars.

Remarks: You can use the MAX_DISPLAYPATH_INFO_STRING constant to define the size of the output buffer.; Required Library: mdlbltin.lib

Function Documentation

static DisplayPathPtr Create ( )

static

Construct a new/empty path.

ElementRefP GetChildElem ( ExposeChildrenReason reason = ExposeChildrenReason::Query ) const

Return the ElementRefP of the innermost public component of a complex element for the given expose reason.

Use this method to get the ElementRefP of the element Handler that owns/manages the entry referenced by this path.

Note: If the path is not to a complex component this method is the same as GetHeadElem.

Remarks: For legacy complex types that wish to be treated as a single entity (ex. Type 18/19, SmartSolids), this method will return their header, not one of their components. Helpful when needing to work with components of normal cells where GetHeadElem can not be used.

ElementRefP GetComponentElem ( ) const

Return the ElementRefP of the innermost component of a complex element.

This method, unlike GetTailElem, stops at a shared cell instance and won't return a shared cell definition component.

Note: If the path is not to a complex component this method is the same as GetHeadElem.

Remarks: Provided to help migrate applications that use to work with a component file position.

See also: DisplayPath::GetChildElem

int GetCount ( ) const

Return the number of entries in this path.

ElementRefP GetCursorElem ( ) const

Return the ElementRefP at the cursor index.

See also: DisplayPath::GetChildElem

ElementRefP GetHeadElem ( ) const

Return the ElementRefP at the head of the path (i.e.

outermost header for a complex element).

Note: Same as GetPathElem (0).

ElementRefP GetPathElem ( int index ) const

Return the ElementRefP at the supplied path index.

-1 will return the ElementRefP at end of the path.

See also: DisplayPath::GetChildElem

DgnModelRefP GetRoot ( ) const

Return the root DgnModelRefP for this path.

ElementRefP GetSharedChildElem ( ExposeChildrenReason reason = ExposeChildrenReason::Query ) const

Return the ElementRefP of the innermost public component of a shared cell definition element for the given expose reason.

Use this method to get the ElementRefP of the element Handler that owns/manages the entry referenced by this path.

Note: If the path is not to a shared cell definition component this method is the same as GetChildElem.

Remarks: For legacy complex types that wish to be treated as a single entity (ex. Type 18/19, SmartSolids), this method will return their header, not one of their components. Helpful when needing to work with components of shared and normal cells where GetHeadElem can not be used.

ElementRefP GetTailElem ( ) const

Return the ElementRefP at the end of the path (i.e.

innermost component of complex element/shared cell defintion)

Note: Same as GetPathElem (-1).

See also: DisplayPath::GetChildElem

void mdlDisplayPath_addRef ( DisplayPathCP path )

Add a reference to a DgnPlatform::DisplayPath.

DisplayPaths are only deleted when their last reference is released.

Parameters

[in,out] path path of interest.

See also: mdlDisplayPath_release

Remarks: Required Library: mdlbltin.lib

bool mdlDisplayPath_contains	(	DisplayPathCP	path,
		ElementRefP	element
	)

Test to see whether a DgnPlatform::DisplayPath has a specific ElementRefP in it.

Returns: true if path contains this element.

Parameters

[in]	path	path of interest.
[in]	element	check if this ElementRefP is in path.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_draw	(	DisplayPathCP	path,
		DgnPlatform::DgnDrawMode	drawMode,
		DgnPlatform::DrawPurpose	drawPurpose
	)

Draw a DgnPlatform::DisplayPath in all active views.

Parameters

[in]	path	path of interest.
[in]	drawMode	drawing mode (see msdefs.h)
[in]	drawPurpose	purpose `path` is to be drawn.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_drawInViews	(	DisplayPathCP	path,
		int	viewMask,
		DgnPlatform::DgnDrawMode	drawMode,
		DgnPlatform::DrawPurpose	drawPurpose
	)

Draw a DgnPlatform::DisplayPath in a particular set of views.

Parameters

[in]	path	path of interest.
[in]	viewMask	bitmask of the views in which `path` should be drawn.
[in]	drawMode	drawing mode (see msdefs.h)
[in]	drawPurpose	purpose `path` is to be drawn.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_fromPath	(	DisplayPathCP	path,
		DisplayPathCP	fromPath
	)

Make a copy of a DgnPlatform::DisplayPath into a different path.

Parameters

[in,out]	path	path to copy to.
[in]	fromPath	source path to copy.

Remarks: Required Library: mdlbltin.lib

int mdlDisplayPath_getCount ( DisplayPathCP path )

Get the number of entries in a DgnPlatform::DisplayPath.

Returns: the number of entries in path.

Parameters

[in] path path of interest.

Remarks: Required Library: mdlbltin.lib

ElementRefP mdlDisplayPath_getCursorElem ( DisplayPathCP path )

Get the ElementRefP at the Cursor index.

Returns: The ElementRefP at the Cursor index in path.

Parameters

[in] path path of interest.

Remarks: Required Library: mdlbltin.lib

int mdlDisplayPath_getCursorElemIndex ( DisplayPathCP path )

Get the index of the Cursor for a DgnPlatform::DisplayPath.

Returns: The index of the Cursor path.

Parameters

[in] path path of interest.

Remarks: Required Library: mdlbltin.lib

int mdlDisplayPath_getCursorIndex ( DisplayPathCP path )

Get the current Cursor index of a DgnPlatform::DisplayPath.

Returns: The current Cursor index of path.

Parameters

[in] path path of interest.

Remarks: Required Library: mdlbltin.lib

UInt32 mdlDisplayPath_getEffectiveElemLevel	(	DisplayPathCP	path,
		int	index
	)

Get the effective level of an element in a DgnPlatform::DisplayPath.

Will be different from the element's level only if the element is in a Shared Cell Instance that is placed relative.

Returns: the effective level of the element in path.

Parameters

[in]	path	path of interest.
[in]	index	index of element to get level for.

Remarks: Required Library: mdlbltin.lib

ElementRefP mdlDisplayPath_getElem	(	DisplayPathCP	path,
		int	index
	)

Get the ElementRefP at a specific index in a DgnPlatform::DisplayPath.

Returns: The ElementRefP at index in path.

Parameters

[in]	path	path of interest.
[in]	index	index to get ElementRefP from. 0 is the first ElementRefP in the path. If `index` is -1, return the last ElementRefP in the path.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_getInfoString	(	DisplayPathCP	path,
		WChar *	outString
	)

DgnModelRefP mdlDisplayPath_getPathRoot ( DisplayPathCP path )

Get the Root DgnModelRefP of a DgnPlatform::DisplayPath.

Returns: The Root DgnModelRefP of path.

Parameters

[in] path path of interest.

Remarks: Required Library: mdlbltin.lib

DgnPlatform::DisplayPathType mdlDisplayPath_getPathType ( DisplayPathCP path )

Get the type of a DgnPlatform::DisplayPath.

Returns: type of path.

Parameters

[in] path path of interest.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_getTransformedEdP	(	DisplayPathCP	path,
		MSElementDescrH	edPP,
		int	index,
		int	viewNum
	)

Get a copy of the component element descriptor at a specific index in a DgnPlatform::DisplayPath, transformed into the world coordinate system of a specific view.

Parameters

[in]	path	path of interest.
[out]	edPP	transformed element descriptor for path. Must be freed by caller.
[in]	index	index to start from.
[in]	viewNum	view for transformation.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_getTransformToWorld	(	TransformP	transP,
		DisplayPathCP	path,
		int	index,
		int	viewNum
	)

Get the transform for a given view of a DgnPlatform::DisplayPath.

Parameters

[out]	transP	transform for path.
[in]	path	path of interest.
[in]	index	index to start transform from. -1 means last element in path.
[in]	viewNum	viewNum view to generate transform for.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_hilite	(	DisplayPathCP	path,
		bool	onOff
	)

Hilite or unhilite a DgnPlatform::DisplayPath.

Path will remain hilited until another call to this function with the same path and onOff set to false.

Parameters

[in]	path	path of interest.
[in]	onOff	if true, draw this DgnPlatform::DisplayPath in the hilite color, otherwise turn off the hilite flag and redraw `path` in it's normal color.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_insertAtHead	(	DisplayPathCP	path,
		ElementRefP	element
	)

Insert an ElementRefP into the beginning of a DgnPlatform::DisplayPath.

Parameters

[in,out]	path	path of interest.
[in]	element	element to add at beginning of path.

See also: mdlDisplayPath_removeFromHead

Remarks: Required Library: mdlbltin.lib

bool mdlDisplayPath_isSamePath	(	DisplayPathCP	path,
		DisplayPathCP	otherPath,
		bool	fullPath
	)

Check to see if two paths are identical.

Optionally, the test can be just to see whether the two paths are identical up to their Cursors.

Returns: true if path and otherPath are identical (according to fullPath parameter).

Parameters

[in]	path	path of interest.
[in]	otherPath	other path to compare against.
[in]	fullPath	if true, check entire paths. Otherwise return true if the paths are the same up to their respective Cursors.

Remarks: Required Library: mdlbltin.lib

bool mdlDisplayPath_isSubPathOf	(	DisplayPathCP	path,
		DisplayPathCP	containerPath
	)

Check to see whether this DgnPlatform::DisplayPath is a subpath of another path (that is, does the other path begin with this path).

Returns: true if path is a subpath of containerPath.

Parameters

[in]	path	path to test
[in]	containerPath	other path.

Remarks: Required Library: mdlbltin.lib

DisplayPathCP mdlDisplayPath_new	(	ElementRefP	element,
		DgnModelRefP	modelRef
	)

Create a new display path from an ElementRefP and a DgnPlatform::DgnModelRef.

Parameters

[in]	element	Element to be the only member of the DgnPlatform::DisplayPath.
[in]	modelRef	Root ModelRef for the DgnPlatform::DisplayPath.

Returns: Reference to new DgnPlatform::DisplayPath.

Note: Returned path has reference count set to 1, call to mdlDisplayPath_release will free it.

Remarks: Required Library: mdlbltin.lib

ElementRefP mdlDisplayPath_popElemRef ( DisplayPathCP path )

Remove the last entry in a DgnPlatform::DisplayPath.

Returns: The ElementRefP just removed from path.

Parameters

[in,out] path path of interest.

See also: mdlDisplayPath_pushElemRef

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_pushElemRef	(	DisplayPathCP	path,
		ElementRefP	element
	)

Add a new entry to a DgnPlatform::DisplayPath.

Parameters

[in,out]	path	path of interest.
[in]	element	Element to add to end of path.

See also: mdlDisplayPath_popElemRef

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_release ( DisplayPathCP path )

Release a reference to a DgnPlatform::DisplayPath.

If this is the last reference, the DgnPlatform::DisplayPath is deleted.

Parameters

[in,out] path path of interest.

See also: mdlDisplayPath_addRef

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_removeFromHead ( DisplayPathCP path )

Remove the first entry in a DgnPlatform::DisplayPath.

Parameters

[in,out] path path of interest.

See also: mdlDisplayPath_insertAtHead

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_setCursorElemIndex	(	DisplayPathCP	path,
		int	index
	)

Set the index of the Cursor for a DgnPlatform::DisplayPath.

Parameters

[in,out]	path	path of interest.
[in]	index	the new Cursor index.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_setPath	(	DisplayPathCP	path,
		ElementRefP	newElem,
		DgnModelRefP	newModel
	)

Set a DgnPlatform::DisplayPath to a new Root and single-entry ElementRefP.

Parameters

[in,out]	path	path of interest.
[in]	newElem	Element to be only entry in path.
[in]	newModel	DgnPlatform::DgnModelRef to be new Root of path.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_setPathElem	(	DisplayPathCP	path,
		ElementRefP	element,
		int	index
	)

Change a single entry in a DgnPlatform::DisplayPath.

Parameters

[in,out]	path	path of interest.
[in]	element	new element to be in path.
[in]	index	index to change.

Remarks: Required Library: mdlbltin.lib

void mdlDisplayPath_setRoot	(	DisplayPathCP	path,
		DgnModelRefP	root
	)

Set the Root DgnPlatform::DgnModelRef for a DgnPlatform::DisplayPath.

Parameters

[in,out]	path	path of interest.
[in]	root	new Root for `path`.

Remarks: Required Library: mdlbltin.lib

ElementRefP PopPathElem ( )

Remove the element from the end of a path. The cursor index will adjusted if necessary.

void PushPathElem ( ElementRefP elRef )

Add an ElementRefP to the end of a path being constructed. The cursor index will be set to this ElementRefP.

void SetCursorIndex ( int index )

Set the cursor index for this path.

void SetRoot ( DgnModelRefP ref )

Set the root DgnModelRefP for a path being constructed.

Modules

Classes

Macros

Functions

Detailed Description

Display Paths

Macro Definition Documentation

Function Documentation