Enumerations
enum	CellAddType { FromContext = -1, NormalCell = 1, PointCell = 2 }

Functions
int	mdlCell_addLibDescr (MSElementDescrP cellEdP, CellAddType cellType, bool convertNestedCellsToRefs)
	Create a new cell in the currently attached cell library. More...

void	mdlCell_getLibraryName (BeFileNameR filename)
	Obtains the name of the cell library attached to the current design file. More...

int	mdlCell_attachLibrary (BeFileNameR filename, BeFileNameP inputname, WCharCP defaultDir, int fromkeyin)
	Attaches a new cell library to the current design file. More...

int	mdlCell_attachLibraryEx (BeFileNameR filename, BeFileNameP inputname, WCharCP defaultDir, int fromkeyin, int libraryFlag)
	Attach a new cell library to the current design file. More...

StatusInt	mdlCell_upgradeLibrary (WCharCP pLibraryFileName, WCharCP pBackupFileName, bool haveUnits, double uorPerStorage, double unitNumerator, double unitDenominator, WCharCP unitLabel, const DgnPlatform::UnitFlags *unitFlags, int libraryFlag, PFFeedbackFunc feedbackFunc)
	Upgrade the specified cell library to the format used by MicroStation V8. More...

int	mdlCell_create (MSElementP cellElm, WCharCP cellName, Dpoint3d *origin, bool pointCell)
	Creates a new cell element based on the data provided. More...

int	mdlCell_createFromFence (WCharCP cellName, WCharCP descr, Dpoint3d *rOrigin, bool pointCell)
	Create a new cell in the current cell library that contains the elements in the fence. More...

int	mdlCell_createFromFenceByType (WCharCP cellName, WCharCP descr, Dpoint3d *rOrigin, UInt16 cellType)
	Create a new cell in the current cell library that contains the elements in the fence. More...

int	mdlCell_deleteInLibrary (WCharCP cellName)
	Remove a cell from the current active cell library by name. More...

bool	mdlCell_existsInLibrary (WCharCP cellName)
	Indicates whether a cell with the specified name exists in the current cell library. More...

int	mdlCell_extract (Dpoint3d origin, Dpoint3d shape, RotMatrixP rMatrix, Dpoint3d scale, WChar cellName, int bufferSize, MSElementCP cell)
	Extracts the information from a cell header element. More...

int	mdlCell_fixLevels (MSElementDescrP elemDscr, int relativeMode, UInt32 baseLevel, DgnFileP library)
	This function is just a direct call to mdlCell_fixLevelsByCode, so that function should be called instead. More...

int	mdlCell_fixLevelsByCode (MSElementDescrP elemDscr, DgnModelRefP pModelRef, int relativeMode, UInt32 baseLevelId)
	Adjust element levels in a cell element descriptor, elemDscr. More...

StatusInt	mdlCell_getLibraryObject (DgnFileP *ppLibraryObj, WCharCP pLibName, bool unused)
	Returns a pointer to the cell library object of the given name. More...

int	mdlCell_getElmDscr (MSElementDescrH cellDscrPP, MSElementDescrH txtNodeDscrPP, DPoint3dCP rOrigin, DPoint3dCP scale, bool trueScale, RotMatrixCP rotMatrix, short const *attributes, UInt32 ggroup, int sharedFlag, bool updateMasterFile, WCharCP cellName, DgnFileP library)
	Read the specified cell from the cell library and returns the cell's element descriptor. More...

int	mdlCell_getElmDscrExtended (MSElementDescrH cellDscrPP, MSElementDescrH txtNodeDscrPP, MSElementDescrH tagDscrPP, DPoint3dCP rOrigin, DPoint3dCP scale, bool trueScale, DgnModelRefP destModelRef, RotMatrixCP rotMatrix, short const *attributes, UInt32 ggroup, int sharedFlag, bool keepCellDimensionality, bool updateDestFile, WCharCP cellName, DgnFileP library)
	Read the specified cell element from the cell library, and return the cell's element descriptor. More...

int	mdlCell_findCell (DgnFileP *library, DgnFileP preferredLib, WCharCP cellName, int searchAll)
	Search for a cell with the specified cell name. More...

StatusInt	mdlCell_findCellEx (DgnFileP *library, DgnFileP preferredLib, WCharCP cellName, int searchAll, UInt32 rights)
	Search for a cell with the specified cell name. More...

int	mdlCell_copyCellDefinition (DgnFileP destLibrary, WCharCP cellName, DgnFileP sourceLibrary)
	Duplicate a cell definition from one cell library to another. More...

bool	mdlCell_isPointCell (MSElementCP hdr)
	Determine whether the cell cellHeader is a point cell. More...

UInt32	mdlCell_placeCell (DPoint3dCP rOrigin, DPoint3dCP scale, bool trueScale, RotMatrixCP rotMatrix, short *attributes, UInt32 ggroup, bool relativeMode, UInt32 baseLevel, int sharedFlag, WCharCP cellName, DgnFileP library)
	Place a cell in the active model of the current design file. More...

int	mdlCell_extractName (WCharP cellNameP, int bufferSize, MSElementCP elmP)
	Retrieve the name string from a non-shared or shared cell element and copy it to the provided buffer. More...

int	mdlCell_setName (MSElementP elmP, WCharCP cellNameP)
	Set the name of the specified cell. More...

int	mdlCell_extractDescription (WCharP cellDescrP, int bufferSize, MSElementCP elmP)
	Retrieve the description from a cell element and copy it to the provided buffer. More...

int	mdlCell_setDescription (MSElementP elmP, WCharCP cellDescrP)
	Set the description of the specified cell element. More...

int	mdlCell_rename (WCharCP newName, WCharCP oldName)
	Changes the name of cell in the current cell library. More...

void	mdlCell_setRange (MSElementDescrP cellDP, DgnModelRefP modelRef)
	The mdlCell_create and mdlCell_setRange functions are generally used to create library cells in memory for subsequent addition to a cell library using mdlCell_addLibDescr. More...

