Macros
#define	NGFLAG_ALLOWDUPLICATES (1 << 0)
	This file contains the public functions that manipulate Named Groups. More...

Functions
StatusInt	mdlNamedGroup_create (NamedGroupP *pNamedGroup, WCharCP groupName, WCharCP groupDescr, int groupFlags, DgnModelRefP modelRef)
	Creates a new Named Group object. More...

StatusInt	mdlNamedGroup_free (NamedGroupP *pNamedGroup)
	Frees a Named Group object. More...

StatusInt	mdlNamedGroup_addMember (NamedGroupP namedGroup, DgnPlatform::ElementId elementId, DgnModelRefP modelRef, int memberFlags)
	Adds a member to a Named Group. More...

StatusInt	mdlNamedGroup_removeMember (NamedGroupP namedGroup, unsigned int index)
	Removes a member from a Named Group. More...

StatusInt	mdlNamedGroup_getMemberCount (NamedGroupCP namedGroup, int graphicMembers, int groupMembers)
	Gets the count of graphics members and Named Group members in a Named Group. More...

StatusInt	mdlNamedGroup_getName (NamedGroupCP namedGroup, WCharP nameBuf, unsigned int bufChars)
	Gets the name of the Named Group. More...

StatusInt	mdlNamedGroup_setName (NamedGroupP namedGroup, WCharCP nameBuf)
	Sets the name of the Named Group. More...

StatusInt	mdlNamedGroup_getType (NamedGroupCP namedGroup, WCharP typeBuf, unsigned int bufChars)
	Gets the type of the Named Group. More...

StatusInt	mdlNamedGroup_setType (NamedGroupP namedGroup, WCharCP typeBuf)
	Sets the type of the Named Group. More...

StatusInt	mdlNamedGroup_getDescription (NamedGroupCP namedGroup, WCharP descrBuf, unsigned int bufChars)
	Gets the description of the Named Group. More...

StatusInt	mdlNamedGroup_setDescription (NamedGroupP namedGroup, WCharCP description)
	Sets the description of the Named Group. More...

int	mdlNamedGroup_getFlags (NamedGroupCP namedGroup)
	Gets the Named Group flags. More...

void	mdlNamedGroup_setFlags (NamedGroupP namedGroup, int groupFlags)
	Sets the Named Group flags. More...

int	mdlNamedGroup_getDefaultMemberFlags (NamedGroupCP namedGroup)
	Gets the Named Group default member flags. More...

void	mdlNamedGroup_setDefaultMemberFlags (NamedGroupP namedGroup, int defaultMemberFlags)
	Sets the Named Group default member flags. More...

ElementRefP	mdlNamedGroup_getElementRef (NamedGroupCP namedGroup)
	Gets the ElementRefP for the Named Group object. More...

StatusInt	mdlNamedGroup_writeToFile (NamedGroupP namedGroup, bool overwriteExisting)
	Writes the Named Group object to the file. More...

StatusInt	mdlNamedGroup_deleteFromFile (NamedGroupP namedGroup)
	Deletes the Named Group object from the file. More...

StatusInt	mdlNamedGroup_selectMembers (NamedGroupP namedGroup, DgnPlatform::MemberTraverseType traverseType, bool select)
	Selects or deselects members of the Named Group. More...

StatusInt	mdlNamedGroup_addToDisplaySet (NamedGroupCP namedGroup, DgnPlatform::MemberTraverseType traverseType)
	adds members of the Named Group to the display set. More...

StatusInt	mdlNamedGroup_removeFromDisplaySet (NamedGroupCP namedGroup, DgnPlatform::MemberTraverseType traverseType)
	remove members of the Named Group from the display set. More...

StatusInt	mdlNamedGroup_fromElementDescr (NamedGroupP *pNamedGroup, MSElementDescrCP pEd, DgnModelRefP sourceModelRef, DgnModelRefP rootModelRef)
	Creates a Named Group object from a Named Group element descriptor. More...

StatusInt	mdlNamedGroup_findByName (NamedGroupP pNamedGroup, MSElementDescrH ppED, UInt32 pFilePos, WCharCP groupName, DgnModelRefP modelRef)
	Finds a Named Group element and creates a Named Group object. More...

StatusInt	mdlNamedGroup_fromGroupElementRef (NamedGroupP pNamedGroup, MSElementDescrH ppED, UInt32 pFilePos, ElementRefP groupRef, DgnModelRefP sourceModelRef, DgnModelRefP rootModelRef)
	Creates a Named Group object from the ElementRefP of the Named Group element. More...

int	mdlNamedGroup_findGroupsContaining (ElementRefP *groupElementRefs, unsigned int maxGroups, ElementRefP memberElementRef)
	Gets the elementRefs of the Named Groups that contain a given elementRef. More...

StatusInt	mdlNamedGroup_traverseGroups (DgnModelRefP modelRef, PFNamedGroupTraverseFunc traverseFunc, CallbackArgP userArg)
	Traverses the Named Groups contained in a modelRef, calling a user-specified function for each group. More...

StatusInt	mdlNamedGroup_traverseMembers (NamedGroupCP namedGroup, PFNamedGroupMemberFunc traverseFunc, DgnPlatform::MemberTraverseType traverseType, CallbackArgP userArg, bool groupLock, bool startGroupOperation)
	Traverses the members of a Named Group, calling a user-specified function for each member. More...

