ItemFactoryBaseNewFamilyInstance(XYZ, FamilySymbol, XYZ, Element, StructuralType) Method

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

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

Syntax

C++

Copy

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
)

member NewFamilyInstance : 
        location : XYZ * 
        symbol : FamilySymbol * 
        referenceDirection : XYZ * 
        host : Element * 
        structuralType : StructuralType -> FamilyInstance

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 .

Exceptions

Exception	Condition
ArgumentException	Thrown if The symbol is not active.

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++

Copy

// 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

Reference

ItemFactoryBase Class

NewFamilyInstance Overload

Autodesk.Revit.Creation Namespace