void	mdlCell_setOriginAndRange (MSElementDescrP cellDP)
	Set the cell's range, range diagonal, and origin. More...

int	mdlCell_readLibraryElements (MSElementDescrH cellElementsPP, WCharCP cellName, DgnFileP library, bool justHeader)
	Get the component elements of the specified cell from the cell library. More...

int	mdlCell_modifyInfo (WCharCP newName, WCharCP newdescr, WCharCP cellName, DgnFileP library)
	Replace the name and description of a cell in a library. More...

StatusInt	mdlCell_replaceLibraryHeaderElement (DgnFileP library, MSElementDescrP cellEdP, CellAddType cellType)
	Replace the data for a cell header in a library. More...

StatusInt	mdlCellLibAsync_getMessageType (int *pCellLibraryMessageType, CellLibAsyncMsgP cellLibAsyncMsg)
	Get the current message type from the CellAsyncMsgP pointer. More...

StatusInt	mdlCellLibAsync_getLibPath (WCharP pCellLibraryPath, int cellLibraryPathLength, CellLibAsyncMsgP cellLibAsyncMsg)
	Get cell library path from the CellAsyncMsgP pointer. More...

Detailed Description

Enumeration Type Documentation

enum CellAddType

strong

Cell Functions

A cell is defined as a group of elements. When placed in a design file, a cell will consist of a cell header (an element of type CELL_HEADER_ELM) and a collection of geometry elements. Cells can be nested.

Cell Libraries

Cells are often stored in libraries. A cell library is nothing more than a standard DGN file. Each model in the file can be placed as as seperate cell. When using the mdlCell API functions, all of the elements in the model will be collected up and grouped under a cell header element. Reference models in the cell model will be converted to nested cells in the cell elements. When extracting the geometry for cell models, the only thing that is respected in the display is whether or not a reference model is displayed. All geometry, regardless of level or display property, will be added to the cell element.

Every DGN file, and therefore cell library, contains an index of the models within it. The index is maintained in memory once a file is accessed. Since the index is maintained within the file it is always up to date. However, programs should not change a library through external means, such as mdlFile_copy, while the file is in use in MicroStation. Doing so will cause the index to be invalid.

When working with cell libraries, developers should also remember the mdlWorkDgn api which can be used to edit the elements in a cell directly.

Enumerator
FromContext
NormalCell
PointCell

Function Documentation

int mdlCell_addLibDescr	(	MSElementDescrP	cellEdP,
		CellAddType	cellType,
		bool	convertNestedCellsToRefs
	)

Create a new cell in the currently attached cell library.

This function also handles copying styles, dependencies, etc. into the library.

Parameters

[in]	cellEdP	a cell element descriptor (type 2) to add to the library.
[in]	cellType	the type of the cell in the library. Use CellAddType::FromContext to choose GRAPHIC or POINT based on the type of the cell. Otherwise, possible values for cellType are CellAddType::NormalCell for a normal graphic cell or CellAddType::PointCell for a point cell.
[in]	convertNestedCellsToRefs	if true, a nested cell with the same name as a cell (model) in the destination library will be replaced by a reference to that cell, which matches the behavior of the MicroStation cell creation tool. When deciding whether to replace, only the cell names are compared, not the geometry. Pre-V8 behavior of this function was to set this to false. mdlCell_createFromFence calls this function with convertNestedCellsToRefs set to true.

Returns: SUCCESS if the cell is added to the library, or an error otherwise. mdlErrno is set to the value that indicates the error cause. Possible values include MDLERR_INVALIDLIBRARY, MDLERR_NOCELLLIBRARY and MDLERR_FILEREADONLY.

Remarks: If a cell with the same name already exists in the library, it will be replaced.

See also: mdlCell_create mdlCell_createFromFence

Remarks: Required Library: mdlbltin.lib

int mdlCell_attachLibrary	(	BeFileNameR	filename,
		BeFileNameP	inputname,
		WCharCP	defaultDir,
		int	fromkeyin
	)

Attaches a new cell library to the current design file.

If a library is successfully attached, filename is set to the cell library's full file specification. If the library is a V7 cell library then this function will fail. It is the equivalent of calling mdlCell_attachLibraryEx with LIBRARY_IgnoreV7Libraries.

Parameters

[out]	filename	name of cell library opened. This should be a string buffer at least MAXFILELENGTH characters long.
[in]	inputname	is the name of the cell library. inputName may contain a path specification. However, if it does not, then MS_CELL and defaultDir (if defined) are searched for the file. If this parameter is NULL, then the active library is detached.
[in]	defaultDir	additional path to search. Can be NULL.
[in]	fromkeyin	if true, the path information from inputName is used. If it is false, mdlCell_attachLibrary assumes that inputName came from the information stored in the design file header (where the path information is not always correct), and it only uses the path information from inputName if the library cannot be found anywhere else. MDL applications should normally set fromKeyin to true.

Remarks: To detach a cell library, pass a NULL string for inputName.

Returns: SUCCESS if a cell library is attached. If it cannot find the cell library, it returns a non-zero value.

See also: mdlCell_attachLibraryEx

Remarks: Required Library: mdlbltin.lib

int mdlCell_attachLibraryEx	(	BeFileNameR	filename,
		BeFileNameP	inputname,
		WCharCP	defaultDir,
		int	fromkeyin,
		int	libraryFlag
	)

Attach a new cell library to the current design file.

If a library is successfully attached, filename is set to the cell library's full file specification.

Parameters

[out]	filename	name of cell library opened. This should be a string buffer at least MAXFILELENGTH characters long.
[in]	inputname	is the name of the cell library. inputName may contain a path specification. However, if it does not, then MS_CELL and defaultDir (if defined) are searched for the file. If this parameter is NULL, then the active library is detached.
[in]	defaultDir	additional path to search. Can be NULL.
[in]	fromkeyin	if true, the path information from inputName is used. If it is false, mdlCell_attachLibraryEx assumes that inputName came from the information stored in the design file header (where the path information is not always correct), and it only uses the path information from inputName if the library cannot be found anywhere else. MDL applications should normally set fromKeyin to true.
[in]	libraryFlag	specifies how to handle the cell library if its format is not up to date. If the cell library is a V7 cell library, then it can be upgraded. See for the possible values.

