Pr e-R elea ded se
Lesson 7 Selection and TraversalSelection and Traversal
Techniques
Upon successful completion of this lesson you will be able to:
I Programmatically select objects.
I Access selected objects using the SelectionManager.
I Determine the type of a selected feature.
I Extract and modify feature data.
I Traverse features.
I Traverse geometry.
I Suppress features and set feature visibility.
I Select features at a known FeatureManager position.
Pr e-R elea se
Do no t co py or dis trib ute
Lesson 7 API Fundamentals
Selection and Traversal Techniques
Pr e-R elea se
Do no t co py or dis trib ute
API Fundamentals Lesson 7
Selection and Traversal Techniques
Case Study: Programming With a Selected Object 179
Case Study:
Programming With a Selected Object
This macro
demonstrates how to access and modify the data specific to certain features in a part file.
It requires that the user selects the Extrude1 feature before running the macro.
1 Open existing part and macro.
Open the part Preselection.sldprt and the macro Preselection.swp.
2 Add code to the Generate button.
Add the following code
Private Sub cmdGenerate_Click() Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Set swApp = Application.SldWorks Set swModel = swApp.ActiveDoc End Sub
Pr e-R elea se
Do no t co py or dis trib ute
Lesson 7 API Fundamentals
Selection and Traversal Techniques
SelectionManager The SelectionManager is an object interface that is dedicated to managing selected objects in the SolidWorks user interface. Every document created in SolidWorks has its own SelectionManager
property that is accessible using the API. Anything that is selected in a document is temporarily stored in the SelectionManager. The selected object remains there until it is un-selected or when a rebuild occurs.
The SelectionManager is a 1 based collection. The first available index is 1, not 0. The SelectionManager also exposes methods and properties that allow the programmer to access objects at any index. The
programmer can then return the object pointer at a specific index and call methods or properties on that object.
Accessing the Selection Manager
To get an interface pointer to the SelectionManager object, you would use the ModelDoc2::SelectionManager property:
DimSelMgrasSldWorks.SelectionMgr SetSelMgr= ModelDoc2.SelectionManager.
Counting Selected Objects
To determine the number of selected objects, use SelectionMgr::GetSelectedObjectCount.
3 Add the following code.
Connect to the Selection Manager and return the object count.
Private Sub cmdGenerate_Click() Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Dim swSelMgr As SldWorks.SelectionMgr Dim count As long
Set swSelMgr = swModel.SelectionManager count = swSelMgr.GetSelectedObjectCount If count <> 1 Then
swApp.SendMsgToUser2 "Please select only Extrude1.", _ swMbWarning, swMbOk
Output: SelectionMgr Pointer a Dispatch object, the SelectionMgr object for this document
SelectionMgr::GetSelectedObjectCount
retval = SelectionMgr.GetSelectedObjectCount ( )
Return: retval Number of currently selected objects.
Pr e-R elea se
Do no t co py or dis trib ute
API Fundamentals Lesson 7
Selection and Traversal Techniques
Case Study: Programming With a Selected Object 181
Accessing Selected Objects
To get an interface pointer to a currently selected object use SelectionMgr::GetSelectedObject5.
Getting Selected Object Types
To determine the selected object type use SelectionMgr::GetSelectedObjectType2.
Getting Feature Type Names
To verify that a specific feature is selected use Feature::GetTypeName.
4 Declare a feature variable.
Add the variable in the button click event.
Private Sub cmdGenerate_Click() Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Dim swSelMgr As SldWorks.SelectionMgr Dim count As long
Dim Feature As SldWorks.Feature Set swApp = Application.SldWorks Set swModel = swApp.ActiveDoc
Set swSelMgr = swModel.SelectionManager count = swSelMgr.GetSelectedObjectCount
SelectionMgr::GetSelectedObject5
retval = SelectionMgr.GetSelectedObject5 (AtIndex)
Return: retval Pointer a dispatch object.
Input: AtIndex Index position within the current list of selected items where AtIndex ranges:From 1 To
SelectionMgr::GetSelectObjectCount
SelectionMgr::GetSelectedObjectType2
retval = SelectionMgr.GetSelectedObjectType2 (AtIndex)
Note: If the object returned is a feature, use Feature::GetTypeName for determining the feature type.
Return: retval Object type. See API Help file for full list.
Input: AtIndex Index position within the current list of selected items where AtIndex ranges:From 1 To
SelectionMgr::GetSelectObjectCount
Feature::GetTypeName
retval = Feature.GetTypeName ( )
Return: retval Feature type. See API Help file for full list.
Pr e-R elea se
Do no t co py or dis trib ute
Lesson 7 API Fundamentals
Selection and Traversal Techniques
5 Return a pointer to the selected feature.
Scroll down and add the following code:
If count > 1 Then
swApp.SendMsgToUser2 "Please select only Extrude1.", _ swMbWarning, swMbOk
Me.Hide Exit Sub End If
Set Feature = swSelMgr.GetSelectedObject5(count) If Not Feature.GetTypeName = “Extrusion” Then
swApp.SendMsgToUser "Please select only Extrude1."
Exit Sub End If End Sub
Feature Data Objects
Every feature in the SolidWorks FeatureManager design tree has a corresponding FeatureData object available in the API. The Feature object represents the interface that exposes methods and properties available for all features. The FeatureData object is the more specific object that exposes the functionality of each specific feature type.
Accessing the Feature Data Object
To return a pointer to the FeatureData object from a Feature object use the method Feature::GetDefinition.
Accessing Selections
To allow access to the entities used to create the feature, use the FeatureData::AccessSelections method from any of the FeatureData types. Because this method puts the model into a rollback state, use it only when you need to access the entity selections used to create the feature. It is not needed to change simple exposed properties on a FeatureData object.
Feature::GetDefinition
retval = Feature.GetDefintion ( )
Return: retval Dispatch pointer to the feature definition object. See API Help file for full list of feature objects.
ExtrudeFeatureData2::AccessSelections
accessGained = ExtrudeFeatureData2.AccessSelections (TopDoc, Component)
Return: accessGained TRUE if the selections were accessed successfully,
FALSE if not.
Input: TopDoc Top-level document.
Input: Component Component in which the feature is to be modified.
Pr e-R elea se
Do no t co py or dis trib ute
API Fundamentals Lesson 7
Selection and Traversal Techniques
Case Study: Programming With a Selected Object 183
Releasing Selections
When using AccessSelections, the program must also make a
corresponding call to ExtrudeFeatureData2::ReleaseSelectionAccess to restore the rollback state for cases when a feature is not modified.
This method is only needed if the feature’s data is not modified.
If the FeatureData object’s data is modified, another method is used to regenerate the feature with the new data. This method,
Feature::ModifyDefinition, will be explained shortly.
6 Connect to a FeatureData object.
Add the following code to connect to the ExtrudeFeatureData object.
Private Sub cmdGenerate_Click() Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Dim swSelMgr As SldWorks.SelectionMgr Dim count As long
Dim Feature As SldWorks.Feature
Dim ExtrudeFeatureData As Sldworks.ExtrudeFeatureData2 Dim retval As Boolean
Set swApp = Application.SldWorks Set swModel = swApp.ActiveDoc
Set swSelMgr = swModel.SelectionManager count = swSelMgr.GetSelectedObjectCount If count > 1 Then
swApp.SendMsgToUser "Please select only Extrude1."
Me.Hide Exit Sub End If
Set Feature = swSelMgr.GetSelectedObject5(count) If Not Feature.GetTypeName = swTnExtrusion Then
swApp.SendMsgToUser2 "Please select the Extrude1.", _ swMbWarning, swMbOk
Exit Sub End If
Set ExtrudeFeatureData = Feature.GetDefinition End Sub
Modifying Feature Data Properties
One of the modifications for an extruded feature is setting the depth.
First call ExtrudeFeatureData2::GetDepth to retrieve the existing depth value and then call ExtrudeFeatureData2::SetDepth to set a new value.
ExtrudeFeatureData2::ReleaseSelectionAccess
void ExtrudeFeatureData2.ReleaseSelectionAccess ( )
Return: void No return value.
Pr e-R elea se
Do no t co py or dis trib ute
Lesson 7 API Fundamentals
Selection and Traversal Techniques
Modify the Object Definition
Finally, call Feature::ModifyDefinition to implement changes.
7 Modify extrude depth.
Add the following code entries to modify the depth of the extruded feature.
Private Sub cmdGenerate_Click() Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Dim swSelMgr As SldWorks.SelectionMgr Dim count As long
Dim Feature As SldWorks.Feature
Dim ExtrudeFeatureData As SldWorks.ExtrudeFeatureData2 Dim retval As Boolean
Dim Depth As Double Dim Factor As Integer
Factor = CInt(txtDepth.Text) Set swApp = Application.SldWorks Set swModel = swApp.ActiveDoc
Set swSelMgr = swModel.SelectionManager count = swSelMgr.GetSelectedObjectCount If count > 1 Then
swApp.SendMsgToUser2 "Please select only Extrude1.", _ swMbWarning, swMbOk
Me.Hide Exit Sub End If
Set Feature = swSelMgr.GetSelectedObject5(count) If Not Feature.GetTypeName = swTnExtrusion Then
swApp.SendMsgToUser2 "Please select the Extrude1.", _ swMbWarning, swMbOk
Exit Sub End If
Set ExtrudeFeatureData = Feature.GetDefinition Depth = ExtrudeFeatureData.GetDepth(True)
ExtrudeFeatureData.SetDepth True, Depth * Factor retval = Feature.ModifyDefinition _
(ExtrudeFeatureData, swModel, Nothing) End Sub
Feature::ModifyDefinition
retval = Feature.ModifyDefinition (Definition, TopDoc, Component)
Return: retval TRUE if the feature is updated successfully, FALSE if not.
Input: Definition Dispatch pointer to the feature definition object.
Input: TopDoc Top-level document.
Input: Component Component for the feature.
Pr e-R elea se
Do no t co py or dis trib ute
API Fundamentals Lesson 7
Selection and Traversal Techniques
The SolidWorks BREP Model 185
8 Save and run the macro.
Select the Extrude1 feature from the FeatureManager and run the macro.
Enter 5 in the multiplication factor text box and click the Generate button.
Click it again and notice how the length of the extrusion keeps getting larger. Return to VBA when
finished.
The SolidWorks BREP Model
In order to traverse geometry in SolidWorks, a programmer should understand the boundary representation (BREP) model that SolidWorks uses and how the API represents these objects. Two object types are used to represent the BREP model in the SolidWorks API.
I Topology objects expose members that are used to manipulate the boundaries of all the geometry in the model.
I Geometry objects expose members that are used to manipulate the actual data that define the geometrical shape that the topology surrounds.
Highest Level Object
Lowest Level Object
Pr e-R elea se
Do no t co py or dis trib ute
Lesson 7 API Fundamentals
Selection and Traversal Techniques
The Face2 object is a topology object. All of the Face2 object members return data about the topology of this object and nothing about the actual sizes of the surface that the face surrounds. To get the actual geometrical data from the face, a programmer would call the accessor Face2::GetSurface to return a pointer to the underlying surface. The programmer could then use a method such as
Surface::GetBSurfaceParams or Surface::EvaluateAtPoint to discover the actual shape of this geometrical object.
Traversing Topology and Geometry
The objects in the diagram are listed in the order in which a
programmer would have to connect to them. A programmer would first have to connect to a Body pointer before they could connect to a Face pointer. The Body object has an accessor method called
Body::GetFirstFace that would return a Face pointer to the first face encountered on the body. The Face pointer has an accessor method called Face::GetNextFace that returns a pointer to the next face on the body. Combining these methods in a loop structure would allow the programmer to traverse all the faces on a body. This technique could be used on the other BREP objects as well.
Tip Keep in mind that there are accessors on several of these BREP objects that will allow a programmer to side step some of the traversing. For instance, to traverse to the edges of a face, a programmer does not have to get a pointer to every object above it in the diagram before they can finally work with an edge pointer. The Face2 object has an accessor method named Face2::GetEdges. This method will return a list of all the edges on the face. Although all the objects above the edge object have a special purpose, there are times where it would not be necessary to access all these objects just to get a pointer to the edge of a face.
Pr e-R elea se
Do no t co py or dis trib ute
API Fundamentals Lesson 7
Selection and Traversal Techniques
Case Study: Body and Face Traversal 187
Case Study:
Body and Face Traversal
This next macro traverses all the faces of a part (single or multibody) and modifies the color properties on each face. It does not require the user to select a face in order to run. Face traversal techniques are important in many areas of API programming, including:
I Selecting all types of faces (cylindrical, planar, etc.) on a body.
I Finding faces for adding mates.
I Finding edge, curve, and point information on faces.
I Automating multiple face modifications.
I Adding attributes to faces.
1 Open an existing part and create a new macro.
Open the part BodyFaceTraversal.sldprt.
Click and name the macro BodyFaceTraversal.swp.
2 Add code to Sub Main.
Connect to SolidWorks and the active document.
Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Sub main()
Set swApp = Application.SldWorks If Not swApp Is Nothing Then
Set swModel = swApp.ActiveDoc If Not swModel Is Nothing Then End If
Set swModel = Nothing End If
Set swApp = Nothing End Sub
Pr e-R elea se
Do no t co py or dis trib ute
Lesson 7 API Fundamentals
Selection and Traversal Techniques
3 Connect to the part document interface.
Although this explicit type cast is not necessary, it is done here to enable the IntelliSense on the PartDoc pointer.
Dim swPart As SldWorks.PartDoc Sub main()
Set swApp = Application.SldWorks If Not swApp Is Nothing Then
Set swModel = swApp.ActiveDoc If Not swModel Is Nothing Then
'Notice the Explicit Type Casting Set swPart = swModel
If Not swPart Is Nothing Then End If
Set swPart = Nothing End If
Set swModel = Nothing End If
Set swApp = Nothing End Sub
Returning a List of Body Pointers
PartDoc::GetBodies2 returns an array of all of the bodies in a part document. A loop can be used to traverse this returned list of bodies.
PartDoc::GetBodies2
retval = PartDoc.GetBodies2 (BodyType, VisibleOnly)
Return: retval SafeArray of dispatch pointers to the bodies.
Input: BodyType swSolidBody - solid body
swSheetBody - sheet body swWireBody - wire body swMinimumBody - point body
swGeneralBody - general, non-manifold body swEmptyBody - NULL body
swAllBodies - all solid bodies
Input: VisibleOnly TRUE gets only the visible bodies, FALSE gets all of the bodies in the part.
Pr e-R elea se
Do no t co py or dis trib ute
API Fundamentals Lesson 7
Selection and Traversal Techniques
Case Study: Body and Face Traversal 189
4 Return the array body object pointers.
Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Dim swPart As SldWorks.PartDoc Dim retval As Variant
Sub main()
Set swApp = Application.SldWorks If Not swApp Is Nothing Then
Set swModel = swApp.ActiveDoc If Not swModel Is Nothing Then
Set swPart = swModel
If Not swPart Is Nothing Then
retval = swPart.GetBodies2(swConst.swSolidBody, True) End If
Set swPart = Nothing End If
Set swModel = Nothing End If
Set swApp = Nothing End Sub
5 Declare an indexer and a face pointer.
Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Dim swPart As SldWorks.PartDoc Dim retval As Variant
Dim i As Integer
Dim swFace As SldWorks.face2
6 Program a loop to traverse the faces.
Sub main()
Set swApp = Application.SldWorks If Not swApp Is Nothing Then
Set swModel = swApp.ActiveDoc If Not swModel Is Nothing Then
Set swPart = swModel
If Not swPart Is Nothing Then
retval = swPart.GetBodies2(swSolidBody, True) For i = 0 To UBound(retval)
Set swFace = retval(i).GetFirstFace Do While Not swFace Is Nothing Loop
Next i End If
Set swPart = Nothing End If
Set swModel = Nothing End If
Set swApp = Nothing End Sub
Pr e-R elea se
Do no t co py or dis trib ute
Lesson 7 API Fundamentals
Selection and Traversal Techniques
Face Material Properties
Use the property Face2::MaterialPropertyValues to get or set material properties for a face.
Material properties are the colors and visual properties of a face. These properties can be overridden on every face in a model.
7 Declare an array to hold face material properties.
Dim swApp As SldWorks.SldWorks Dim swModel As SldWorks.ModelDoc2 Dim swPart As SldWorks.PartDoc Dim retval As Variant
Dim i As Integer
Dim swFace As SldWorks.face2 Dim matProps(8) As Double
Face2::MaterialPropertyValues
MaterialPropertyValues = Face2.MaterialPropertyValues ‘ Gets property Face2.MaterialPropertyValues = MaterialPropertyValues ‘ Sets property
Output: MaterialPropertyValues SafeArray of material values on a face. The format of the return values is an array of doubles as follows:
MaterialPropertyValues(0) - Red MaterialPropertyValues(1) - Green MaterialPropertyValues(2) - Blue MaterialPropertyValues(3) - Ambient MaterialPropertyValues(4) - Diffuse MaterialPropertyValues(5) - Specular MaterialPropertyValues(6) - Shininess MaterialPropertyValues(7) - Transparency MaterialPropertyValues(8) - Emission