Typedefs | Functions
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]elementPoints 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]userArgPIs the value that was passed to the calling mdlModify function. Typically points to a structure containing parameters for the callback.
[in]modelRefModel which holds the current element
[in]edPpoints 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]newEdPPpoints 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]sourceThe 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]elDescrpointer 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]modelRefmodel to process
[in]compFlagcomplex elem flags
[in]eleFunccalled for each elem
[in]paramsparameters passed to users eleFunc
[in]compOffsetif 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]modelRefmodel to process
[in]filePosfile position for element
[in]compFlagif true, only do one element
[in]modifyFlagssteps for modification
[in]eleFuncfunction called for each elem
[in]paramsparameters for eleFunc
[in]doGroupsIf 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]modelRefsource modelRef containing the element. If the modelRef is a reference model, the MODIFY_COPY bit in modifyFlags must be set.
[in]filePosfile position of the element
[in]compFlagindicates 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]modifyFlagsflags 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]eleFuncuser 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]paramsparams typically points to a structure containing parameters for eleFunc.
[in]compOffsetis 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]cpthe pointer used in the calls to mdlModify_elementSingle and mdlModify_elementMulti.
See also
dlModify_elementSingle mdlModify_elementMulti mdlModify_elementDescr

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.