Namespace: Autodesk.Revit.Creation Class: ItemFactoryBase

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

Method

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.

Syntax

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

Examples

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

Parameters

Parameter	Type	Description
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

Type	Description
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.