Element Modification

Typedefs
typedef int(*	ModifyFunc_EachElement )(MSElementP element, CallbackArgP userArgP, DgnModelRefP modelRef, MSElementDescrP edP, MSElementDescrH newEdPP, DgnPlatform::ModifyElementSource source)
	UserFunction utilized by mdlModify_elementSingle, mdlModify_elementMulti, and mdlModify_elementDescr. More...

Functions
int	mdlModify_elementDescr (MSElementDescrH elDescr, DgnModelRefP modelRef, int compFlag, ModifyFunc_EachElement eleFunc, CallbackArgP params, long compOffset)
	Modify an element descriptor in memory. More...
UInt32	mdlModify_elementMulti (DgnModelRefP modelRef, UInt32 filePos, int compFlag, int modifyFlags, ModifyFunc_EachElement eleFunc, CallbackArgP params, int doGroups)
	Similar to mdlModify_elementSingle, except that this function also processes selection sets and graphic groups. More...
UInt32	mdlModify_elementSingle (DgnModelRefP modelRef, UInt32 filePos, int compFlag, int modifyFlags, ModifyFunc_EachElement eleFunc, CallbackArgP params, long compOffset)
	Reads an element from the design file and calls a function for each component of that element. More...
void	mdlModify_freeGGMap (MdlCopyParams *cp)
	Frees memory after element modification. More...

Detailed Description

Typedef Documentation

typedef int(* ModifyFunc_EachElement)(MSElementP element, CallbackArgP userArgP, DgnModelRefP modelRef, MSElementDescrP edP, MSElementDescrH newEdPP, DgnPlatform::ModifyElementSource source)

UserFunction utilized by mdlModify_elementSingle, mdlModify_elementMulti, and mdlModify_elementDescr.

Parameters

[in,out]	element	Points to the current element to be modified. This element should be modified in place so that when the callback returns, the new element is in element. The calling mdlModify function adjusts the appropriate values in the header element (if element is a component of a complex element).
[in,out]	userArgP	Is the value that was passed to the calling mdlModify function. Typically points to a structure containing parameters for the callback.
[in]	modelRef	Model which holds the current element
[in]	edP	points to the element descriptor for element. The callback should treat the element descriptor pointed to by edP as read-only and never modify it directly. edP rarely needs to be used, except when the callback needs to know the element structure (the header type).
[out]	newEdPP	points to an element descriptor. This descriptor replaces the current element descriptor if the MODIFY_STATUS_REPLACEDSCR bit is set in the return value of the callback. The calling mdlModify function automatically frees the memory associated with newEdPP.
[in]	source	The source of the element

Returns

Should return a combination of the following values:

eleFunc return value	Meaning
MODIFY_STATUS_NOCHANGE	The element was not changed.
MODIFY_STATUS_REPLACE	Replace original element with the new element.
MODIFY_STATUS_DELETE	Delete the original element.
MODIFY_STATUS_ABORT	Stop processing component elements. MODIFY_STATUS_ABORT can be used with any of the other values.
MODIFY_STATUS_FAIL	An error occurred during element modification. Ignore all changes previously made.
MODIFY_STATUS_REPLACEDSCR	Replace the current element descriptor with a new element descriptor. This is used to replace one or more elements with a (possibly) different number of elements.
MODIFY_STATUS_ERROR	MODIFY_STATUS_FAIL | MODIFY_STATUS_ABORT

See also

mdlModify_elementSingle mdlModify_elementMulti mdlModify_elementDescr

Function Documentation

int mdlModify_elementDescr	(	MSElementDescrH	elDescr,
		DgnModelRefP	modelRef,
		int	compFlag,
		ModifyFunc_EachElement	eleFunc,
		CallbackArgP	params,
		long	compOffset
	)

Modify an element descriptor in memory.

This is the lowest-level function in the mdlModify_... group. mdlModify_elementSingle reads an element descriptor from the design file and calls mdlModify_elementDescr to modify that descriptor. mdlModify_elementDescr is useful when you want to modify an element descriptor but do not want to write the new elements to the file.

Parameters

[in,out]	elDescr	pointer to a pointer to an element descriptor. Since this function can modify the element descriptor, the value of elmDscrPP can be different before and after the call.
[in]	modelRef	model to process
[in]	compFlag	complex elem flags
[in]	eleFunc	called for each elem
[in]	params	parameters passed to users eleFunc
[in]	compOffset	if componentFlag set

Returns

the last status returned by eleFunc.

Remarks

See mdlModify_elementSingle for further argument explanations.

See also

mdlModify_elementSingle mdlModify_elementMulti

UInt32 mdlModify_elementMulti	(	DgnModelRefP	modelRef,
		UInt32	filePos,
		int	compFlag,
		int	modifyFlags,
		ModifyFunc_EachElement	eleFunc,
		CallbackArgP	params,
		int	doGroups
	)

Similar to mdlModify_elementSingle, except that this function also processes selection sets and graphic groups.

Parameters

[in]	modelRef	model to process
[in]	filePos	file position for element
[in]	compFlag	if true, only do one element
[in]	modifyFlags	steps for modification
[in]	eleFunc	function called for each elem
[in]	params	parameters for eleFunc
[in]	doGroups	If doGroups is true, mdlModify_elementMulti processes graphic groups.

Returns

The file position of the new element. If more than one element is modified, such as when a selection set is active, it returns zero.

Remarks

This function makes MDL applications function identically to MicroStation primitives for element modification. It uses the following algorithm:

