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...

Detailed Description

Function Documentation

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.

Parameters

[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

Returns: ERROR if the input level bit-mask is NULL or the model-ref is invalid, else SUCCESS

See also: mdlLevel_draw

int mdlLevelTable_getHighestLevelCode	(	DgnPlatform::LevelCode *	highestLevelCodeOut,
		DgnModelRefP	modelRefIn
	)

Get the value of highest used level code in level-table.

Parameters

[out]	highestLevelCodeOut	highest level code
[in]	modelRefIn	model-ref of level-table

Returns: ERROR if the model-ref is invalid or pHighestLevelCode is NULL, else SUCCESS

StatusInt mdlLevelTable_getHighestLevelId	(	DgnPlatform::LevelId *	highestLevelIdOut,
		DgnModelRefP	modelRefIn
	)

Get the value of highest used level id in level-table.

Parameters

[out]	highestLevelIdOut	highest level id
[in]	modelRefIn	model-ref of level-table

Returns: ERROR if the model-ref is invalid or highestLevelIdOut is NULL, else SUCCESS

StatusInt mdlLevelTable_getLevelCount	(	int *	levelCountOut,
		DgnModelRefP	modelRefIn,
		short	levelCountTypeIn
	)

Get the number of levels in level-table.

API Overview

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:

mdlLevelTable_... set of functions
mdlLevel_... set of functions
mdlLevelIterator_... set of functions
mdlLevelLibrary_... set of functions
mdlLevelFilter_... set of functions
mdlLevelList_... set of functions

Level Creation and Deletion

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.

Level Usage

A level is used, or in other words an element is on the level if:

A graphic element (including element of a shared cell definition) is on the level,
Individual segments of a Multi-line element are on the level,
Individual segments of a Multi-line Style are on the level,
A reference attachment is on the level,
A dimension style has its "Dimension Line Level Override" on the level.

Level Attributes

Each level has the following properties:

Name - The level name is a Unicode String.

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:
1. If a cell-instance is on a frozen level, then all the elements of the cell-instance are not displayed, irrespective of the contained element's level.
2. If an attachment is on a frozen level, then the attachment is not displayed.
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:
- The level display control is ON, and
- The view level display control is ON, and
- The level frozen control is OFF, and
- The level viewport frozen control is OFF (if displaying the element in the context of a DWG layout or a viewport).
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:
- No new levels can be created in the level-table.
- None of the exisiting levels can be deleted from the level-table.
- None of the level attributes can be modified.
- No new level library can be attached to the level-table.
- None of the existing level libraries can be detached from the level-table.
By default, read-only is OFF. Call mdlLevelTable_setReadOnly to turn on/off the readonly nature of a level table.
Level Element Access Controls : The access to elements on a level can be controlled by setting a element access mode on the level. The element access mode can be set to one of 4 values - 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.

Level Data Storage

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.

Level Data Management

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.
In V8, this is the default behavior of the system & cannot be changed from the user interface.
Setting 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.

Iterating Levels

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:

mdlLevelIterator_setIterateType : Specify whether all/root/child/used/unused levels are to be iterated over.
mdlLevelIterator_setLevelFilter : If a level filter is set, then the iterator will return only those levels which pass through the level filter.

Parameters

[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)

Remarks

The return value of levelCountOut will depend on value of levelCountTypeIn as follows:

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

Returns: ERROR if the model-ref is invalid or levelCountOut is NULL, else SUCCESS

StatusInt mdlLevelTable_getReadOnly	(	bool *	isReadOnlyOut,
		DgnModelRefP	modelRefIn
	)

Get read-only flag of level-table.

Parameters

[out]	isReadOnlyOut	read-only flag - true or false
[in]	modelRefIn	model-ref of level-table

Returns: ERROR if the model-ref is invalid or isReadOnlyOut is NULL, else SUCCESS

See also: mdlLevelTable_isReadOnly mdlLevelTable_setReadOnly

bool mdlLevelTable_isReadOnly ( DgnModelRefP modelRefIn )

Check if level-table is read-only.

Parameters

[in] modelRefIn model-ref of level-table

Returns: true if the level-table is read-only, else false

Remarks: If modelRefIn is invalid, then the function returns false.

See also: mdlLevelTable_getReadOnly mdlLevelTable_setReadOnly

StatusInt mdlLevelTable_rewrite ( DgnModelRefP modelRefIn )

Rewrite the level-table data into current-file.

This action has one of the following effects:

If the level-table does not exist in the file, then it is added into the file.
If the level-table already exists in the file, then the information in this level-table is updated based on changes made to the level-data.
For an attachment's level-table, if there are no more any override levels, then this function will remove the attachment's override level-table from file.

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.

Remarks: A successful write to file raises a LEVEL_TABLE_REWRITE event.

Parameters

[in] modelRefIn model-ref of level-table

Returns: ERROR if the model-ref is invalid, else SUCCESS

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:

No new levels can be created in the level-table.
None of the exisiting levels can be deleted from the level-table.
None of the level attributes can be modified.
No new level library can be attached to the level-table.
None of the existing level libraries can be detached from the level-table.

By default, read-only is OFF.

Parameters

[in]	modelRefIn	model-ref of level-table
[in]	isReadOnlyIn	read-only flag - true or false

Returns: ERROR if the model-ref is invalid, else SUCCESS

See also: mdlLevelTable_isReadOnly mdlLevelTable_getReadOnly

Functions

Detailed Description

Function Documentation

API Overview

Level Creation and Deletion

Level Usage

Level Attributes

Level Data Storage

Level Data Management

Iterating Levels