Returns: SUCCESS if the operation is completed and a cell library was attached, otherwise an error value.

See also: mdlCell_attachLibrary

Remarks: Required Library: mdlbltin.lib

int mdlCell_copyCellDefinition	(	DgnFileP	destLibrary,
		WCharCP	cellName,
		DgnFileP	sourceLibrary
	)

Duplicate a cell definition from one cell library to another.

Remarks: This function always try to convert nested cells to references (see mdlCell_addLibDescr).

Parameters

[in]	destLibrary	the cell library to copy the cell to.
[in]	cellName	the name of the cell to copy.
[in]	sourceLibrary	the cell library to copy the cell from.

Returns: SUCCESS if the cell is copied, otherwise an error code.

Remarks: Required Library: mdlbltin.lib

See also: mdlCell_getLibraryObject

int mdlCell_create	(	MSElementP	cellElm,
		WCharCP	cellName,
		Dpoint3d *	origin,
		bool	pointCell
	)

Creates a new cell element based on the data provided.

This can be used as an orphan cell, or later added to a cell library using mdlCell_addLibDescr. Typically this function is used to create a cell header, and mdlElmdscr_appendDscr is then used to add elements.

Parameters

[out]	cellElm	This is a pointer to a full MSElement union which is filled in.
[in]	cellName	the name of the cell; may be NULL.
[in]	origin	the origin of the cell. If NULL is passed for cellOrigin, the (0, 0, 0) point for the current coordinate system is used.
[in]	pointCell	true if the cell is to be a point cell, otherwise false.

Returns: SUCCESS if the operation is completed successfully, otherwise ERROR

See also: mdlCell_addLibDescr mdlCell_createFromFence

Remarks: Required Library: mdlbltin.lib

int mdlCell_createFromFence	(	WCharCP	cellName,
		WCharCP	descr,
		Dpoint3d *	rOrigin,
		bool	pointCell
	)

Create a new cell in the current cell library that contains the elements in the fence.

It creates the new cell from the current selection set if no fence is defined.

Parameters

[in]	cellName	the name of the cell in the library. This must be less than DgnPlatform::MAX_CELLNAME_LENGTH characters, and must be valid as tested by mdlModel_nameIsValid.
[in]	descr	is the cell description; it may not exceed MAX_CELLDSCR_LENGTH characters.
[in]	rOrigin	the origin of the cell. If NULL is passed for cellOrigin, tcb->celor is used.
[in]	pointCell	true if the cell is to be a point cell, otherwise false.

Remarks: This function collects up all the elements in the fence or selection set and creates a cell element out of them.

Returns: SUCCESS or the error that occurred which prevented the cell creation. mdlErrno is also set to the error value. Possible values include MDLERR_INVALIDLIBRARY, MDLERR_NOCELLLIBRARY and MDLERR_FILEREADONLY.

See also: mdlCell_create mdlCell_addLibDescr

Remarks: Required Library: mdlbltin.lib

int mdlCell_createFromFenceByType	(	WCharCP	cellName,
		WCharCP	descr,
		Dpoint3d *	rOrigin,
		UInt16	cellType
	)

Create a new cell in the current cell library that contains the elements in the fence.

It creates the new cell from the current selection set if no fence is defined.

Parameters

[in]	cellName	the name of the cell in the library. This must be less than DgnPlatform::MAX_CELLNAME_LENGTH characters, and must be valid as tested by mdlModel_nameIsValid.
[in]	descr	is the cell description; it may not exceed MAX_CELLDSCR_LENGTH characters.
[in]	rOrigin	the origin of the cell. If NULL is passed for cellOrigin, tcb->celor is used.
[in]	cellType	the type of cell to create (point, graphic, parametric)

Remarks: This function collects up all the elements in the fence or selection set and creates a cell element out of them.

Returns: SUCCESS or the error that occurred which prevented the cell creation. mdlErrno is also set to the error value. Possible values include MDLERR_INVALIDLIBRARY, MDLERR_NOCELLLIBRARY and MDLERR_FILEREADONLY.

See also: mdlCell_create mdlCell_addLibDescr

Remarks: Required Library: mdlbltin.lib

int mdlCell_deleteInLibrary ( WCharCP cellName )

Remove a cell from the current active cell library by name.

Parameters

[in] cellName name of cell to be deleted.

Returns: SUCCESS if the specified cell was deleted or one of the following error values: MDLERR_CELLNOTFOUND, MDLERR_CELLEXISTS, MDLERR_INVALIDLIBRARY, MDLERR_NOCELLLIBRARY or MDLERR_FILEREADONLY.

Remarks: Required Library: mdlbltin.lib

bool mdlCell_existsInLibrary ( WCharCP cellName )

Indicates whether a cell with the specified name exists in the current cell library.

Parameters

[in] cellName name of the cell to search for.

Returns: true if the cell name exists in the library; otherwise it returns false.

See also: mdlCell_placeCell mdlCell_getElmDscr

Remarks: Required Library: mdlbltin.lib

int mdlCell_extract	(	Dpoint3d *	origin,
		Dpoint3d *	shape,
		RotMatrixP	rMatrix,
		Dpoint3d *	scale,
		WChar *	cellName,
		int	bufferSize,
		MSElementCP	cell
	)

Extracts the information from a cell header element.

If any parameters are NULL, this function does not attempt to fill them in. All parameters are returned in the current (design file) coordinate system.

Parameters

[out]	origin	is the cell origin.
[out]	shape	returns an array of eight Dpoint3d's which represent the minimum bounding box for the cell in the coordinate system of the cell. This idea can be illustrated by using MicroStation's element selection tool to select a cell. MicroStation places handles on the boundary which defines the cell, and these handles correlate to the eight Dpoint3ds returned by mdlCell_extract. Note that this must point to an array large enough to hold the 8 points.
[out]	rMatrix	the rotation matrix for the cell.
[out]	scale	the cell's X, Y and Z scale factors.
[out]	cellName	the cell's name in Unicode.
[in]	bufferSize	if extracting cell's name, number of widechars name buffer can hold. This is ignored if cellName is NULL.
[in]	cell	cell element to extract information from.

