Inserts a new instance of a family onto a face referenced by the input Reference instance,
using a line on that face for its position, and a type/symbol.
Namespace:
Autodesk.Revit.Creation
Assembly:
RevitAPI
(in RevitAPI.dll) Version: 17.0.0.0 (17.0.1090.0)
Syntax
C# |
---|
|
Visual Basic |
---|
|
Visual C++ |
---|
|
Parameters
- reference
-
Type:
Autodesk.Revit.DB
Reference
A reference to a face.
- position
-
Type:
Autodesk.Revit.DB
Line
A line on the face defining where the symbol is to be placed.
- symbol
-
Type:
Autodesk.Revit.DB
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
An instance of the new object if creation was successful, otherwise a null reference ( Nothing in Visual Basic) .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.
Examples
Copy
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);
}
Copy
VB.NET
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
Exceptions
Exception | Condition |
---|---|
Autodesk.Revit.Exceptions ArgumentNullException | Thrown when a non-optional argument was null. |
Autodesk.Revit.Exceptions ArgumentException | Thrown when the function cannot get a face from the reference, or, when the family cannot be placed as line-based on an input face reference, because its FamilyPlacementType is not WorkPlaneBased or CurveBased |
Autodesk.Revit.Exceptions ArgumentsInconsistentException | Thrown when the family cannot be placed on this line as it does not coincide with the input face. |
Autodesk.Revit.Exceptions InvalidOperationException | Thrown when Revit is unable to place the family instance. |
Autodesk.Revit.Exceptions ArgumentException | Thrown if The symbol is not active. |