StatusInt	mdlNamedGroup_traverseRelatedMembersForPath (DisplayPathCP memberDisplayPath, PFNamedGroupMemberFunc traverseFunc, DgnPlatform::MemberTraverseType traverseType, CallbackArgP userArg, bool groupLock, bool startGroupOperation)
	Traverses the members of Named Groups containing the root element of a displayPath. More...

StatusInt	mdlNamedGroup_traverseRelatedMembers (ElementRefP memberElementRef, DgnModelRefP modelRef, PFNamedGroupMemberFunc traverseFunc, DgnPlatform::MemberTraverseType traverseType, CallbackArgP userArg, bool groupLock, bool startGroupOperation)
	Traverses the members of Named Groups containing a specifed element. More...

StatusInt	mdlNamedGroup_prepareForGroupOperation (DgnModelRefP modelRef, DgnPlatform::MemberTraverseType traverseType)
	Clears the group operation flags for all potential group members. More...

void	mdlNamedGroup_doneGroupOperation ()
	Signals MicroStation that the group operation is complete. More...

bool	mdlNamedGroup_containsGroups (NamedGroupP namedGroup, ElementRefP groupElementRef)
	Returns whether a named group contains other named groups. More...

int	mdlNamedGroup_getContainedGroups (NamedGroupP namedGroup, ElementRefP *groupElementRefs, unsigned int maxGroups)
	Returns ElementRefs of the named groups that are members of a named group. More...

void	mdlNamedGroup_getUniqueName (WCharP nameBuf, int bufChars, WCharCP baseName, DgnModelRefP modelRef)
	Returns a name that can be used for a Named Group without duplicating that of any existing Named Group. More...

NamedGroupMemberP	mdlNamedGroup_findMemberByElementRef (NamedGroupP namedGroup, int *pMemberIndex, ElementRefP memberElementRef, DgnModelRefP memberModelRef)
	Returns the Named Group Member object for a member of a DgnPlatform::NamedGroup specified by its elementRef and modelRef. More...

NamedGroupMemberP	mdlNamedGroup_getMember (NamedGroupCP namedGroup, unsigned int index)
	Returns the Named Group Member object for a member of a DgnPlatform::NamedGroup specified by its index. More...

int	mdlNamedGroupMember_getFlags (NamedGroupMemberCP member)
	Returns the member flags for the specifed Named Group Member. More...

void	mdlNamedGroupMember_setFlags (NamedGroupMemberP member, int flags)
	Sets the member flags for the specifed Named Group Member. More...

Detailed Description

Macro Definition Documentation

#define NGFLAG_ALLOWDUPLICATES (1 << 0)

This file contains the public functions that manipulate Named Groups.

Named Groups

Named Groups are a mechanism for grouping graphical elements within a design. Named Groups are stored in the design as a complex element with a header of type 110 and components of type 111. When an element is added to a named group, a reference to the element is stored in the named group element, and the member element is not modified. An element can belong to any number of Named Groups. A Named Group can contain members that are other Named Groups, as long as there is no cycle in the membership hierarchy.

When an application manipulates Named Groups, it does so through the Named Group API. The Named Group API encapsulates all of the housekeeping required to create and process the named group elements in a Named Group object of type NamedGroupP. Applications can create new Named Groups by creating a Named Group object using mdlNamedGroup_create and writing it to the file using mdlNamedGroup_writeToFile. Members are added using mdlNamedGroup_addMember. A Named Group can be retrieved from the file using mdlNamedGroup_findByName, or all of the Named Groups within a model can be traversed using mdlNamedGroup_traverseGroups. The members of the Named Group can be traversed using mdlNamedGroup_traverseMembers. The Named Groups that an element belongs to can be efficiently determined by using mdlNamedGroup_findGroupsContaining.

Whenever a NamedGroupP object is returned to the caller, the caller is responsible for calling mdlNamedGroup_free to free it.

In MicroStation, Named Groups share some characteristics with numbered Graphic Groups, but they are considerably more flexible and powerful:

Elements can belong to multiple Named Groups but can belong to only one Graphic Group.
Adding an element to a Named Group does not modify the element, so locked elements can belong to Named Groups.
Named Groups can have other Named Groups as members, so a hierarchy can be established.
When a change is made to a member of a Named Group, the way that change is propagated to other Named Group members can be controlled in a flexible manner.

Change Propagation

Every member of a Named Group has a set of change propagation flags. When an element that is a member of a Named Group is modified by a MicroStation or application command that supports selection sets and graphic groups (usually by using mdlModify_elementMulti for element manipulation, with the doGroups argument set to true) other members of the graphic group might also be modified depending on the state of these change propagation flags. There are three such flags:


Flag	Description
Forward Change Propagation	Controls when changes to this member are propagated to other group members.
Backward Change Propagation	Controls when changes to other members in the group are propagated to this member.
Group Change Propagation	When the member belongs to multiple groups, controls how changes to this member are propagated to the other groups to which it belongs.

Each of these change propagation flags can have one of the following values:


Value	Description
NGMEMBERFLAG_GROUPLOCK	The corresponding propagation occurs only when Group Lock is on.
NGMEMBERFLAG_NEVER	The corresponding propagation never occurs.
NGMEMBERFLAG_ALWAYS	The corresponding propagation occurs for every manipulation that supports groups, regardless of the state of group lock.

