M

ItemFactoryBase.NewFamilyInstance

Description:
Inserts a new instance of a family into the document, using a location, type/symbol, the host element and a reference direction.

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.

Overloads (9):

NewFamilyInstance(Face,Line,FamilySymbol)

NewFamilyInstance(Face,XYZ,XYZ,FamilySymbol)

NewFamilyInstance(Line,FamilySymbol,View)

NewFamilyInstance(Reference,Line,FamilySymbol)

NewFamilyInstance(Reference,XYZ,XYZ,FamilySymbol)

NewFamilyInstance(XYZ,FamilySymbol,Element,StructuralType)

NewFamilyInstance(XYZ,FamilySymbol,StructuralType)

NewFamilyInstance(XYZ,FamilySymbol,View)

NewFamilyInstance(XYZ,FamilySymbol,XYZ,Element,StructuralType)

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

Public Function NewFamilyInstance ( _
	location As XYZ, _
	symbol As FamilySymbol, _
	referenceDirection As XYZ, _
	host As Element, _
	structuralType As StructuralType _
) As FamilyInstance

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

Autodesk.Revit.DB.XYZ

location

The physical location where the instance is to be placed.
Autodesk.Revit.DB.FamilySymbol

symbol

A FamilySymbol object that represents the type of the instance that is to be inserted.
Autodesk.Revit.DB.XYZ

referenceDirection

A vector that dictates the direction of certain family instances.
Autodesk.Revit.DB.Element

host

A host object into which the instance will be embedded
Autodesk.Revit.DB.Structure.StructuralType

structuralType

If structural then specify the type of the component.

Return Value nullNothingnullptr If creation was successful then an instance to the new object is returned, otherwise null Nothing nullptr a null reference ( Nothing in Visual Basic) .

// 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++;
         }
     }
 }

' 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

Autodesk.Revit.Exceptions.ArgumentException

Thrown if The symbol is not active.