Functions | |
StatusInt | mdlLevelTable_getLevelCount (int *levelCountOut, DgnModelRefP modelRefIn, short levelCountTypeIn) |
Get the number of levels in level-table. More... | |
StatusInt | mdlLevelTable_getHighestLevelId (DgnPlatform::LevelId *highestLevelIdOut, DgnModelRefP modelRefIn) |
Get the value of highest used level id in level-table. More... | |
int | mdlLevelTable_getHighestLevelCode (DgnPlatform::LevelCode *highestLevelCodeOut, DgnModelRefP modelRefIn) |
Get the value of highest used level code in level-table. More... | |
StatusInt | mdlLevelTable_getReadOnly (bool *isReadOnlyOut, DgnModelRefP modelRefIn) |
Get read-only flag of level-table. More... | |
bool | mdlLevelTable_isReadOnly (DgnModelRefP modelRefIn) |
Check if level-table is read-only. More... | |
StatusInt | mdlLevelTable_setReadOnly (DgnModelRefP modelRefIn, bool isReadOnlyIn) |
Set read-only flag of level-table. More... | |
StatusInt | mdlLevelTable_rewrite (DgnModelRefP modelRefIn) |
Rewrite the level-table data into current-file. More... | |
StatusInt | mdlLevelTable_drawLevels (bool *viewDraw, bool incrementalIn, DgnPlatform::DgnDrawMode drawModeIn, DgnModelRefP modelRefIn, BitMaskCP levelBitMaskIn, bool startEndMsgIn, bool drawSharedIn) |
Draw all elements on a list of specified levels. More... | |
StatusInt mdlLevelTable_drawLevels | ( | bool * | viewDraw, |
bool | incrementalIn, | ||
DgnPlatform::DgnDrawMode | drawModeIn, | ||
DgnModelRefP | modelRefIn, | ||
BitMaskCP | levelBitMaskIn, | ||
bool | startEndMsgIn, | ||
bool | drawSharedIn | ||
) |
Draw all elements on a list of specified levels.
[in] | viewDraw | views to update. Should point to an array dimensioned to DgnPlatform::MAX_VIEWS, and viewDraw[i] controls whether view i is drawn. If NULL, all views are drawn. |
[in] | incrementalIn | if false, don't erase before drawing |
[in] | drawModeIn | erasing portion of drawing |
[in] | modelRefIn | model ref |
[in] | levelBitMaskIn | bitmask representing the list of levels to draw |
[in] | startEndMsgIn | if true then want in prog/complete msg |
[in] | drawSharedIn | if true, then draw all models/attachments which use the same level |
int mdlLevelTable_getHighestLevelCode | ( | DgnPlatform::LevelCode * | highestLevelCodeOut, |
DgnModelRefP | modelRefIn | ||
) |
Get the value of highest used level code in level-table.
[out] | highestLevelCodeOut | highest level code |
[in] | modelRefIn | model-ref of level-table |
StatusInt mdlLevelTable_getHighestLevelId | ( | DgnPlatform::LevelId * | highestLevelIdOut, |
DgnModelRefP | modelRefIn | ||
) |
Get the value of highest used level id in level-table.
[out] | highestLevelIdOut | highest level id |
[in] | modelRefIn | model-ref of level-table |
StatusInt mdlLevelTable_getLevelCount | ( | int * | levelCountOut, |
DgnModelRefP | modelRefIn, | ||
short | levelCountTypeIn | ||
) |
Get the number of levels in level-table.
The Levels API is designed to enable applications to manage MicroStation Levels The Levels API can be used to manipulate any or all levels' related information. The API can be classified as:
Levels can be created using the mdlLevel_create function. When a level is created, it is assigned a level id. The level id is an unsigned long number which is unique in the context of all levels in a level table. It is a system assigned number and cannot be changed. Once a level is created, elements can be created on the level. The level id is stored in the element. To obtain the level id from the element use the mdlElement_getProperties function.
A level that is unused can be deleted using the mdlLevel_delete function. A level is unused, if there are no elements on the level.
Level ids can be reused. Thus if a level is deleted, then the next level created may be assigned the id of the deleted level.
Default Level: Every file will always have atleast one level called the Default level. In DWG, this is called level "0". Its level code is always set to 0. The name & code of the default level cannot be changed. The default level cannot be deleted.
A level is used, or in other words an element is on the level if:
Each level has the following properties:
Code (or Number) - The level code is an unsigned long. A user may or may-not assign a level code. All user-assigned numbers should be unique in the context of all levels in a level table. The level code can be changed - use function mdlLevel_setCode. To clear a user-assigned level code, supply LEVEL_NULL_CODE to mdlLevel_setCode. User assigned Level code is not supported for DWG Files.
The level code should not be confused with the level id, which also an unsigned long that is also unique in the context of all levels in a level table. The following table which compares level id with level code:
level id | level code | |
---|---|---|
Type | UInt32 | UInt32 |
Uniqueness | Unique in context of level-table | Unique in context of level-table |
Assigned By | System | User |
Is Required | Yes | No, if not assigned by user then system will auto-generate a number |
Changeable? | No | Yes |
Stored in the element? | Yes | No |
Level Element DgnPlatform::Symbology - Color, Weight and Style. A level's element symbology is assigned to all those elements of the level that have their respective symbology set to BYLEVEL. Thus if an element has its color set to COLOR_BYLEVEL, then its level's "Element Color" is used to color the element.
Level DgnPlatform::Symbology - Color, Weight and Style with a set of ON/OFF Override Flags. A level's symbology is assigned to its elements in a particular view, if the "level symbology" attribute of the view is turned on and if the corresponding override flag in the level is turned ON. Thus, if a level's color is set to RED, and if the level color override is ON and if "level symbology" is turned on in View 1, then all elements of the level will be displayed in RED.
Level Display Controls : Turning off a level turns off all elements that are on the level. There are many different ways to turn off a level:
Set level display off: Turning off the display makes all the elements on the level invisible in all the views. Use mdlLevel_setDisplay to turn on/off the level display.
Set view level display off: The level display can be controlled in a specific view independent of other views. Turning off a level in a view makes all the elements on the level invisible in only that specific view. Call mdlView_setLevelDisplay to turn on/off the level display in a view.
Set level frozen on: Freezing a level (turning on the frozen) makes all the elements on the level invisible in all the views. Call mdlLevel_setFrozen with frozenTypeIn parameter set to LEVEL_FROZEN_TYPE_GLOBAL
to turn freeze/unfreeze a level. Freezing a level is similar to turning off the level display with the following differences:
Set level viewport frozen on: DgnPlatform::Viewport freeze is a concept specific to DWG and is applicable to DWG layouts and their viewports. Using this control a level can be frozen only in the context of a layout or a viewport. See description in function mdlLevel_setFrozen with frozenTypeIn parameter set to LEVEL_FROZEN_TYPE_VP_FREEZE
for more details.
What makes an element visible?: In order for an element of a level be visible in a view, the following condition needs to exist:
Level Access Controls : A level can set to hidden or it can be set to readonly.
Set level hidden on: Making a level hidden makes it hidden from the MicroStation user interface. This can be used by third party programs to create levels for their purposes and which the level manager does not display. Beyond that, a hidden level is no different from any other level. Call mdlLevel_setHidden to turn on/off the hidden nature of a level.
Set level readonly: This is similar to making a level hidden, except that it is displayed in the MicroStation user interface. For example, the level manager will list this level, but its attributes cannot be changed. Exception: The level display controls of a readonly level can be changed. Call mdlLevel_setReadOnly to turn on/off the readonly nature of a level.
Set level table readonly: The entire level table may be set read-only. Setting a level-table as read-only has the following implications:
By default, read-only is OFF. Call mdlLevelTable_setReadOnly to turn on/off the readonly nature of a level table.
LevelElementAccess::All, LevelElementAccess::Locked, LevelElementAccess::ReadOnly & LevelElementAccess::ViewOnly
. See description in function mdlLevel_setElementAccess for more details on this mode. In V8 this is not completely supported yet. Even though all the four modes can be set using mdlLevel_setElementAccess, only the first two modes LevelElementAccess::All & LevelElementAccess::Locked
are uniformly supported across the product. The other modes will be supported in a post-V8 release. Levels are stored in a level table. A level table is a type 96 element. Each level is an entry element within the level table. Each level entry element is a type 95 element. Level information is written to file by the function mdlLevelTable_rewrite. Level information is automatically loaded from file when required. If any level information is modified, then the function mdlLevelTable_rewrite needs to be called to make the modification permanent. If mdlLevelTable_rewrite is not called, then the modifications will be valid only in the context of the current session.
Every DGN File will have one associated master level table. All root models of the DGN File share the same level table, i.e. they share the same set of levels.
When a new attachment is created in a DGN file, then each attachment inherits its levels from its source file. The attachment's level overrides can be set to one of the following:
REF_ATTACH_LEVEL_OVERRIDES_ALL
- A snapshot of the attachment's level attributes are read from its source file and stored in the current file as a separate level table. In this mode, the attachment's levels attributes will be independent of the its original levels attributes. If the attachment's source file is opened up and its level attributes are changed, then these changes will not be reflected in the attachment. REF_ATTACH_LEVEL_OVERRIDES_PER_ATTACHMENT
gives the maximum flexibility for controlling attachment level overrides. On the other hand, it tends to maximize the level storage/memory requirements. REF_ATTACH_LEVEL_OVERRIDES_NONE
- In this mode, the attachment's level attributes are always inherit from its source file. None of level attributes of the attachment can be overridden. If the attachment's source file is opened up and its level attributes are changed, then these changes will be reflected in the attachment. Setting REF_ATTACH_LEVEL_OVERRIDES_NONE
minimizes the level storage/memory requirements. REF_ATTACH_LEVEL_OVERRIDES_CREATE_AS_REQUIRED
- This mode is gives the flexibility of REF_ATTACH_LEVEL_OVERRIDES_ALL
without maximizing the level storage/memory requirements. In this mode, the attachment's level attributes start off by always inheriting from its source file (just like the REF_ATTACH_LEVEL_OVERRIDES_NONE
mode). Level attributes can be freely overridden. Only the overridden attachment levels are stored. The level attributes of the attachment's levels which are not overridden come from its source file. If the attachment's source file is opened up and its level attributes are changed, then these changes will be reflected in the attachment, only if the level has not already been overridden for the attachment. The attachment's level overrides can be set by calling the function mdlRefFile_getIntegerParameters with param name REFERENCE_LEVEL_OVERRIDES
(defined in mdl.h). In this case, the (void *) param of mdlRefFile_getIntegerParameters can take one of the override values. mdlRefFile_getIntegerParameters should be called at the time of creating the attachment and before call to the mdlRefFile_completeAttachment(). Changing this override mode after the attachment is completed is not supported.
Both root models and attachment models are represented by the object DgnModelRefP. A level is uniquely identifiable by the combination of the model-ref and its level id. In order to manager levels data, the API will typically take both the model-ref and the level id as parameters.
Levels can be iterated using the mdlLevelIterator_ set of functions.
In order to iterate over levels is to know the level table whose levels are to be iterated over, i.e. you need to have a DgnModelRefP. The mdlLevelIterator_ functions give the ability to iterate over all levels of a given model-ref. In order to iterate of levels of more than one model-ref, use the model-ref iterator functions which give the ability to iterate over model-refs associated with a file-object.
The first step in using the level iterator is to create one with the function mdlLevelIterator_create which takes a model-ref as an input parameter. mdlLevelIterator_getFirst, which gives the level id of the first level in the level table, starts off the iterator. Continue iterating through all the level by making successive calls to mdlLevelIterator_getNext, which gives the level id of the next level, until LEVEL_NULL_ID is returned.
Use mdlLevelIterator_traverse to iterate through all the levels automatically (this will save writing a for loop). The mdlLevelIterator_traverse takes call-back function which is called for all the levels iterated over.
After the iteration is done, call mdlLevelIterator_free to free up memory used by the level iterator.
The level iterator supports a number of ways to control which levels are returned:
[out] | levelCountOut | level count in level-table |
[in] | modelRefIn | model-ref of level-table |
[in] | levelCountTypeIn | one of LEVEL_COUNT_TYPE_ ... (defined in leveltable.h) |
levelCountTypeIn | levelCountOut |
---|---|
LEVEL_COUNT_TYPE_ALL | The number of levels in level table |
LEVEL_COUNT_TYPE_USED | The number of used levels in level table |
LEVEL_COUNT_TYPE_UNUSED | The number of un-used levels in level table |
StatusInt mdlLevelTable_getReadOnly | ( | bool * | isReadOnlyOut, |
DgnModelRefP | modelRefIn | ||
) |
Get read-only flag of level-table.
[out] | isReadOnlyOut | read-only flag - true or false |
[in] | modelRefIn | model-ref of level-table |
bool mdlLevelTable_isReadOnly | ( | DgnModelRefP | modelRefIn | ) |
Check if level-table is read-only.
[in] | modelRefIn | model-ref of level-table |
StatusInt mdlLevelTable_rewrite | ( | DgnModelRefP | modelRefIn | ) |
Rewrite the level-table data into current-file.
This action has one of the following effects:
This function should be called whenever any of the level-table's data is changed by calls to any of the mdlLevel_set... or mdlLevelTable_set... functions. The call to mdlLevelTable_rewrite will make the changes permanent. Otherwise, the changes will be valid only in the current session. The call to mdlLevelTable_rewrite is accumalative, i.e. it writes all the changes made to level data. In other words, multiple changes in the context of a single model-ref can be made before calling mdlLevelTable_rewrite. The rewrite function will rewrite all the changes made to levels of the specified model-ref.
[in] | modelRefIn | model-ref of level-table |
StatusInt mdlLevelTable_setReadOnly | ( | DgnModelRefP | modelRefIn, |
bool | isReadOnlyIn | ||
) |
Set read-only flag of level-table.
Setting a level-table as read-only has the following implications:
By default, read-only is OFF.
[in] | modelRefIn | model-ref of level-table |
[in] | isReadOnlyIn | read-only flag - true or false |