Remarks: The points in shape are transformed into the current coordinate system before they are returned. They do not necessarily represent a minimum bounding box in the current coordinate system.

Returns: SUCCESS if cell is a valid MicroStation element of type CELL_HEADER_ELM. Otherwise, it returns MDLERR_BADELEMENT.

See also: mdlCell_create

Remarks: Required Library: mdlbltin.lib

int mdlCell_extractDescription	(	WCharP	cellDescrP,
		int	bufferSize,
		MSElementCP	elmP
	)

Retrieve the description from a cell element and copy it to the provided buffer.

Note that graphic cells and shared cell instances as placed by MicroStation do not keep their descriptions. For shared cells, you should use this function on the definition. For graphic cells, you must find the cell in a library and extract its description that way.

Parameters

[in]	cellDescrP	the buffer where the extracted cell description will be placed.
[in]	bufferSize	the maximum number of MSWChars to copy to the cellDescrP buffer.
[in]	elmP	is the cell element from which the description is extracted.

Returns: SUCCESS if the operation is completed successfully, otherwise ERROR

See also: mdlCell_setDescription mdlCell_extractName

Remarks: Required Library: mdlbltin.lib

int mdlCell_extractName	(	WCharP	cellNameP,
		int	bufferSize,
		MSElementCP	elmP
	)

Retrieve the name string from a non-shared or shared cell element and copy it to the provided buffer.

Parameters

[out]	cellNameP	the buffer where the extracted cell name will be placed.
[in]	bufferSize	the maximum number of MSWChars to copy to cellNameP.
[in]	elmP	the cell element from which the name is extracted.

Returns: SUCCESS if the cell name is successfully found and copied to the buffer, otherwise ERROR.

See also: mdlCell_setName mdlCell_extractDescription

Remarks: Required Library: mdlbltin.lib

int mdlCell_findCell	(	DgnFileP *	library,
		DgnFileP	preferredLib,
		WCharCP	cellName,
		int	searchAll
	)

Search for a cell with the specified cell name.

The search order is first the library passed in as preferredLib; then the current active cell library; and then sequentially though the files listed in MS_CELLLIST and MS_BLOCKLIST if the searchAll parameter is true. The first cell found with the requested name will stop the search.

Remarks: This function will only find cells which have export rights or better. Because of the rights limitation, protected libraries will be skipped and cells will be searched for through th rest of the path. To specify rights, see mdlCell_findCellEx.

Parameters

[out]	library	is the library where the cell was found, if the search was successful. This argument will be NULL if the cell was not found.
[in]	preferredLib	the cell library to search first, or NULL.
[in]	cellName	the name of the cell to search for.
[in]	searchAll	indicates whether all of the cell libraries in the MS_CELLLIST and MS_BLOCKLIST paths are to be searched. Setting this value to 0 indicates that only the preferredLib library is searched; setting this value to 1 indicates that all cell libraries are to be searched; setting this value to 2 indicates that all cell libraries are to be searched and messages generated as the search progresses. Messages are sent to the error display field in the MicroStation window.

Returns: SUCCESS if the cell was found, otherwise MDLERR_CELLNOTFOUND.

Remarks: Required Library: mdlbltin.lib

StatusInt mdlCell_findCellEx	(	DgnFileP *	library,
		DgnFileP	preferredLib,
		WCharCP	cellName,
		int	searchAll,
		UInt32	rights
	)

Search for a cell with the specified cell name.

The search order is first the library passed in as preferredLib; then the current active cell library; and then sequentially though the files listed in MS_CELLLIST and MS_BLOCKLIST if the searchAll parameter is true. The first cell found with the requested name will stop the search. This function differs from mdlCell_findCell by the rights parameter which allows the caller to specify the desired permission level.

Parameters

[out]	library	is the library where the cell was found, if the search was successful. This argument will be NULL if the cell was not found.
[in]	preferredLib	the cell library to search first, or NULL.
[in]	cellName	the name of the cell to search for.
[in]	searchAll	indicates whether all of the cell libraries in the MS_CELLLIST and MS_BLOCKLIST paths are to be searched. Setting this value to 0 indicates that only the preferredLib library is searched; setting this value to 1 indicates that all cell libraries are to be searched; setting this value to 2 indicates that all cell libraries are to be searched and messages generated as the search progresses. Messages are sent to the error display field in the MicroStation window.
[in]	rights	The level of rights that should be tested. See mdlDgnFileObj_checkRights for a description of the choices.

Returns: SUCCESS if the cell was found, otherwise MDLERR_CELLNOTFOUND.

Remarks: Required Library: mdlbltin.lib

int mdlCell_fixLevels	(	MSElementDescrP	elemDscr,
		int	relativeMode,
		UInt32	baseLevel,
		DgnFileP	library
	)

This function is just a direct call to mdlCell_fixLevelsByCode, so that function should be called instead.

It will adjust element levels in a cell element descriptor, elemDscr. This adjustment is based on the cell type and the values of relativeMode and baseLevel. It uses the following logic:

if (cell is a point cell)
    {
    set all levels to baseLevel
    }
else if (relativeMode is true)
    {
    adjust so the lowest level used in cell is baseLevel
    }

         If relative mode is chosen, the all element level ids are adjusted
         by the difference between the lowest level id in the cell and the
         base level id provided.

Parameters

[in]	elemDscr	cell element descriptor
[in]	relativeMode	true for relative level.
[in]	baseLevel	used for point cells and relative mode.
[in]	library	This is no longer used and can be NULL. Instead the model ref from elemDscr->h.dgnModelRef is used.

Remarks: This function is needed because mdlCell_getElmDscr does not apply the above logic before it returns the cell's element descriptor. This functionality was left out of mdlCell_getElmDscr so that you could get the original level values.

Returns: SUCCESS if the levels could be fixed.

