ItemFactoryBase.NewFamilyInstance(XYZ, FamilySymbol, XYZ, Element, StructuralType) Method

Namespace: Autodesk.Revit.Creation
Assembly: RevitAPI (in RevitAPI.dll) Version: 26.1.0.0 (26.1.0.34)

Syntax

C#

public FamilyInstance NewFamilyInstance(
	XYZ location,
	FamilySymbol symbol,
	XYZ referenceDirection,
	Element host,
	StructuralType structuralType
)

Parameters

location  XYZ

The physical location where the instance is to be placed.

symbol  FamilySymbol

A FamilySymbol object that represents the type of the instance that is to be inserted.

referenceDirection  XYZ

A vector that dictates the direction of certain family instances.

host  Element

A host object into which the instance will be embedded

structuralType  StructuralType

If structural then specify the type of the component.

Return Value

FamilyInstance
If creation was successful then an instance to the new object is returned, otherwise nullptr.

Exceptions

Remarks

This method allows you to create FamilyInstance objects that require both a location and direction. If the instance fails to be created an exception may be thrown.

The type/symbol that is used must be loaded into the document before this method is called. Families and their symbols can be loaded using the Document.LoadFamily or Document.LoadFamilySymbol methods.

Some Families, such as Beams, have more than one endpoint and are inserted in the same manner as single point instances. Once inserted these linear family instances can have their endpoints changed by using the instance's Element.Location property.

Note: if the created family instance includes nested instances, the API framework will automatically regenerate the document during this method call.

Example

C#

// Get a floor to place the beds
 FilteredElementCollector collector = new FilteredElementCollector(document);
 Floor floor = collector.OfClass(typeof(Floor)).FirstElement() as Floor;
 if (floor != null)
 {
     // Find a Bed-Box family
     Family family = null;
     FilteredElementCollector famCollector = new FilteredElementCollector(document);
     famCollector.OfClass(typeof(Family));
     ICollection<Element> collection = famCollector.ToElements();
     foreach (Element element in collection)
     {

         if (element.Name.CompareTo("Bed-Box") == 0)
         {
             family = element as Family;
             break;
         }
     }

     if (family != null)
     {
         // Enumerate the beds in the Bed-Box family
         FilteredElementCollector fsCollector = new FilteredElementCollector(document);
         ICollection<Element> fsCollection = fsCollector.WherePasses(new FamilySymbolFilter(family.Id)).ToElements();
         IEnumerator<Element> symbolItor = fsCollection.GetEnumerator();

         int x = 0, y = 0;
         int i = 0;
         while (symbolItor.MoveNext())
         {
             FamilySymbol symbol = symbolItor.Current as FamilySymbol;
             XYZ location = new XYZ(x, y, 0);
             XYZ direction = new XYZ();
             switch (i % 3)
             {
                 case 0:
                     direction = new XYZ(1, 1, 0);
                     break;
                 case 1:
                     direction = new XYZ(0, 1, 1);
                     break;
                 case 2:
                     direction = new XYZ(1, 0, 1);
                     break;
             }
             FamilyInstance instance = document.Create.NewFamilyInstance(location, symbol, direction, floor, StructuralType.NonStructural);
             x += 10;
             i++;
         }
     }
 }

VB

' Get a floor to place the beds
Dim collector As New FilteredElementCollector(document)
Dim floor As Floor = TryCast(collector.OfClass(GetType(Floor)).FirstElement(), Floor)
If floor IsNot Nothing Then
    ' Find a Bed-Box family
    Dim family As Family = Nothing
    Dim famCollector As New FilteredElementCollector(document)
    famCollector.OfClass(GetType(Family))
    Dim collection As ICollection(Of Element) = famCollector.ToElements()
    For Each element As Element In collection

        If element.Name.CompareTo("Bed-Box") = 0 Then
            family = TryCast(element, Family)
            Exit For
        End If
    Next

    If family IsNot Nothing Then
        ' Enumerate the beds in the Bed-Box family
        Dim fsCollector As New FilteredElementCollector(document)
        Dim fsCollection As ICollection(Of Element) = fsCollector.WherePasses(New FamilySymbolFilter(family.Id)).ToElements()
        Dim symbolItor As IEnumerator(Of Element) = fsCollection.GetEnumerator()

        Dim x As Integer = 0, y As Integer = 0
        Dim i As Integer = 0
        While symbolItor.MoveNext()
            Dim symbol As FamilySymbol = TryCast(symbolItor.Current, FamilySymbol)
            Dim location As New XYZ(x, y, 0)
            Dim direction As New XYZ()
            Select Case i Mod 3
                Case 0
                    direction = New XYZ(1, 1, 0)
                    Exit Select
                Case 1
                    direction = New XYZ(0, 1, 1)
                    Exit Select
                Case 2
                    direction = New XYZ(1, 0, 1)
                    Exit Select
            End Select
            Dim instance As FamilyInstance = document.Create.NewFamilyInstance(location, symbol, direction, floor, StructuralType.NonStructural)
            x += 10
            i += 1
        End While
    End If
End If

See Also

Reference