Named Groups are a mechanism for grouping graphical elements within a design. More...

Modules
	Named Group C Api

Classes
struct	NamedGroupCollection
	A NamedGroupCollection provides a mechanism for finding and iterating the NamedGroups associated with a DgnModel. More...

struct	NamedGroupMemberFlags
	The Flags stored for each member of a NamedGroup. More...

struct	NamedGroupMember
	A NamedGroupMember is returned for each member of a NamedGroup that is returned by the NamedGroup "Traverse" methods. More...

struct	NamedGroupFlags
	The NamedGroupFlags structure holds settings for the NamedGroup as a whole. More...

struct	INamedGroupMemberVisitor
	The interface that is implemented by classes that participate in NamedGroup member traversal. More...

struct	NamedGroup

Typedefs
typedef RefCountedPtr< NamedGroup >	NamedGroupPtr
	A Reference Counted pointer to a NamedGroup. More...

typedef RefCountedPtr < NamedGroupCollection >	NamedGroupCollectionPtr
	A Reference Counted pointer to a NamedGroupCollection. More...

Enumerations
enum	NamedGroupStatus { NG_Success = 0, NG_ClosedGroup = NAMED_GROUP_ERROR_BASE + 1, NG_FarReferenceDisallowed = NAMED_GROUP_ERROR_BASE + 2, NG_DuplicateMember = NAMED_GROUP_ERROR_BASE + 3, NG_BadMember = NAMED_GROUP_ERROR_BASE + 4, NG_NameTooLong = NAMED_GROUP_ERROR_BASE + 5, NG_NameTooShort = NAMED_GROUP_ERROR_BASE + 6, NG_DescriptionTooLong = NAMED_GROUP_ERROR_BASE + 7, NG_TypeTooLong = NAMED_GROUP_ERROR_BASE + 8, NG_CircularDependency = NAMED_GROUP_ERROR_BASE + 9, NG_CantCreateSubgroup = NAMED_GROUP_ERROR_BASE + 10, NG_BadArg = NAMED_GROUP_ERROR_BASE + 11, NG_NotNamedGroupElement = NAMED_GROUP_ERROR_BASE + 12, NG_FileReadOnly = NAMED_GROUP_ERROR_BASE + 13, NG_ExistsNotOverwriting = NAMED_GROUP_ERROR_BASE + 14, NG_NameNotUnique = NAMED_GROUP_ERROR_BASE + 15, NG_NotFound = NAMED_GROUP_ERROR_BASE + 16, NG_NotPersistent = NAMED_GROUP_ERROR_BASE + 17, NG_OperationInProgress = NAMED_GROUP_ERROR_BASE + 18, NG_IsFarReference = NAMED_GROUP_ERROR_BASE + 19 }
	Possible status values returned from NamedGroup and NamedGroupCollection methods. More...

enum	MemberTraverseStatus { Continue = 0, SkipElement = 1, SkipGroup = 2, Abort = 3 }
	The return value from the INamedGroupMemberVisitor::VisitMember method. More...

Detailed Description

Named Groups are a mechanism for grouping graphical elements within a design.

When an element is added to a named group, a reference to that element is stored in the NamedGroup object, with no modification to the member element. 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.

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 command that supports selection sets and graphic groups (using the ElementAgenda API with doGroups true), other members of the Named 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 from NameGroup::FlagValues:


Value	Description
NG_FLAG_GroupLock	The corresponding propagation occurs only when Group Lock is on.
NG_FLAG_Never	The corresponding propagation never occurs.
NG_FLAG_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 NamedGroup (namedGroup) the element (rootMember) belongs to:
     {
     If, in namedGroup, rootMember has forward propagation set to NG_FLAG_Always or NG_FLAG_GroupLock with Group Lock on
        {
        For each otherMember of namedGroup
            {
            If otherMember is another Named Group (otherGroup)
                {
                If rootMember has group propagation set to NG_FLAG_Always, or NG_FLAG_GroupLock with Group Lock on
                    {
                    propagate changes to otherGroup using this algorithm.
                    }
                }
             Else If otherMember has backward propagation set to NG_FLAG_Always, or NG_FLAG_GroupLock with Group lock on
                {
                Manipulate otherMember.
                }
            }
        }
     }

In MicroStation's user interface, there are two member types that predefine 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: NG_FLAG_GroupLock
     Backward Propagation: NG_FLAG_Never
     Group Propagation: NG_FLAG_Never,

and Member 2 has custom flags with

     Forward Propagation: NG_FLAG_GroupLock
     Backward Propagation: NG_FLAG_GroupLock
     Group Propagation: NG_FLAG_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 NG_FLAG_Always wherever NG_FLAG_GroupLock appears, then the same move actions happen even if Group Lock is off.

+===============+===============+===============+===============+===============+======

Typedef Documentation

typedef RefCountedPtr<NamedGroupCollection> NamedGroupCollectionPtr

A Reference Counted pointer to a NamedGroupCollection.

typedef RefCountedPtr<NamedGroup> NamedGroupPtr

A Reference Counted pointer to a NamedGroup.

Enumeration Type Documentation

enum MemberTraverseStatus

strong

The return value from the INamedGroupMemberVisitor::VisitMember method.

Enumerator
Continue	Continue normally.
SkipElement	Skip the current element (do not propagate from it to other members of groups it belongs to).
SkipGroup	Skip the rest of the elements within the current group.
Abort	Abort the traversal.

enum NamedGroupStatus

Possible status values returned from NamedGroup and NamedGroupCollection methods.

Enumerator
NG_Success	The method succeeded.
NG_ClosedGroup	Attempt to add or delete a member from a closed group.
NG_FarReferenceDisallowed	Attempt to add a Far Reference to a NamedGroup for which flags.m_allowFarReferences is false.
NG_DuplicateMember	Attempt to add a duplicate member.
NG_BadMember	Attempt to add an element that has been deleted or hasn't been added to the model yet.
NG_NameTooLong	The name specified is too long.
NG_NameTooShort	The name specified is too short.
NG_DescriptionTooLong	The description specified is too long.
NG_TypeTooLong	The type specified is too long.
NG_CircularDependency	Attempt to add a group that of which this NamedGroup is a descendant.
NG_CantCreateSubgroup	Encountered a defective NamedGroup member while reconstituing a NamedGroup from persistent storage.
NG_BadArg	A NULL argument passed that cannot be NULL.
NG_NotNamedGroupElement	The Element passed in does not represent the persistent store of a NamedGroup.
NG_FileReadOnly	The NamedGroup cannot be written because the file is readonly.
NG_ExistsNotOverwriting	Attempt to overwrite a NamedGroup that already exists.
NG_NameNotUnique	There is already a NamedGroup with the name supplied.
NG_NotFound	The NamedGroup was not found.
NG_NotPersistent	The NamedGroup has never been written to the DgnFile.
NG_OperationInProgress	There is a NamedGroup operation already in progress.
NG_IsFarReference	Unexpectedly encountered Far Reference.

Modules

Classes

Typedefs

Enumerations

Detailed Description

Typedef Documentation

Enumeration Type Documentation