See also: mdlCell_getElmDscr mdlCell_fixLevelsByCode

Remarks: Required Library: mdlbltin.lib

int mdlCell_fixLevelsByCode	(	MSElementDescrP	elemDscr,
		DgnModelRefP	pModelRef,
		int	relativeMode,
		UInt32	baseLevelId
	)

Adjust element levels in a cell element descriptor, elemDscr.

This adjustment is based on the cell type and the values of relativeMode and baseLevelId. It uses the following logic:

if (cell is a point cell)
    {
    set all levels to baseLevel
    }
else if (relativeMode is true)
    {
    adjust so the lowest level used in cell is baseLevel
    }

         If relative mode is chosen, the baseLevelId is converted to
         a level code and all element level codes are adjusted by the difference
         between the base level code and lowest level code in the cell.

Parameters

[in]	elemDscr	cell element descriptor
[in]	pModelRef	model ref of element descriptor
[in]	relativeMode	relative or absolute
[in]	baseLevelId	used for point cells and relative mode. This is a level number, not a level code.

Remarks: This function is needed because mdlCell_getElmDscr does not apply the above logic before it returns the cell's element descriptor. This functionality was left out of mdlCell_getElmDscr so that you could get the original level values.

Returns: SUCCESS if the level codes could be adjusted.

See also: mdlCell_getElmDscr mdlCell_fixLevels

Remarks: Required Library: mdlbltin.lib

int mdlCell_getElmDscr	(	MSElementDescrH	cellDscrPP,
		MSElementDescrH	txtNodeDscrPP,
		DPoint3dCP	rOrigin,
		DPoint3dCP	scale,
		bool	trueScale,
		RotMatrixCP	rotMatrix,
		short const *	attributes,
		UInt32	ggroup,
		int	sharedFlag,
		bool	updateMasterFile,
		WCharCP	cellName,
		DgnFileP	library
	)

Read the specified cell from the cell library and returns the cell's element descriptor.

The address of the element descriptor for the cell's graphic elements is returned in cellDscrPP.

Remarks: If empty text nodes are in a cell, MicroStation removes them before it places the cell. These empty text nodes are placed immediately after the cell. For this reason, mdlCell_getElmDscr also extracts the empty text node elements and returns them in a separate element descriptor, txtNodeDscrPP. Applications should treat these empty text nodes similarly. If txtNodeDscrPP is NULL, then empty text nodes will be lost.; If sharedFlag is 1 or 2 and the user has turned shared cells on, the function first searches the active file for a shared cell instance without reading the cell library. If no shared cell is found, then the library is searched.

Parameters

[out]	cellDscrPP	cell element descriptor
[out]	txtNodeDscrPP	element descriptor for empty text nodes. If NULL, these text nodes are lost.
[in]	rOrigin	the location of the cell's origin. If origin is NULL, the cell is transformed to the (0, 0, 0) point in the current coordinate system.
[in]	scale	points to a Dpoint3d structure holding the X, Y and (in 3D) Z scale factors to be applied to the cell's elements. If scale is NULL, the cell is not scaled.
[in]	trueScale	indicates whether the cell definition and DGN file units are used in scaling the cell, resulting in cells that have the same size between models with different units. ACTIVEMODEL is assumed for the destination.
[in]	rotMatrix	is the rotation matrix that defines the cell's orientation. If rMatrix is NULL, the identity matrix is used.
[in]	attributes	an array of attribute information to append to the cell header. This parameter has been deprecated; please see the mdlLinkage functions to append attributes to the cell header.
[in]	ggroup	is the graphic group number for the cell's elements. A value of 0 means that the elements will not be part of a graphic group.
[in]	sharedFlag	indicates whether the element descriptor is for a shared or unshared cell. If sharedFlag is 0, an unshared cell is returned. If sharedFlag is 1, a shared cell is returned if found, otherwise an unshared cell. If sharedFlag is 2, the state of the user-specified shared flag is used.
[in]	updateMasterFile	indicates that the cell is to be placed in the active model ref, so all necessary styles, etc. should be copied to the active file. If this parameter is set to false, then the display of the cell elements may not match the original model.
[in]	cellName	the name of the cell to be returned.
[in]	library	the library object containing the cell. If this argument is NULL, the cell is searched for. It is usually acquired via mdlCell_findCell or mdlCell_getLibraryObject.

Returns: SUCCESS if the cell is read and cellDscrPP is valid. Otherwise, it returns an error status.

See also: mdlCell_placeCell mdlCell_getElmDscrExtended

Remarks: Required Library: mdlbltin.lib

int mdlCell_getElmDscrExtended	(	MSElementDescrH	cellDscrPP,
		MSElementDescrH	txtNodeDscrPP,
		MSElementDescrH	tagDscrPP,
		DPoint3dCP	rOrigin,
		DPoint3dCP	scale,
		bool	trueScale,
		DgnModelRefP	destModelRef,
		RotMatrixCP	rotMatrix,
		short const *	attributes,
		UInt32	ggroup,
		int	sharedFlag,
		bool	keepCellDimensionality,
		bool	updateDestFile,
		WCharCP	cellName,
		DgnFileP	library
	)

Read the specified cell element from the cell library, and return the cell's element descriptor.

The address of the element descriptor for the cell's graphic elements is returned in cellDscrPP.

Remarks: If empty text nodes are present in the cell, they are returned in txtNodeDscrPP. If txtNodeDscrPP is NULL, then empty text nodes are ignored. If tags are present in the cell, they are returned in tagDscrPP. If tagDscrPP is NULL, then tags are returned as part of the cell element descriptor.

Parameters