When a command supporting groups is used to manipulate an element, the following algorithm is used to determine whether other members are manipulated:

 For each Named Group (namedGroup) the element (rootMember) belongs to:
    If, in namedGroup, rootMember has forward propagation set to NGMEMBERFLAG_ALWAYS
    or NGMEMBERFLAG_GROUPLOCK with Group Lock on, then
        For each otherMember of namedGroup
            If otherMember is another Named Group (otherGroup), then
                If rootMember has group propagation set to NGMEMBERFLAG_ALWAYS, or NGMEMBERFLAG_GROUPLOCK
                with Group Lock on, then propagate changes to otherGroup using this algorithm.
            Else If otherMember has backward propagation set to NGMEMBERFLAG_ALWAYS, or NGMEMBERFLAG_GROUPLOCK
            with Group lock on, then
                Manipulate otherMember.
            End If
        End For
    End If
End For

In MicroStation's user interface, there are two member types that predefine a combinations of propagation flags. An Active Member has its Change Propagation set to:

Forward Propagate (To Other Members) Group Lock
Backward Propagate (From Other Members) Group Lock
Group Propagate (To other Groups) Never

This combination of rules results in behavior just like graphic group members.

A Passive Member has its Change Propagation set to:

Forward Propagate (To Other Members) Never
Backward Propagate (From Other Members) Group Lock
Group Propagate (To other Groups) Never

Alternatively, a user can select the "Custom" member type and select any combination of propagation rules.

As an example of how change propagation works, consider the following diagram:

     1
4    2   5
     3

Suppose each of the numbers is an element. Suppose 1,2,3 are in a group called "Column" and "4,2,5" are in a group called Row. (Element 2 is in both Row and Column). Now suppose that in group "Column", Members 1 and 2 are set up as an Active Members. Suppose element 3 is a Passive Member.

Now suppose that in group "Row", Member 4 is an Active Member, but Member 5 has custom flags with

Forward Propagation: NGMEMBERFLAG_GROUPLOCK
Backward Propagation: NGMEMBERFLAG_NEVER
Group Propagation: NGMEMBERFLAG_NEVER,

and Member 2 has custom flags with

Forward Propagation: NGMEMBERFLAG_GROUPLOCK
Backward Propagation: NGMEMBERFLAG_GROUPLOCK
Group Propagation: NGMEMBERFLAG_GROUPLOCK,

With group lock on:

If you move Element 1: 1, 2, and 3 move. 1 propagates changes to 2 and 3, all of which accept propagation from other members.

If you move Element 2: 1, 2, 3, and 4 move. 2 propagates changes to 1 and 3 of group Column, all of whom accept propagation from other members. 1 propagates changes to 4 of group Row, but 5 does not move because it does not accept change propagation from other members.

If you move Element 3: Only 3 moves because it does not propagate changes to other members of the Column group.

If you move Element 4: 1, 2, 3, and 4 move. 4 propagates changes to 2, which as a member of group Row, propagates changes to group Column, which moves 1 and 3. Element 5 does not accept changes propagating from other members of its group, so it does not move..

If you move Element 5: 1, 2, 3, 4, and 5 move. 5 propagates changes to 4, which accepts propagation. It also propagates changes to 2, which in turn propagates changes to the other group it belongs to, moving 1 and 3.

If you set up the same test, but substitute NGMEMBERFLAG_ALWAYS wherever NGMEMBERFLAG_GROUPLOCK appears, then the same move actions happen even if Group Lock is off. Named Group member traversal types.

+------------—+------------—+------------—+------------—+------------—+---—

Function Documentation

StatusInt mdlNamedGroup_addMember	(	NamedGroupP	namedGroup,
		DgnPlatform::ElementId	elementId,
		DgnModelRefP	modelRef,
		int	memberFlags
	)

Adds a member to a Named Group.

Parameters

[in] namedGroup Named Group

[in] elementId DgnPlatform::ElementId of the element to add to the named group.

[in] modelRef modelRef that elementId is in. It must be the same as the modelRef passed to the mdlModelRef_create function, or a directly attached reference of that modelRef.

[in]

memberFlags

member flags, ORed together from the following table.


Value	Description
NGMEMBERFLAG_FORWARDPROPAGATENEVER	Do not propagate changes to other group members.
NGMEMBERFLAG_FORWARDPROPAGATEGROUPLOCK	Propagate changes to other group members when group lock is on.
NGMEMBERFLAG_FORWARDPROPAGATEALWAYS	Propagate changes to other group members regardless of group lock setting.
NGMEMBERFLAG_BACKWARDPROPAGATENEVER	Do not propagate changes from other group members to this member.
NGMEMBERFLAG_BACKWARDPROPAGATEGROUPLOCK	Propagate changes from other group members to this member when group lock is on.
NGMEMBERFLAG_BACKWARDPROPAGATEALWAYS	Propagate changes from other group members to this member regardless of group lock setting.
NGMEMBERFLAG_GROUPPROPAGATENEVER	Do not propagate changes to other groups to which this members belongs.
NGMEMBERFLAG_GROUPPROPAGATEGROUPLOCK	Propagate changes to other groups to which this member belongs when group lock is on.
NGMEMBERFLAG_GROUPPROPAGATEALWAYS	Propagate changes to other groups to which this member belongs regardless of group lock setting.

Returns

SUCCESS if the member is added, or one of the following error codes.


