Creating a Group and How to Fish

Here is a question from Henry Medina on creating groups that might be of interest to a wider audience:

Question: I have listened to your TV recording several times and was also able to run the Labs project. Your Labs code shows how to draw beams, columns and braces, but not a group. How could I create a new instance of an existing group, set its insertion base point, location, rotation angle, and mirror it? Please show the commands in C#.

Answer: When addressing a question like this, there are a certain number of steps that I recommend always going through:

Before looking at these, here are some basics about element creation. Everything that can be created through the Revit API is handled by the Application and Document classes in the Autodesk.Revit.Creation namespace. Since a group is a database resident object, it is generated by the creation document. The creation application is used for objects that a memory resident only, such as geometry objects.

Now, looking at the creation document and its methods in RevitAPI.chm or in the Visual Studio object browser, it is easy to find the NewGroup method. It takes an ElementSet as an argument and returns a newly created Group instance. It creates a new type of group and returns a new instance of it containing the specified elements. Initially the group will have a generic name, such as Group 1. This can be modified by changing the name of the group type using something like newGroup.GroupType.Name = newName. So it actually creates both a GroupType object and an instance of that type. The GroupType class is derived from Autodesk.Revit.Symbol, and Group from Autodesk.Revit.Element.

The Getting Started document turns up one snippet of information on groups in its question and answer section that may be useful to us later, but does not address our immediate need:

Q: When exporting a model containing groups to an external program, the user receives an error at the end of the export: "Changes to group "Group 1" are allowed only in group edit mode. Use the Edit Group command to make the change to all instances of the group. You may use the "Ungroup" option to proceed with this change by ungrouping the changed group instances."

A: Currently the API does not permit changes to members of groups. You can programmatically ungroup, make the change, regroup and then swap the other instances of the old group to the new group to get the same effect.

While this does not help us with our immediate question, it does at least further confirm the degree of programmatic access that is and is not provided to the grouping functionality.

Searching the Revit SDK Samples for NewGroup turns up no hits. Almost all aspects of the Revit API are demonstrated in the samples, so this is actually quite unusual. I have not addressed this in any of my labs yet either.

The next place to look is the developer guide. This is the most in-depth source of information on Revit programming, because it explains relationships and underlying concepts that are not immediately apparent from the classes, properties and methods presented in the help file nor immediately visible in the sample code. Again, we start by searching for 'NewGroup'. If no hits were found, I would then search for just 'group'. This time, 'NewGroup' is found, in section 9.4 Group. This section does indeed explain groups very well from the programming point of view. It also includes two code snippets 9-8: Creating a Group and 9-9: Naming a Group.

This answers the first part of your question, on how to create a group.

Regarding the placement of instances, I continued searching in the creation document members and found the PlaceGroup method, which places an instance of a model group into the Revit project, using a location and a group type.

I have not implemented any code testing any of this yet. If you do, please feel free to pass it on.

I hope this helps you learn to fish, and does not just feed you.

Many thanks, Henry, for this illuminating question, and good luck with your further steps!