[out]	cellDscrPP	cell element descriptor.
[out]	txtNodeDscrPP	text node descriptor. If this parameter is not NULL, the returned elmdscr will contain any empty text nodes from the cell. If this parameter is NULL, empty text nodes are ignored.
[out]	tagDscrPP	tag descriptor. If this is not NULL, updateMasterFile should be set to true to ensure that the tag set is copied into the master file.
[in]	rOrigin	is the location of the cell's origin. If origin is NULL, the cell is transformed to the (0, 0, 0) point in the current coordinate system.
[in]	scale	points to a Dpoint3d structure holding the X, Y and (in 3D) Z scale factors to be applied to the cell's elements. If scale is NULL, the cell is not scaled.
[in]	trueScale	indicates whether the cell definition and DGN file units are used in scaling the cell, resulting in cells that have the same size between models with different units.
[in]	destModelRef	specifies the design model to use the units from if trueScale is set to true. It also specifies the destination model ref for copying styles, etc. to if updateDestFile is true. This parameter should not be NULL; use ACTIVEMODEL or INVALID_MODELREF instead.
[in]	rotMatrix	the rotation matrix that defines the cell's orientation. If rMatrix is NULL, the identity matrix is used.
[in]	attributes	an array of attribute information to append to the cell header. This parameter has been deprecated; please see the mdlLinkage functions to append attributes to the cell header.
[in]	ggroup	is the graphic group number for the cell's elements. A value of 0 means that the elements will not be part of a graphic group.
[in]	sharedFlag	indicates whether the element descriptor is for a shared or unshared cell. If sharedFlag is 0, an unshared cell is returned. If sharedFlag is 1, a shared cell is returned if found, otherwise an unshared cell. If sharedFlag is 2, the state of the user-specified shared flag is used.
[in]	keepCellDimensionality	indicates whether the resulting elmdscr should be converted to the dimensionality (2D or 3D) of the destination model ref. This flag is useful when extracting elements which are then going to be added as a shared cell. In this case, it is likely that the desired behavior is for the shared cell definition to maintain its original dimensionality, but all instances should be of the correct dimensionality to write to the model. For example, a 3D shared cell definition can be referenced by shared cell instances in both 3D and 2D models within the same file.
[in]	updateDestFile	indicates that the cell is to be placed in the destModelRef, so all necessary styles, etc. should be copied to the active file. If this parameter is set to false, then the display of the cell elements may not match the original model. Setting this parameter to true is similar to calling mdlElmdscr_copy on the cell element descriptor, except that the cell elements themselves are not added to the file. The program can then choose the correct placement of the elements and perform other operations before adding them to the file.
[in]	cellName	is the name of the cell to be read and returned.
[in]	library	indicates the cell library to read the cell from, or if NULL, the cell is searched for in all available libraries. It is usually acquired via mdlCell_findCell or mdlCell_getLibraryObject.

Returns: SUCCESS if the cell is found and read and a valid descriptor is returned, otherwise ERROR.

See also: mdlCell_placeCell mdlCell_getElmDscr

Remarks: Required Library: mdlbltin.lib

void mdlCell_getLibraryName ( BeFileNameR filename )

Obtains the name of the cell library attached to the current design file.

Parameters

[out] filename name of the attached cell library.

Remarks: If no cell library is attached, the filename will be empty. The filename reflects the active settings. No guarantee is made that the filename refers to a valid cell library file.

See also: mdlCell_attachLibrary

Remarks: Required Library: mdlbltin.lib

StatusInt mdlCell_getLibraryObject	(	DgnFileP *	ppLibraryObj,
		WCharCP	pLibName,
		bool	unused
	)

Returns a pointer to the cell library object of the given name.

This is used by mdlCell_getElmDscr, mdlCell_placeCell, and other functions that require a cell library handle.

Parameters

[out]	ppLibraryObj	pointer to the cell library object.
[in]	pLibName	name of the cell library to find.
[in]	unused	Unused; pass false.

Returns: SUCCESS if the library of the given name is found, otherwise ERROR.

See also: mdlCell_placeCell mdlCell_getElmDscr

Remarks: Required Library: mdlbltin.lib

bool mdlCell_isPointCell ( MSElementCP hdr )

Determine whether the cell cellHeader is a point cell.

Parameters

[in] hdr cell header element

Returns: true if cellHeader is a point cell, false for any other type.

Remarks: Required Library: mdlbltin.lib

int mdlCell_modifyInfo	(	WCharCP	newName,
		WCharCP	newdescr,
		WCharCP	cellName,
		DgnFileP	library
	)

Replace the name and description of a cell in a library.

Parameters

[in]	newName	is the new cell name. Pass NULL to use the old name.
[in]	newdescr	is the new cell description. Pass NULL to use the old description.
[in]	cellName	is the name of the cell to modify.
[in]	library	is the pointer to the cell library to use.

Returns: SUCCESS if the operation is completed successfully, otherwise ERROR.

Remarks: Cell names are case-insensitive, so this function will not work to change only the case of a name. If the cell name contains invalid characters, this operation will fail. See mdlModel_nameIsValid to test for validity. Cell names are limited to DgnPlatform::MAX_CELLNAME_LENGTH wchars.; Required Library: mdlbltin.lib

See also: mdlCell_readLibraryElements mdlCell_getElmDscr mdlCell_replaceLibraryHeaderElement

UInt32 mdlCell_placeCell	(	DPoint3dCP	rOrigin,
		DPoint3dCP	scale,
		bool	trueScale,
		RotMatrixCP	rotMatrix,
		short *	attributes,
		UInt32	ggroup,
		bool	relativeMode,
		UInt32	baseLevel,
		int	sharedFlag,
		WCharCP	cellName,
		DgnFileP	library
	)

Place a cell in the active model of the current design file.

Remarks: If library is NULL, mdlCell_placeCell scans the current cell library for the cell using cellName, and if not found then scans libraries in the MS_CELLLIST path.; If sharedFlag is 1 and a shared cell definition for cellName exists in the design file, a new shared cell instance is placed without the cell library being read, and library is ignored. If the sharedFlag is 1 and no shared cell definition exists, the cell will be read from the library and both the shared cell definition and instance will be created.; If the active model's Annotation Scale lock is ON, the active annotation scale is propagated to the cell. The cell model (from cell library) needs to have the "Can be placed as annotation cell" toggle ON in order to be placed as an annotation cell. If that toggle is OFF, the active annotation scale is propagated only to the annotations contained in that cell model.