Value	Description
MDLERR_BADARG	the namedGroup is NULL.
MDLERR_CLOSEDGROUP	the namedGroup has NGFLAG_CLOSEDGROUP set.
MDLERR_FARREFERENCE	The element is not in the modelRef of the DgnPlatform::NamedGroup, and the named group does not have NGFLAG_ALLOWFARREFS set.
MDLERR_DUPLICATEMEMBER	The specified element is already in the named group, and the named group does not have NGFLAG_ALLOWDUPLICATES set.
MDLERR_IDNOTFOUND	Either the elementId or modelRef is invalid.

Remarks: The prospective named group member must already be written to the file before it can be added.

StatusInt mdlNamedGroup_addToDisplaySet	(	NamedGroupCP	namedGroup,
		DgnPlatform::MemberTraverseType	traverseType
	)

adds members of the Named Group to the display set.

Parameters

[in]	namedGroup	Named Group
[in]	traverseType	The type of traversal used to find the members to add to the display set. See mdlNamedGroup_traverseMembers.

Returns: SUCCESS if the members are added, or MDLERR_BADARG if namedGroup is NULL.

bool mdlNamedGroup_containsGroups	(	NamedGroupP	namedGroup,
		ElementRefP	groupElementRef
	)

Returns whether a named group contains other named groups.

Parameters

[in]	namedGroup	Named Group. If NULL, use groupElementRef to find the group.
[in]	groupElementRef	ElementRefP of a Named Group element. Must be non-NULL if namedGroup is NULL.

Returns: true if the Named Group contains other Named Groups.

Remarks: The function can be used to determine whether a Named Group object has named group members, or whether the named group represented by groupElementRef contains members. The latter case allows the caller to avoid the overhead of creating a Named Group object if the only reason for doing so would be to find out whether it contained other named groups.

StatusInt mdlNamedGroup_create	(	NamedGroupP *	pNamedGroup,
		WCharCP	groupName,
		WCharCP	groupDescr,
		int	groupFlags,
		DgnModelRefP	modelRef
	)

Creates a new Named Group object.

Parameters

[out] pNamedGroup newly created Named Group.

[in] groupName name of the named group. This must be unique within the model, although it is not checked until an attempt is made to write namedGroup to the model. A unique name can be generated using mdlNamedGroup_getUniqueName.

[in] groupDescr description of the named group.

[in]

groupFlags

named group flags, ORed together from the following table:


Value	Description
NGFLAG_ALLOWDUPLICATES	Allow duplicate members. This is not currently supported and should not be set.
NGFLAG_EXCLUSIVEMEMBERS	Do not allow any member that is a members of any other Named Group. This is not currently supported and should not be set.
NGFLAG_ALLOWFARREFS	Allow references to members in directly attached references. Members from nested references are not currently supported.
NGFLAG_CLOSEDGROUP	Do not allow members to be added or deleted.
NGFLAG_SELECTMEMBERS	When any member of the named group is selected using MicroStation's Select tool, select all members.
NGFLAG_ANONYMOUS	Do not show this named group in the Named Group Manager dialog box.

[in] modelRef the modelRef that the DgnPlatform::NamedGroup will be written to.

Returns

SUCCESS if the Named Group object can be created, or one of the following error codes.


Value	Description
MDLERR_BADARG	namedGroup is NULL, or groupName is NULL, empty or longer than MAX_NAMEDGROUP_NAME_LENGTH characters.
MDLERR_BADMODELREF	The modelRef is invalid.

StatusInt mdlNamedGroup_deleteFromFile ( NamedGroupP namedGroup )

Deletes the Named Group object from the file.

Parameters

[in] namedGroup Named Group

Returns

SUCCESS if the Named Group object can be deleted from the file, or one of the following error codes:


Value	Description
MDLERR_BADARG	namedGroup is NULL
MDLERR_FILEREADONLY	The modelRef specified when the named group was created or located is read only.
MDLERR_WRITEINHIBIT	An application is preventing data from being written to the file.
MDLERR_NOTLOADED	The Named Group object was created, but never been written to the file.
MDLERR_ELEMENTNOTFOUND	The Named Group element corresponding to the object can not be found in the file.

void mdlNamedGroup_doneGroupOperation ( )

Signals MicroStation that the group operation is complete.

Remarks: When operating on elements that might propagate changes to Named Groups, it is important to avoid operating on any element more than once. To avoid that, a flag is kept on each elementRef indicating that the element has been visited during a particular modification operation. Before performing a modification, mdlNamedGroup_prepareForGroupOperation can be called to clear the group operation flags.

See also: mdlNamedGroup_prepareForGroupOperation

StatusInt mdlNamedGroup_findByName	(	NamedGroupP *	pNamedGroup,
		MSElementDescrH	ppED,
		UInt32 *	pFilePos,
		WCharCP	groupName,
		DgnModelRefP	modelRef
	)

Finds a Named Group element and creates a Named Group object.

Parameters

[out]	pNamedGroup	Named Group object. Pass NULL if the Named Group object is not needed. If the Named Group object is returned, the caller is responsible for freeing it.
[out]	ppED	Element descriptor containing Named Group. Pass NULL if the element descriptor is not needed. If the element descriptor is returned, the caller is responsible for freeing it.
[out]	pFilePos	file position of element descriptor. Pass NULL if the file position is not needed.
[in]	groupName	name of the group.
[in]	modelRef	the modelRef containing the named group.

Returns: SUCCESS if the Named Group is found, MDLERR_ELEMENTNOTFOUND otherwise.

