Other Classifications

Other Classifications

Elements are also classified by the following:

There are some relationships between the classifications. For example:

Category

The Element.Category property represents the category or subcategory to which an Element belongs. It is used to identify the Element type. For example, anything in the walls Category is considered a wall. Other categories include doors and rooms.

Categories are the most general class. The Document.Settings.Categories property is a map that contains all Category objects in the document and is subdivided into the following:

  • Model Categories - Model Categories include beams, columns, doors, windows, and walls.
  • Annotation Categories. Annotation Categories include dimensions, grids, levels, and textnotes.

Figure 20: Categories

Note: The following guidelines apply to categories:
  • In general, the following rules apply to categories:
    • Each family object belongs to a category
    • Non-family objects, like materials and views, do not belong to a category
    • There are exceptions such as ProjectInfo, which belongs to the Project Information category.
  • An element and its corresponding symbols are usually in the same category. For example, a basic wall and its wall type Generic - 8" are all in the Walls category.
  • The same type of Elements can be in different categories. For example, SpotDimensions has the SpotDimensionType, but it can belong to two different categories: Spot Elevations and Spot Coordinates.
  • Different Elements can be in the same category because of their similarity or for architectural reasons. ModelLine and DetailLine are in the Lines category.

To gain access to the categories in a document' Setting class (for example, to insert a new category set), use one of the following techniques:

  • Get the Categories from the document properties.
  • Get a specific category quickly from the categories map using the BuiltInCategory enumerated type.

Code Region 5-1: Getting categories from document settings 

// Get settings of current document
Settings documentSettings = document.Settings;

// Get all categories of current document
Categories groups = documentSettings.Categories;

// Show the number of all the categories to the user
String prompt = "Number of all categories in current Revit document:" + groups.Size; 

// get Floor category according to OST_Floors and show its name
Category floorCategory = groups.get_Item(BuiltInCategory.OST_Floors);
prompt += floorCategory.Name;

// Give the user some information
MessageBox.Show(prompt, "Revit", MessageBoxButtons.OK);

Category is used in the following manner:

  • Category is used to classify elements. The element category determines certain behaviors. For example, all elements in the same category can be included in the same schedule.
  • Elements have parameters based on their categories.
  • Categories are also used for controlling visibility and graphical appearance in Revit.

Figure 21: Visibility by Category

An element's category is determined by the Category ID.

  • Category IDs are represented by the ElementId class.
  • Imported Category IDs correspond to elements in the document.
  • Most categories are built-in and their IDs are constants stored in ElementIds.
  • Each built-in category ID has a corresponding value in the BuiltInCategory Enumeration. They can be converted to corresponding BuiltInCategory enumerated types.
  • If the category is not built-in, the ID is converted to a null value.

Code Region 5-2: Getting element category 

Element selectedElement = null;
foreach (Element e in document.Selection.Elements)
{
        selectedElement = e;
        break;  // just get one selected element
}

// Get the category instance from the Category property
Category category = selectedElement.Category;

BuiltInCategory enumCategory = (BuiltInCategory)category.Id.Value;
Note: To avoid Globalization problems when using Category.Name, BuiltInCategory is a better choice. Category.Name can be different in different languages.

Family

Families are classes of Elements within a category. Families can group Elements by the following:

  • A common set of parameters (properties).
  • Identical use.
  • Similar graphical representation.

Most families are component Family files, meaning that you can load them into your project or create them from Family templates. You determine the property set and the Family graphical representation.

Another family type is the system Family. System Families are not available for loading or creating. Revit predefines the system Family properties and graphical representation; they include walls, dimensions, roofs, floors (or slabs), and levels.

Figure 22: Families

In addition to functioning as an Element class, Family is also a template used to generate new items that belong to the Family.

Family in the Revit Platform API

In the Revit Platform API, both the Family class and FamilyInstance belong to the Component Family. Other Elements include System Family.

Families in the Revit Platform API are represented by three objects:

  • Family
  • FamilySymbol
  • FamilyInstance.

Each object plays a significant role in the Family structure.

The Family object has the following characteristics:

  • Represents an entire family such as a beam.
  • Represents the entire family file on a disk.
  • Contains a number of FamilySymbols.

The FamilySymbol object represents a specific set of family settings in the Family such as the Type, Concrete-Rectangular Beam: 16×32.

The FamilyInstance object is a FamilySymbol instance representing a single instance in the Revit project. For example, the FamilyInstance can be a single instance of a 16×32 Concrete-Rectangular Beam in the project.

Note: Remember that the FamilyInstance exists in FamilyInstance Elements, Datum Elements, and Annotation Elements.

Consequently, the following rules apply:

  • Each FamilyInstance has one FamilySymbol.
  • Each FamilySymbol belongs to one Family.
  • Each Family contains one or more FamilySymbols.

For more detailed information, see Family Instances.

ElementType

In the Revit Platform API, Symbols are usually non-visible elements used to define instances. Symbols are called Types in the user interface.

  • A type can be a specific size in a family, such as a 1730 × 2032 door, or an 8×4×1/2 angle.
  • A type can be a style, such as default linear or default angular style for dimensions.

Symbols represent Elements that contain shared data for a set of similar elements. In some cases, Symbols represent building components that you can get from a warehouse, such as doors or windows, and can be placed many times in the same building. In other cases, Symbols contain host object parameters or other elements. For example, a WallType Symbol contains the thickness, number of layers, material for each layer, and other properties for a particular wall type.

FamilySymbol is a symbol in the API. It is also called Family Type in the Revit user interface. FamilySymbol is a class of elements in a family with the exact same values for all properties. For example, all 32×78 six-panel doors belong to one type, while all 24×80 six-panel doors belong to another type. Like a Family, a FamilySymbol is also a template. The FamilySymbol object is derived from the ElementType object and the Element object.

Instance

Instances are items with specific locations in the building (model instances) or on a drawing sheet (annotation instances). Instance represents transformed identical copies of an ElementType. For example, if a building contains 20 windows of a particular type, there is one ElementType with 20 Instances. Instances are called Components in the user interface.

Note: For FamilyInstance, the Symbol property can be used instead of the GetTypeId() method to get the corresponding FamilySymbol. It is convenient and safe since you do not need to do a type conversion.
Parent topic: Elements Essentials