Modules | Classes | Macros | Functions
DisplayPaths

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]pathpath of interest.
[out]outStringthe 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]pathpath 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]pathpath of interest.
[in]elementcheck 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]pathpath of interest.
[in]drawModedrawing mode (see msdefs.h)
[in]drawPurposepurpose 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]pathpath of interest.
[in]viewMaskbitmask of the views in which path should be drawn.
[in]drawModedrawing mode (see msdefs.h)
[in]drawPurposepurpose 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]pathpath to copy to.
[in]fromPathsource 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]pathpath 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]pathpath 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]pathpath 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]pathpath 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]pathpath of interest.
[in]indexindex 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]pathpath of interest.
[in]indexindex 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]pathpath 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]pathpath 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]pathpath of interest.
[out]edPPtransformed element descriptor for path. Must be freed by caller.
[in]indexindex to start from.
[in]viewNumview 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]transPtransform for path.
[in]pathpath of interest.
[in]indexindex to start transform from. -1 means last element in path.
[in]viewNumviewNum 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]pathpath of interest.
[in]onOffif 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]pathpath of interest.
[in]elementelement 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]pathpath of interest.
[in]otherPathother path to compare against.
[in]fullPathif 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]pathpath to test
[in]containerPathother 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]elementElement to be the only member of the DgnPlatform::DisplayPath.
[in]modelRefRoot 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]pathpath 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]pathpath of interest.
[in]elementElement 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]pathpath 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]pathpath 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]pathpath of interest.
[in]indexthe 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]pathpath of interest.
[in]newElemElement to be only entry in path.
[in]newModelDgnPlatform::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]pathpath of interest.
[in]elementnew element to be in path.
[in]indexindex 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]pathpath of interest.
[in]rootnew 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.


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