int mdlNamedGroup_findGroupsContaining	(	ElementRefP *	groupElementRefs,
		unsigned int	maxGroups,
		ElementRefP	memberElementRef
	)

Gets the elementRefs of the Named Groups that contain a given elementRef.

Parameters

[out]	groupElementRefs	Pointer to a buffer that holds at least maxGroups elementRefs. If this parameter is NULL, no elementRefs are returned, but the function still returns the count of groups. This can be used to allocate memory for groupElementRefs.
[in]	maxGroups	Number of elementRefs that groupElementRefs can hold. Pass 0 if groupElementRefs is NULL.
[in]	memberElementRef	the elementRef for which the containing groups are required.

Returns: the number of groups that contain the memberElementRef.

NamedGroupMemberP mdlNamedGroup_findMemberByElementRef	(	NamedGroupP	namedGroup,
		int *	pMemberIndex,
		ElementRefP	memberElementRef,
		DgnModelRefP	memberModelRef
	)

Returns the Named Group Member object for a member of a DgnPlatform::NamedGroup specified by its elementRef and modelRef.

Parameters

[in]	namedGroup	Named Group
[out]	pMemberIndex	the index of the member. Pass NULL if this is not of interest.
[in]	memberElementRef	the elementRef of the member.
[in]	memberModelRef	the modelRef of the member.

Returns: NULL if the namedGroup does not contain memberElementRef, otherwise the Named Group Member object.

StatusInt mdlNamedGroup_free ( NamedGroupP * pNamedGroup )

Frees a Named Group object.

Parameters

[in,out] pNamedGroup a pointer to the DgnPlatform::NamedGroup object to free. On return, the pointer value is set to NULL.

Returns: SUCCESS if Named Group object is freed, or MDLERR_BADARG if pNamedGroup is NULL or points to NULL.

StatusInt mdlNamedGroup_fromElementDescr	(	NamedGroupP *	pNamedGroup,
		MSElementDescrCP	pEd,
		DgnModelRefP	sourceModelRef,
		DgnModelRefP	rootModelRef
	)

Creates a Named Group object from a Named Group element descriptor.

Parameters

[out]	pNamedGroup	Named Group object
[in]	pEd	Element descriptor containing Named Group.
[in]	sourceModelRef	the modelRef that the element descriptor came from.
[in]	rootModelRef	the modelRef that the elements are to be relative to. Usually the same as sourceModelRef.

Returns

SUCCESS if the Named Group object can be created from the element descriptor, or one of the following error codes:


Value	Description
MDLERR_BADARG	either edP or pNamedGroup is NULL
MDLERR_BADTYPE	edP does not contain a Named Group element.

StatusInt mdlNamedGroup_fromGroupElementRef	(	NamedGroupP *	pNamedGroup,
		MSElementDescrH	ppED,
		UInt32 *	pFilePos,
		ElementRefP	groupRef,
		DgnModelRefP	sourceModelRef,
		DgnModelRefP	rootModelRef
	)

Creates a Named Group object from the ElementRefP of the Named Group element.

Parameters

[out]	pNamedGroup	Named Group object. Pass NULL if the Named Group object is not needed. If the Named Group object is returned, the caller is responsible for freeing it.
[out]	ppED	Element descriptor containing Named Group. Pass NULL if the element descriptor is not needed. If the element descriptor is returned, the caller is responsible for freeing it.
[out]	pFilePos	file position of element descriptor. Pass NULL if the file position is not needed.
[in]	groupRef	the ElementRefP of the named group element
[in]	sourceModelRef	the modelRef that groupRef came from.
[in]	rootModelRef	the modelRef that the elements are to be relative to. Usually the same as sourceModelRef.

Returns: SUCCESS if the Named Group is found, MDLERR_ELEMENTNOTFOUND otherwise.

int mdlNamedGroup_getContainedGroups	(	NamedGroupP	namedGroup,
		ElementRefP *	groupElementRefs,
		unsigned int	maxGroups
	)

Returns ElementRefs of the named groups that are members of a named group.

Parameters

[in]	namedGroup	Named Group.
[out]	groupElementRefs	Pointer to a buffer that holds at least maxGroups elementRefs. If this parameter is NULL, no elementRefs are returned, but the function still returns the count of groups. This can be used to allocate memory for groupElementRefs.
[in]	maxGroups	Number of elementRefs that groupElementRefs can hold. Pass 0 if groupElementRefs is NULL.

Returns: the number of Named Groups that are members of namedGroup

int mdlNamedGroup_getDefaultMemberFlags ( NamedGroupCP namedGroup )

Gets the Named Group default member flags.

Parameters

[in] namedGroup Named Group

Returns: the value of the Named Group default member flags. The default member flags are used to set up the member propagation flags when a group is chosen in the tool settings for the Group Add command. See mdlNamedGroup_addMember.

StatusInt mdlNamedGroup_getDescription	(	NamedGroupCP	namedGroup,
		WCharP	descrBuf,
		unsigned int	bufChars
	)

Gets the description of the Named Group.

Parameters

[in]	namedGroup	Named Group
[out]	descrBuf	Named Group description
[in]	bufChars	size of descrBuf, in MSWChars.

Returns: SUCCESS if the description is returned, or MDLERR_BADARG if namedGroup is NULL.

ElementRefP mdlNamedGroup_getElementRef ( NamedGroupCP namedGroup )

Gets the ElementRefP for the Named Group object.

Parameters