if (there is a selection set active)
 {
   call mdlModify_elementSingle for all other elements in selection set
 }
 else
 {
   call mdlModify_elementSingle for the element at filePos
   if (doGroups is true and element is a member of a graphic group)
   {
     call mdlModify_elementSingle for all elements in the graphic group
   }
 }

See mdlModify_elementSingle for further argument explanations.

See also

mdlModify_freeGGMap mdlModify_elementSingle mdlModify_elementDescr

UInt32 mdlModify_elementSingle	(	DgnModelRefP	modelRef,
		UInt32	filePos,
		int	compFlag,
		int	modifyFlags,
		ModifyFunc_EachElement	eleFunc,
		CallbackArgP	params,
		long	compOffset
	)

Reads an element from the design file and calls a function for each component of that element.

This function is used when a single element has been identified for modification and an MDL application will change that element.

Parameters

[in]	modelRef	source modelRef containing the element. If the modelRef is a reference model, the MODIFY_COPY bit in modifyFlags must be set.
[in]	filePos	file position of the element
[in]	compFlag	indicates when to call eleFunc for complex elements, and can have one of the following values: componentFlag Meaning MODIFY_REQUEST_NOHEADERS Never call eleFunc for the headers of complex elements. MODIFY_REQUEST_HEADERS Call eleFunc for all components and headers of complex elements. MODIFY_REQUEST_ONLYONE Call eleFunc only once for the component element at offset componentOffset from the header. MDL applications typically use mdlLocate_findElement to find an element and mdlLocate_getComponentOffset to get componentOffset.
[in]	modifyFlags	flags indicating steps for modification. This can be one of the following values: Constant for modifyFlags Meaning MODIFY_ORIG Modify the original element. If the new element is larger than the old element, the old one is deleted and the new one is added to the end of the file. MODIFY_COPY Modify the element and add the new element to the file, leaving the original element unchanged. If a new element is created, it is given a new graphic group number and text node number (if it is a text node). The attributes are processed according to the current linkage generation mode, and the new and not modified bits are set in the header. MODIFY_DONTERASEORIG Do not erase the original element if MODIFY_ORIG is being used. Otherwise, the original element is erased from the screen. MODIFY_DONTDRAWNEW Do not draw the newly created element. MODIFY_DRAWINHILITE Draw the newly created element in the current hilite color. This is valid only if MODIFY_DONTDRAWNEW is not present.
[in]	eleFunc	user call-back function called for each component element to be modified. eleFunc modifies (in memory) an element passed to it as an argument. mdlModify_elementSingle automatically writes the modified element to the file according to the return status of eleFunc.
[in]	params	params typically points to a structure containing parameters for eleFunc.
[in]	compOffset	is used in conjunction with componentFlag when MODIFY_REQUEST_ONLYONE is passed, and a specific component offset must be specified. See compFlag, above.

Returns

The mdlModify_elementSingle function adds a new element or replaces the old element that was modified by eleFunc. It returns the new element's file position.

Remarks

If the MODIFY_COPY bit is set in modifyFlags, mdlModify_elementSingle expects that params points to a structure of type MdlCopyParams. The MdlCopyParams structure is used to maintain graphic grouping information across multiple calls to mdlModify_elementSingle. If you want to make sure that copied elements maintain the same graphic group association as original elements, you must allow MDL to maintain the information in the MdlCopyParams structure across your calls to mdlModify_elementSingle. It does this by allocating memory to hold a table of old/new gg numbers. When you are done with your operation, the call to mdlModify_freeGGMap frees this memory.

There are two cases in MDL where mdlModify_elementSingle is called multiple times on behalf of your program: fence processing and the mdlModify_elementMulti function. In these cases you should call mdlModify_freeGGMap immediately, since you won't be calling mdlModify_elementSingle again. You can tell if you've done things properly by issuing the MicroStation command SHOW HEAP GGMP. There should not be any entries of type GGMP in the heap if all goes well.

mdlModify_elementSingle uses the MdlCopyParams structure to track the mapping of old graphic group numbers to new graphic group numbers. MDL applications must call mdlModify_freeGGMap after mdlModify_elementSingle to free this memory. If your eleFunc requires additional information, declare a structure containing the required information, with MdlCopyParams as the first member. Then pass a pointer to that structure for params as the following example illustrates:

typedef struct myModifyParams
{
   MdlCopyParams ggParams;        // mdlModify_elementSingle
   long beamNumber;               // beam being changed
   int *classCode;                // class code active
   int project;                   // project type
} MyModifyParams;

See also

dlModify_elementDescr mdlModify_elementMulti mdlModify_freeGGMap

void mdlModify_freeGGMap

(

MdlCopyParams *

cp

)

Frees memory after element modification.

When the MODIFY_COPY bit is set in the modifyFlags parameter for mdlModify_elementSingle or mdlModify_elementMulti, these functions duplicate elements before modifying them. One of the steps for duplicating an element is assigning it a new graphic group number. To ensure that all elements in the same graphic group are assigned the same new graphic group number, these functions must allocate memory to track the mapping from original graphic group numbers to new graphic group numbers. See the description in mdlModify_elementSingle for further information on this topic. When MDL applications complete their element modifications, they must call mdlModify_freeGGMap once to free this memory.

Parameters

[in]

cp

the pointer used in the calls to mdlModify_elementSingle and mdlModify_elementMulti.

See also

dlModify_elementSingle mdlModify_elementMulti mdlModify_elementDescr