ItemFactoryBase.NewFamilyInstance(Reference, Line, FamilySymbol) Method

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

Syntax

C#

public FamilyInstance NewFamilyInstance(
	Reference reference,
	Line position,
	FamilySymbol symbol
)

Parameters

reference  Reference

A reference to a face.

position  Line

A line on the face defining where the symbol is to be placed.

symbol  FamilySymbol

A FamilySymbol object that represents the type of the instance that is to be inserted. Note that this symbol must represent a family whose FamilyPlacementType is WorkPlaneBased or CurveBased.

Return Value

FamilyInstance
An instance of the new object if creation was successful, otherwise nullptr.

Exceptions

Remarks

Use this method to insert one family instance on a face of another element, using a line on the face to define the position and direction of the new symbol.

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.

The host object must support insertion of instances, otherwise this method will fail. If the instance fails to be created an exception may be thrown.

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

Example

C#

public void PlaceStiffenerOnWallFaceRef(Autodesk.Revit.DB.Document doc)
{
    FilteredElementCollector wallCollector = new FilteredElementCollector(doc);
    wallCollector.OfClass(typeof(Wall));
    Wall wall = wallCollector.FirstElement() as Wall;

    // The structural stiffeners family type is compatible with line-based face placement
    FilteredElementCollector fsCollector = new FilteredElementCollector(doc);
    fsCollector.OfClass(typeof(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralStiffener);
    FamilySymbol stiffenerSymbol = fsCollector.FirstElement() as FamilySymbol;

    // Get side face of wall
    IList<Reference> sideFaces = HostObjectUtils.GetSideFaces(wall, ShellLayerType.Exterior);
    Reference sideFaceRef = sideFaces[0];

    // Generate line for path
    Face face = wall.GetGeometryObjectFromReference(sideFaceRef) as Face;
    BoundingBoxUV bbox = face.GetBoundingBox();
    UV lowerLeft = bbox.Min;
    UV upperRight = bbox.Max;
    double deltaU = upperRight.U - lowerLeft.U;
    double deltaV = upperRight.V - lowerLeft.V;
    double vOffset = deltaV * 0.60; // 60% up the wall face

    UV firstPoint = lowerLeft + new UV(deltaU * 0.20, vOffset);
    UV lastPoint = lowerLeft + new UV(deltaU * 0.80, vOffset);

    Line line = Line.CreateBound(face.Evaluate(firstPoint), face.Evaluate(lastPoint));

    doc.Create.NewFamilyInstance(sideFaceRef, line, stiffenerSymbol);
}

VB

Public Sub PlaceStiffenerOnWallFaceRef(doc As Autodesk.Revit.DB.Document)
    Dim wallCollector As New FilteredElementCollector(doc)
    wallCollector.OfClass(GetType(Wall))
    Dim wall As Wall = TryCast(wallCollector.FirstElement(), Wall)

    ' The structural stiffeners family type is compatible with line-based face placement
    Dim fsCollector As New FilteredElementCollector(doc)
    fsCollector.OfClass(GetType(FamilySymbol)).OfCategory(BuiltInCategory.OST_StructuralStiffener)
    Dim stiffenerSymbol As FamilySymbol = TryCast(fsCollector.FirstElement(), FamilySymbol)

    ' Get side face of wall
    Dim sideFaces As IList(Of Reference) = HostObjectUtils.GetSideFaces(wall, ShellLayerType.Exterior)
    Dim sideFaceRef As Reference = sideFaces(0)

    ' Generate line for path
    Dim face As Face = TryCast(wall.GetGeometryObjectFromReference(sideFaceRef), Face)
    Dim bbox As BoundingBoxUV = face.GetBoundingBox()
    Dim lowerLeft As UV = bbox.Min
    Dim upperRight As UV = bbox.Max
    Dim deltaU As Double = upperRight.U - lowerLeft.U
    Dim deltaV As Double = upperRight.V - lowerLeft.V
    Dim vOffset As Double = deltaV * 0.6
    ' 60% up the wall face
    Dim firstPoint As UV = lowerLeft + New UV(deltaU * 0.2, vOffset)
    Dim lastPoint As UV = lowerLeft + New UV(deltaU * 0.8, vOffset)

    Dim line__1 As Line = Line.CreateBound(face.Evaluate(firstPoint), face.Evaluate(lastPoint))

    doc.Create.NewFamilyInstance(sideFaceRef, line__1, stiffenerSymbol)
End Sub

See Also

Reference