[in] namedGroup Named Group

Returns: the ElementRefP for the Named Group object. If namedGroup has just been created using mdlNamedGroup_create and has not yet been written to the file, then its ElementRefP is NULL. In all other cases, the ElementRefP is available.

int mdlNamedGroup_getFlags ( NamedGroupCP namedGroup )

Gets the Named Group flags.

Parameters

[in] namedGroup Named Group

Returns: the value of the Named Group flags word. See mdlNamedGroup_create.

NamedGroupMemberP mdlNamedGroup_getMember	(	NamedGroupCP	namedGroup,
		unsigned int	index
	)

Returns the Named Group Member object for a member of a DgnPlatform::NamedGroup specified by its index.

Parameters

[in]	namedGroup	Named Group
[in]	index	the index of the desired member.

Returns: NULL if the namedGroup does not contain memberElementRef, otherwise the Named Group Member object.

Remarks: The Named Group Member object returned is managed by the Named Group object. It is not freed by the caller. The Named Group Member object is not valid after the named group is freed, nor after members are added or removed from the group.

StatusInt mdlNamedGroup_getMemberCount	(	NamedGroupCP	namedGroup,
		int *	graphicMembers,
		int *	groupMembers
	)

Gets the count of graphics members and Named Group members in a Named Group.

Parameters

[in]	namedGroup	Named Group
[out]	graphicMembers	number of graphic elements that belong to the Named Group. The caller can pass NULL if this count is not of interest.
[out]	groupMembers	number of other Named Groups that belong to the Named Group. The caller can pass NULL if this count is not of interest.

Returns: SUCCESS if the counts are returned, or MDLERR_BADARG if namedGroup is NULL.

StatusInt mdlNamedGroup_getName	(	NamedGroupCP	namedGroup,
		WCharP	nameBuf,
		unsigned int	bufChars
	)

Gets the name of the Named Group.

Parameters

[in]	namedGroup	Named Group
[out]	nameBuf	Named Group name
[in]	bufChars	size of nameBuf, in MSWChars.

Returns: SUCCESS if the name is returned, or MDLERR_BADARG if namedGroup is NULL.

StatusInt mdlNamedGroup_getType	(	NamedGroupCP	namedGroup,
		WCharP	typeBuf,
		unsigned int	bufChars
	)

Gets the type of the Named Group.

Parameters

[in]	namedGroup	Named Group
[out]	typeBuf	Named Group type
[in]	bufChars	size of typeBuf, in MSWChars.

Returns: SUCCESS if the name is returned, or MDLERR_BADARG if namedGroup is NULL.

Remarks: The named group type does not affect its operation. Its primary use is to give the user a way to sort named groups in the dialog box.

void mdlNamedGroup_getUniqueName	(	WCharP	nameBuf,
		int	bufChars,
		WCharCP	baseName,
		DgnModelRefP	modelRef
	)

Returns a name that can be used for a Named Group without duplicating that of any existing Named Group.

Parameters

[out]	nameBuf	Named Group name
[in]	bufChars	size of nameBuf, in MSWChars.
[in]	baseName	a name to use as the base. If NULL, the default of "Group " is used for english versions.
[in]	modelRef	modelRef where the named group will be written.

StatusInt mdlNamedGroup_prepareForGroupOperation	(	DgnModelRefP	modelRef,
		DgnPlatform::MemberTraverseType	traverseType
	)

Clears the group operation flags for all potential group members.

Parameters

[in]	modelRef	the modelRef containing the root member or the named group that will be traversed.
[in]	traverseType	The type of traversal used to determine the scope of potential members. If traverseType is MemberTraverseType::Copy, all reference childRefs of modelRef must have the group Operation Flags of every element cleared. Otherwise only the elements in modelRef need to have the group Operation Flags cleared.

Returns: SUCCESS, or MDLERR_GROUPOPINPROGRESS if an attempt is made to prepare for Group Operation while another group operation is already in progress.

Remarks: When operating on elements that might propagate changes to Named Groups, it is important to avoid operating on any element more than once. To avoid that, a flag is kept on each elementRef indicating that the element has been visited during a particular modification operation. Before performing a modification, mdlNamedGroup_prepareForGroupOperation can be called to clear the group operation flags.; If (and only if) this function returns SUCCESS, make sure you call mdlNamedGroup_doneGroupOperation when you are done the group operation. Otherwise other group operations will be blocked and that will cause MicroStation to behave erratically.

See also: mdlNamedGroup_traverseRelatedMembersForPath mdlNamedGroup_traverseMembers mdlNamedGroup_traverseRelatedMembers mdlNamedGroup_doneGroupOperation

StatusInt mdlNamedGroup_removeFromDisplaySet	(	NamedGroupCP	namedGroup,
		DgnPlatform::MemberTraverseType	traverseType
	)

remove members of the Named Group from the display set.

Parameters

[in]	namedGroup	Named Group
[in]	traverseType	The type of traversal used to find the members to remove from the display set. See mdlNamedGroup_traverseMembers.

Returns: SUCCESS if the members are removed, or MDLERR_BADARG if namedGroup is NULL.

StatusInt mdlNamedGroup_removeMember	(	NamedGroupP	namedGroup,
		unsigned int	index
	)

Removes a member from a Named Group.

Parameters

[in]	namedGroup	Named Group
[in]	index	the index of the member to remove.

Returns

SUCCESS if the member is added, or one of the following error codes.


