DisplayPaths define a unique presentation of an element.
More...
|
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...
|
|
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.
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.
#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. |
static DisplayPathPtr Create |
( |
| ) |
|
|
static |
Construct a new/empty path.
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.
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.
- See also
- DisplayPath::GetChildElem
Return the number of entries in this path.
ElementRefP GetCursorElem |
( |
| ) |
const |
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.
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.
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
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
DgnPlatform::DisplayPathType mdlDisplayPath_getPathType |
( |
DisplayPathCP |
path | ) |
|
Get the type of a DgnPlatform::DisplayPath.
- Returns
- type of path.
- Parameters
-
[in] | path | path of interest. |
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. |
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. |
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. |
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
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. |
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. |
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.
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
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
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
void mdlDisplayPath_removeFromHead |
( |
DisplayPathCP |
path | ) |
|
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. |
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. |
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. |
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 . |
ElementRefP PopPathElem |
( |
| ) |
|
Remove the element from the end of a path. The cursor index will adjusted if necessary.
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.
Set the root DgnModelRefP for a path being constructed.