Parameters

[in]	rOrigin	the location to place the cell origin. If origin is NULL, the cell is placed at the (0, 0, 0) point in the current coordinate system.
[in]	scale	points to a Dpoint3d structure holding the X, Y, and (in 3D) Z scale factors to be applied to the cell elements before they are placed. If scale is NULL, the cell is placed at a scale factor of 1.0.
[in]	trueScale	if true, use cell model and master model units to scale the cell.
[in]	rotMatrix	the rotation matrix that defines the orientation for cell placement. If rMatrix is NULL, the identity matrix is used. rMatrix does not necessarily need to be orthogonal or normalized. (Cells can be placed skewed).
[in]	attributes	is an array of attribute information to append to the cell header before it is placed. The first short of this array is the length, in shorts, of the attribute data. Note that attribute linkage lengths must be a multiple of four words. If attributes is NULL, the cell has no attributes attached to the header.
[in]	ggroup	the graphic group number for the cell's elements. A value of 0 means that the elements will not be part of a graphic group.
[in]	relativeMode	determines how the levels for the cell's elements are assigned. All elements for a point cell are assigned to baseLevel. If relativeMode is true, the lowest level used in the cell definition is assigned to baseLevel and all other element levels are adjusted accordingly. If relativeMode is false, the levels are taken from the cell library unchanged.
[in]	baseLevel	determines how the levels for the cell's elements are assigned. All elements for a point cell are assigned to baseLevel. For a graphic cell, this is ignored if relativeMode is false. This is a level ID, gotten through functions such as mdlLevel_getIdFromName. Relative placement internally works by level numbers.
[in]	sharedFlag	indicates whether the cell should be placed as shared or unshared. If sharedFlag is 0, an unshared cell is placed. If sharedFlag is 1, a shared cell is created. If sharedFlag is 2, the state of the user-specified shared flag is used. mdlCell_placeCell also creates and places the shared cell definition if it does not exist in the file.
[in]	cellName	is the name of the cell to be placed.
[in]	library	name of library or NULL. If the library is NULL, the cell will be searched for in the active cell library, then all files found on MS_CELLLIST. If the shared flag is 1, then the active file will be searched for a shared cell definition first.

Remarks: The rotation matrix, rotMatrix, is applied before the scale factors.

Returns: the file position of a newly placed cell. If an error occurs, it returns 0 and sets mdlErrno to the specific error cause.

See also: mdlCell_getElmDscr

Remarks: Required Library: mdlbltin.lib

int mdlCell_readLibraryElements	(	MSElementDescrH	cellElementsPP,
		WCharCP	cellName,
		DgnFileP	library,
		bool	justHeader
	)

Get the component elements of the specified cell from the cell library.

Calling this function with justHeader false is the same as calling mdlCell_getElmDscr with no transformations.

Parameters

[out]	cellElementsPP	is an element descriptor containing the elements of the cell.
[in]	cellName	the name of the cell to find and read.
[in]	library	the cell library to read the cell from, or NULL to search.
[in]	justHeader	if set true, only the cell header is read and returned.

Returns: SUCCESS if the operation is completed successfully, otherwise ERROR.

Remarks: Required Library: mdlbltin.lib

int mdlCell_rename	(	WCharCP	newName,
		WCharCP	oldName
	)

Changes the name of cell in the current cell library.

Parameters

[in]	newName	is the new name of the cell in the library. This must be less than DgnPlatform::MAX_CELLNAME_LENGTH characters, and must be valid as tested by mdlModel_nameIsValid.
[in]	oldName	old name for cell in library

Returns: SUCCESS if the specified cell was renamed. If an error occurs, they return one the following values: MDLERR_CELLNOTFOUND, MDLERR_CELLEXISTS, MDLERR_INVALIDLIBRARY, MDLERR_NOCELLLIBRARY or MDLERR_FILEREADONLY.

Remarks: Required Library: mdlbltin.lib

StatusInt mdlCell_replaceLibraryHeaderElement	(	DgnFileP	library,
		MSElementDescrP	cellEdP,
		CellAddType	cellType
	)

Replace the data for a cell header in a library.

Since this will replace all linkages on the element except name and description, care must be taken to avoid removing linkages that should remain. Typically mdlCell_readLibraryElements is used to get the cell header so that the original linkages are in place.

Parameters

[in]	library	is the pointer to the cell library to use.
[in]	cellEdP	is the new cell element to use to replace the header.
[in]	cellType	is the cell type; see mdlCell_addLibDescr for a description of types.

Returns: SUCCESS if the operation is completed successfully, otherwise ERROR.

Remarks: Required Library: mdlbltin.lib

See also: mdlCell_readLibraryElements mdlCell_getElmDscr mdlCell_modifyInfo

int mdlCell_setDescription	(	MSElementP	elmP,
		WCharCP	cellDescrP
	)

Set the description of the specified cell element.

When setting the description of a cell using an element descriptor you need to be careful about changing the length of the cell description as the element descriptor has only been allocated to be large enough for the current description length. The proper way to change the cell descriptor is:

MSElement   element;
memcpy (&element, &cellDP->el, mdlElement_size (&cellDP->el));
mdlCell_setDescription (&element, L"NEW DESCRIPTION");
mdlElmdscr_replaceElement (&cellDP, &element);

Parameters

[in]	elmP	the cell element on which the description will be set.
[in]	cellDescrP	the description to give the cell.

Returns: SUCCESS if the operation is completed successfully, otherwise ERROR.

See also: mdlCell_extractDescription mdlCell_setName

Remarks: Required Library: mdlbltin.lib

int mdlCell_setName	(	MSElementP	elmP,
		WCharCP	cellNameP
	)

Set the name of the specified cell.

When setting the name of a cell using an element descriptor you need to be careful about changing the length of the cell name as the element descriptor has only been allocated to be large enough for the current name length. The proper way to change the cell descriptor is:

MSElement   element;
memcpy (&element, &cellDP->el, mdlElement_size (&cellDP->el));
mdlCell_setName (&element, L"NEW NAME");
mdlElmdscr_replaceElement (&cellDP, &element);