Value	Description
MDLERR_BADARG	the namedGroup is NULL.
MDLERR_CLOSEDGROUP	the namedGroup has NGFLAG_CLOSEDGROUP set.

See also: mdlNamedGroup_traverseMembers

StatusInt mdlNamedGroup_selectMembers	(	NamedGroupP	namedGroup,
		DgnPlatform::MemberTraverseType	traverseType,
		bool	select
	)

Selects or deselects members of the Named Group.

Parameters

[in]	namedGroup	Named Group
[in]	traverseType	The type of traversal used to find the members to select. See mdlNamedGroup_traverseMembers.
[in]	select	true to select the members, false to remove the members from the current selection.

Returns: SUCCESS if the members are selected (or deselected), or MDLERR_BADARG if namedGroup is NULL.

void mdlNamedGroup_setDefaultMemberFlags	(	NamedGroupP	namedGroup,
		int	defaultMemberFlags
	)

Sets the Named Group default member flags.

Parameters

[in]	namedGroup	Named Group
[in]	defaultMemberFlags	the value of the Named Group default member flags. The default member flags are used to set up the member propagation flags when a group is chosen in the tool settings for the Group Add command.

StatusInt mdlNamedGroup_setDescription	(	NamedGroupP	namedGroup,
		WCharCP	description
	)

Sets the description of the Named Group.

Parameters

[in]	namedGroup	Named Group
[in]	description	Named Group description

Returns: SUCCESS if the description is set, or MDLERR_TOOLARGE if the length of nameBuf is greater than MAX_NAMEDGROUP_DESCR_LENGTH characters.

void mdlNamedGroup_setFlags	(	NamedGroupP	namedGroup,
		int	groupFlags
	)

Sets the Named Group flags.

Parameters

[in]	namedGroup	Named Group
[in]	groupFlags	The flags to set. See mdlNamedGroup_create.

StatusInt mdlNamedGroup_setName	(	NamedGroupP	namedGroup,
		WCharCP	nameBuf
	)

Sets the name of the Named Group.

Parameters

[in]	namedGroup	Named Group
[in]	nameBuf	Named Group name

Returns: SUCCESS if the name is set, or MDLERR_TOOLARGE if the length of nameBuf is greater than MAX_NAMEDGROUP_NAME_LENGTH characters.

StatusInt mdlNamedGroup_setType	(	NamedGroupP	namedGroup,
		WCharCP	typeBuf
	)

Sets the type of the Named Group.

Parameters

[in]	namedGroup	Named Group
[in]	typeBuf	Named Group type

Returns: SUCCESS if the type is set, or MDLERR_TOOLARGE if the length of typeBuf is greater than MAX_NAMEDGROUP_CATEGORY_LENGTH characters.

Remarks: The named group type does not affect its operation. Its primary use is to give the user a way to sort named groups in the dialog box.

StatusInt mdlNamedGroup_traverseGroups	(	DgnModelRefP	modelRef,
		PFNamedGroupTraverseFunc	traverseFunc,
		CallbackArgP	userArg
	)

Traverses the Named Groups contained in a modelRef, calling a user-specified function for each group.

Parameters

[in]	modelRef	The modelRef to scan for named groups.
[in]	traverseFunc	the function to call for each named group.
[in]	userArg	argument that is passed to each named group.

Returns: SUCCESS, or the return value from traverseFunc if nonzero.

Remarks: The traversal function receives the following arguments:
StatusInt (*PFNamedGroupTraverseFunc)(MSElementDescrP namedGroupEdP, CallbackArgP userArg);; The traversal is stopped if the traverseFunc returns a value other than SUCCESS (0).

StatusInt mdlNamedGroup_traverseMembers	(	NamedGroupCP	namedGroup,
		PFNamedGroupMemberFunc	traverseFunc,
		DgnPlatform::MemberTraverseType	traverseType,
		CallbackArgP	userArg,
		bool	groupLock,
		bool	startGroupOperation
	)

Traverses the members of a Named Group, calling a user-specified function for each member.

Parameters

[in] namedGroup Named Group

[in] traverseFunc the function to call for each member.

[in]

traverseType

The type of traversal used to determine the members for which traverseFunc is called. Valid values are:


Traverse Type	Description
MemberTraverseType::Simple	Calls traverseFunc for directly contained members and members that are in contained Named Groups (recursively).
MemberTraverseType::Manipulate	Calls traverseFunc for members according to the member propagation flags.
MemberTraverseType::Copy	Like Traverse_Manipulate, except it also calls traverseFunc far references.
MemberTraverseType::Enumerate	Calls traverseFunc for contained Named Groups as elements rather than traversing them.
MemberTraverseType::DirectMembers	Calls traverseFunc for directly contained members only, ignoring contained Named Groups.

[in] userArg argument that is passed to each named group.

[in] groupLock set to true if group lock should be considered to be ON. Usually tcb->fbfdcn.gglk is passed.

[in] startGroupOperation set to true if the groupOperationFlags should be cleared before this traversal.

Returns: SUCCESS, or the return value from traverseFunc if nonzero.

Remarks: The traversal function receives the following arguments:
StatusInt (*PFNamedGroupMemberFunc)(DisplayPathCP displayPath, NamedGroupP namedGroup, int memberIndex, void *userArg);; The traversal is stopped if the traverseFunc returns a value other than SUCCESS (0).; When operating on elements that might propagate changes to Named Groups, it is important to avoid operating on any element more than once. To avoid that, a flag is kept on each elementRef indicating that the element has been visited during a particular modification operation. Before performing a modification, mdlNamedGroup_prepareForGroupOperation can be called to clear the group operation flags, or the startGroupOperation argument can be set true in the call.

See also: mdlNamedGroup_traverseRelatedMembersForPath mdlNamedGroup_traverseRelatedMembers

StatusInt mdlNamedGroup_traverseRelatedMembers	(	ElementRefP	memberElementRef,
		DgnModelRefP	modelRef,
		PFNamedGroupMemberFunc	traverseFunc,
		DgnPlatform::MemberTraverseType	traverseType,
		CallbackArgP	userArg,
		bool	groupLock,
		bool	startGroupOperation
	)

Traverses the members of Named Groups containing a specifed element.

Parameters

[in]	memberElementRef	the element whose containing groups should be traversed.
[in]	modelRef	the modelRef containing memberElementRef
[in]	traverseFunc	the function to call for each member.
[in]	traverseType	The type of traversal used to find the members to select. See mdlNamedGroup_traverseMembers.
[in]	userArg	argument that is passed to each named group.
[in]	groupLock	set to true if group lock should be considered to be ON. Usually tcb->fbfdcn.gglk is passed.
[in]	startGroupOperation	set to true if the groupOperationFlags should be cleared before this traversal.

Returns: SUCCESS, or the return value from traverseFunc if nonzero.

Remarks: The traversal function receives the following arguments:
StatusInt (*NamedGroupMemberFunc)(DisplayPathCP displayPath, NamedGroupP namedGroup, int memberIndex, void *userArg);; The traversal is stopped if the traverseFunc returns a value other than SUCCESS (0).; When operating on elements that might propagate changes to Named Groups, it is important to avoid operating on any element more than once. To avoid that, a flag is kept on each elementRef indicating that the element has been visited during a particular modification operation. Before performing a modification, mdlNamedGroup_prepareForGroupOperation can be called to clear the group operation flags, or the startGroupOperation argument can be set true in the call.

See also: mdlNamedGroup_traverseRelatedMembersForPath mdlNamedGroup_traverseMembers

StatusInt mdlNamedGroup_traverseRelatedMembersForPath	(	DisplayPathCP	memberDisplayPath,
		PFNamedGroupMemberFunc	traverseFunc,
		DgnPlatform::MemberTraverseType	traverseType,
		CallbackArgP	userArg,
		bool	groupLock,
		bool	startGroupOperation
	)

Traverses the members of Named Groups containing the root element of a displayPath.

Parameters

[in]	memberDisplayPath	the display path of the element whose containing groups should be traversed.
[in]	traverseFunc	the function to call for each member.
[in]	traverseType	The type of traversal used to find the members to select. See mdlNamedGroup_traverseMembers.
[in]	userArg	argument that is passed to each named group.
[in]	groupLock	set to true if group lock should be considered to be ON. Usually tcb->fbfdcn.gglk is passed.
[in]	startGroupOperation	set to true if the groupOperationFlags should be cleared before this traversal.

Returns: SUCCESS, or the return value from traverseFunc if nonzero.

Remarks: The traversal function receives the following arguments:
StatusInt (*NamedGroupMemberFunc)(DisplayPathCP displayPath, NamedGroupP namedGroup, int memberIndex, void *userArg);; The traversal is stopped if the traverseFunc returns a value other than SUCCESS (0).; When operating on elements that might propagate changes to Named Groups, it is important to avoid operating on any element more than once. To avoid that, a flag is kept on each elementRef indicating that the element has been visited during a particular modification operation. Before performing a modification, mdlNamedGroup_prepareForGroupOperation can be called to clear the group operation flags, or the startGroupOperation argument can be set true in the call.

See also: mdlNamedGroup_traverseRelatedMembers mdlNamedGroup_traverseMembers

StatusInt mdlNamedGroup_writeToFile	(	NamedGroupP	namedGroup,
		bool	overwriteExisting
	)

Writes the Named Group object to the file.

Parameters

[in]	namedGroup	Named Group
[in]	overwriteExisting	if true, overwrites existing Named Group of the same name.

Returns

SUCCESS if the Named Group object can be written to the file, or one of the following error codes:


Value	Description
MDLERR_BADARG	namedGroup is NULL
MDLERR_FILEREADONLY	The modelRef specified when the named group was created or located is read only.
MDLERR_ALREADYEXISTS	There is already a named group with the same name, and overwriteExisting is false.
MDLERR_WRITEINHIBIT	An application is preventing data from being written to the file.

int mdlNamedGroupMember_getFlags ( NamedGroupMemberCP member )

Returns the member flags for the specifed Named Group Member.

Parameters

[in] member Named Group Member

Returns: the flags for the named group member. The flags are OR'ed combinations of the NGMEMBERFLAG_xxx values as described in the section header.

See also: mdlNamedGroup_setFlags

void mdlNamedGroupMember_setFlags	(	NamedGroupMemberP	member,
		int	flags
	)

Sets the member flags for the specifed Named Group Member.

Parameters

[in]	member	Named Group Member
[in]	flags	the flags for the named group member. The flags are OR'ed combinations of the NGMEMBERFLAG_xxx values as described in the section header.

See also: mdlNamedGroup_getFlags

Macros

Functions

Detailed Description

Macro Definition Documentation

Named Groups

Function Documentation