Parameters

[in]	elmP	the cell element on which the name will be set.
[in]	cellNameP	the name to give to the cell.

Returns: SUCCESS if the operation is completed successfully, otherwise ERROR .

See also: mdlCell_extractName mdlCell_setDescription

Remarks: Required Library: mdlbltin.lib

void mdlCell_setOriginAndRange ( MSElementDescrP cellDP )

Set the cell's range, range diagonal, and origin.

The origin is set to the middle of the range. This function only validates the range of the cell against the ACTIVEMODEL. If you are working with a different modelRef, you must use mdlElmdscr_validate and mdlCell_setRange.

Parameters

[in] cellDP the cell's element descriptor.

See also: mdlCell_setRange

Remarks: Required Library: mdlbltin.lib

void mdlCell_setRange	(	MSElementDescrP	cellDP,
		DgnModelRefP	modelRef
	)

The mdlCell_create and mdlCell_setRange functions are generally used to create library cells in memory for subsequent addition to a cell library using mdlCell_addLibDescr.

The programmer typically creates a cell element, creates a new element descriptor, adds the component elements to that element descriptor, calls mdlCell_setRange, and then adds the cell to the library using mdlCell_addLibDescr.

Parameters

[in,out]	cellDP	the element descriptor of the cell.
[in]	modelRef	indicates the model to validate the cell range against. ACTIVEMODEL is typically used.

Remarks: The mdlCell_setRange function must be called to update the range block diagonal in the header of a cell library element descriptor. The range block diagonal is the range of the un-rotated cell, so this function must be called after the cell definition is complete (immediately before mdlCell_addLibDescr is called). The cell range is used when creating cell handles.

See also: mdlCell_addLibDescr mdlCell_setOriginAndRange

Remarks: Required Library: mdlbltin.lib

StatusInt mdlCell_upgradeLibrary	(	WCharCP	pLibraryFileName,
		WCharCP	pBackupFileName,
		bool	haveUnits,
		double	uorPerStorage,
		double	unitNumerator,
		double	unitDenominator,
		WCharCP	unitLabel,
		const DgnPlatform::UnitFlags *	unitFlags,
		int	libraryFlag,
		PFFeedbackFunc	feedbackFunc
	)

Upgrade the specified cell library to the format used by MicroStation V8.

Since V7 cell libraries were unitless, this functions allows you to pass in units to assign for the cells. Most of the parameters for units are the pieces of a DgnPlatform::UnitInfo structure, so consult mdlUnits_* functions for more explanation.

Parameters

[in,out]	pLibraryFileName	the name of the library to convert. The full file specification returned in this parameter, so it should be at least MAXFILELENGTH characters.
[in]	pBackupFileName	the name of a backup file to create before converting. If this parameter is NULL and the libraryFlag indicates that a backup should be made, the backup file will go to MS_BACKUP.
[in]	haveUnits	specifies whether the unit values given by uorPerStorage, unitNumertor, and unitDenominator, unitLabel, and unitFlags are used. All the parameters except uorPerStorage are the same as what is found in a DgnPlatform::UnitInfo structure.
[in]	uorPerStorage	uors per master unit for cells; ignored if haveUnits is false.
[in]	unitNumerator	numerator for converting storage units to meters; ignored if haveUnits is false.
[in]	unitDenominator	denominator for converting storage units to meters; ignored if haveUnits is false.
[in]	unitLabel	specifies the name of the storage units; ignored if haveUnits is false.
[in]	unitFlags	unit flags; ignored if haveUnits is false.
[in]	libraryFlag	specifies LIBRARY_xxx values which can be used to modify the method of handling V7 cell libraries. Possible values are:


Value	Description
LIBRARY_IgnoreV7Libraries	Ignore any V7 libraries; function will return MDLERR_INVALIDLIBRARY.
LIBRARY_AutoConvertToV8	Automatically convert the library without asking user. A backup will be created.
LIBRARY_PromptForConvertToV8	Prompt the user to determine whether to convert. If the user declines, MDLERR_USERABORT is returned.
LIBRARY_AutoConvertToV8NoBackup	Convert the library to the current version and do not create a backup. Instead, pBackupFileName is the source cell library and pLibraryFileName is the output V8 file.

Parameters

[in] feedbackFunc is a feedback function called during conversion if the cell library was a V7 file.

Returns: SUCCESS if the operation is completed and a cell library was attached, otherwise an error value.

See also: mdlCell_attachLibraryEx

Remarks: Required Library: mdlbltin.lib

StatusInt mdlCellLibAsync_getLibPath	(	WCharP	pCellLibraryPath,
		int	cellLibraryPathLength,
		CellLibAsyncMsgP	cellLibAsyncMsg
	)

Get cell library path from the CellAsyncMsgP pointer.

Parameters

[out]	pCellLibraryPath	Returns the full path to the cell library from the CellAsyncMsgP pointer.
[in]	cellLibraryPathLength	This is the size of the buffer pCellLibraryPath.
[in]	cellLibAsyncMsg	is the pointer to the object to query cell library information.

Returns: SUCCESS if the cell info is returned successfully, otherwise ERROR.

See also: mdlCellLibAsync_getMessageType userSystem_cellLibraryChange.htm

Remarks: Required Library: mdlbltin.lib

StatusInt mdlCellLibAsync_getMessageType	(	int *	pCellLibraryMessageType,
		CellLibAsyncMsgP	cellLibAsyncMsg
	)

Get the current message type from the CellAsyncMsgP pointer.

Parameters

[out]	pCellLibraryMessageType	is the message type extracted from the CellAsyncMsgP pointer.
[in]	cellLibAsyncMsg	is the pointer to the object to query cell library information. See mdlSystem_cellLibraryChange for callback formatting

Returns: SUCCESS if the message info is returned successfully, otherwise ERROR.

See also: mdlCellLibAsync_getLibPath mdlCellLibAsync_getMessageType.htm

Remarks: Required Library: mdlbltin.lib

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Cell Functions

Cell Libraries

Function Documentation