Macro Tutorial – Mate Toggles

I have recently written a couple of, what I call, “Quick and Dirty” macros.  These are so quick, all you have to do is make a selection and run the macro.   In this article, I am going to discuss some of the thoughts and development processes behind writing one of these macros.

Please keep in mind that not all of the information you need is included in this article.  There may be a few cases where I jumped to the code that I used without a thorough explanation of how I go there.  The information provided here should be a good guideline for

The Setup:

SolidWorks allows you to have multiple mating schemes that allow you to show multiple positions of a component, within an assembly.  You can use configurations to do this, but for the purposes of this article, we will be suppressing and unsuppressing mates within a single configuration of the assembly.

Currently, when you need to toggle mates to move a component from one position to another, you need to select some mates and suppress them, then select more mates and unsuppress them.  At this time, the component will move to the new position.  This is a four (4) step (select, suppress, select, unsuppress) process.  Let’s see if we can get that down to two (2) steps (select, (un)suppress).

If you would like to follow along with what I did, you can download the sample models and macros here.  Please note that this macro was written in SolidWorks 2007.  It has been tested in SolidWorks 2006 after the SolidWorks Type Libraries have been changed.  In the Macro Editor, click on the “References” menu and select the SolidWorks 2006 Type Libraries, then resave the macro.  The models have been created in SolidWorks 2003.

Phase 1 – Record a Macro:

First thing we need to do is figure our how the SolidWorks API selects a mate, suppresses a mate and unsuppresses a mate.  This is a great time to use the macro recorder.  Here is how we will capture what we need to know.

• Load an assembly into SolidWorks.
• Turn on the Macro Recorder.
• Select an unsuppressed mate.
• Suppress the mate.
• Select a suppressed mate.
• Unsuppress the mate.
• Stop the Macro recorder and save the new recorded macro.

When we edit the recorded macro, we get something very similar to the following:

' ******************************************************************************
' MateToggle.swb - macro recorded on 09/04/07 by lkikstra
' ******************************************************************************
Dim swApp As Object
Dim Part As Object
Dim SelMgr As Object
Dim boolstatus As Boolean
Dim longstatus As Long, longwarnings As Long
Dim Feature As Object
Sub main()

Set swApp = Application.SldWorks

Set Part = swApp.ActiveDoc
Set SelMgr = Part.SelectionManager
boolstatus = Part.Extension.SelectByID2("Parallel1", "MATE", 0, 0, 0, False, 0, Nothing, 0)
Part.EditSuppress
Part.ClearSelection2 True
boolstatus = Part.Extension.SelectByID2("Parallel2", "MATE", 0, 0, 0, False, 0, Nothing, 0)
Part.EditUnsuppress
Part.ClearSelection2 True
End Sub

By looking at the above code, we can see that the macro attached to SolidWorks, then attached to the active document, enabled the selection manager, selected a mate, suppressed it, selected another mate, unsuppressed it, then ended.  These are the same steps we did when we initially recorded the macro.  So far, so good.

When you attempt to run this macro on the same assembly, nothing happens.  Why?  Because the suppression states of mates were changed while you were recording the macro.  In order for the macro to work properly, the same conditions must exist in SolidWorks now, as they did when you initially recorded the macro.  To see that above macro will work, suppress the “Parallel2” mate and unsuppress the “Parallel1” mate and launch the macro again.  Now everything should work as expected.

To see the macro in action, put the mates back to their original status and open the macro in the macro recorder.  Press the [F8] key to step thru the macro line-by-line.

As we step thru the macro, we can learn that the following:

• “boolstatus = Part.Extension.SelectByID2” selects the mate.
• “Part.EditSuppress” will suppress the mate.
• “Part.EditUnsuppress” will unsuppress the mate.
• “Part.ClearSelection2 True” will clear the current selection

At this point, the macro will only work for an assembly that has the “Parallel1” mate unsuppressed, and “Parallel2” mate suppressed.  If these mates do not exist in the assembly, the macro will run, but nothing will happen.

Phase 2 – Modify the recorded macro for “universal” use:

We can modify this macro, or use what we learned, to build a new macro that will work on any assembly, and any mates, but before we can do that we need to decide how we want the macro to work.  Here are my thoughts:

• Require user to select a mate before running macro.
• Check the suppression state of the selected mate.
• Toggle the suppression state

We now have 2 things for us to learn and develop for this macro.  Mate pre-selection and checking the current suppression state of the selected mate.

From the original recorded macro, we can see that the macro enabled a selection manager (“Set SelMgr = Part.SelectionManager”) before selecting the mate.   We will need to add this line to our code because we need to access the selection made by the user.

The next thing we need to look at is how to access the user’s selection.  We know the line “boolstatus = Part.Extension.SelectByID2” makes the selection, but we don’t know the name that at this time, so we need to look for other ways to access the user’s selection.  In the SolidWorks API and Add-ins help file (API Help File), go to the “Index” tab and enter “Get” and start scrolling down the list to see if anything makes sense.  I do know from past experience that “GetSelectedObject6” works for our needs.  This brings us to the page “SelectionMgr::GetSelectedObject6”.  We can read this page for more information.  Because a selection set is lost after it is used, we can only work with the first selection in the set.

We will need to modify our selection to read as follows:
Set MySelection = SelMgr.GetSelectedObject6(1, -1)

To check the suppression state, we can go to the API Help File and search for “Suppress”.  While cruising thru the list, I found the page “Assembly and Mate Traversal”.  On the API Help File page, I see a reference to “Component2::IsSuppressed”, and on the page “Configuration::SuppressNewFeatures”, I see that the same setting affects features and mates.  It appears that the assembly mates are features in the assembly.  It might be a leap, but let’s try it.

To check for the suppression state, we can use “MySelection.IsSuppressed”.  To be able to react properly to this state, we need to modify the suppress/unsuppress, we need to add the following lines:

If MySelection.IsSuppressed Then
  Part.EditUnsuppress
Else
  Part.EditSuppress
End If

Because a selection set is lost after it is used, we can get rid of the “Part.ClearSelection2 True” line. 

Our updated macro now looks like this:

' ******************************************************************************
' MateToggle2.swb - macro modified on 09/04/07 by lkikstra
' ******************************************************************************
Dim swApp As Object
Dim Part As Object
Dim SelMgr As Object
Dim boolstatus As Boolean
Dim longstatus As Long, longwarnings As Long
Dim Feature As Object
Dim MySelection As Object
Sub main()
Set swApp = Application.SldWorks
Set Part = swApp.ActiveDoc
Set Sel Mgr = Part.SelectionManager
Set MySelection = SelMgr.GetSelectedObject6(1, -1)
If MySelection.IsSuppressed Then
  Part.EditUnsuppress
Else
  Part.EditSuppress
End If
End Sub

It works pretty slick.  You can end the development here if you like because you now have a macro that does what you need.

Phase 3 – Optional Enhancements:

Your macro works, but there are a few more things we need to consider:

What if the person selects a part instead of a mate?  What if nothing was selected?  In these cases, you can add a filters between the selection, and the suppression status check.  To check if something was selected, we can add a line testing the contents of  “MySelection”.  To ensure a mate was selected, we can add a line to check the type of “MySelection”.  The MateToggle3.swp macro illustrates how to do this.  Here is how that portion of the code looks:

  If Not MySelection Is Nothing Then        ' Is something selected
    If SelMgr.GetSelectedObjectType3(1, -1) = swSelMATES Then
                                            ' Filter selection
      If MySelection.IsSuppressed Then
        Part.EditUnsuppress
      Else
        Part.EditSuppress
      End If
    Else
      MsgBox "No mates selected."
    End If                                  ' Filter selection
  Else
    MsgBox "Nothing selected."
  End If                                    ' Is something selected

At this stage, I added message boxes to inform the user of improper selections that the macro will not handle.    I also indented the code so the user can see the nested statements, and I added a few comments at the end of a few lines.  Both of these techniques are not mandatory, but they do make the code a little easier to follow and understand. 

Because this macro should only work within a SolidWorks assembly, the macro should check to see if the current document is an assembly.

One final enhancement would be to make the macro work on more than one mate at a time?  This does get tricky because a selection set is lost after it is used.  To keep track of all of the selections, we need to put them into a temporary placeholder, and then traverse thru them one at a time, checking and changing the suppression state.  In the case of improper selections, we can filter the selections before storing them.  This is a needed enhancement to the macro, and it was a big change to the code. 

Don’t forget, if you would like to follow along with what I did, you can download the sample models and macros here. 

You can download the finished macro here. 

Even the “finished” macro is not complete.  This macro will only work if the mates are selected in the feature manager at the left.  It may not work if a mate dimension has been selected in the graphics window.  This macro also does not ensure that the user selected a mate in the top level of the assembly.

Conclusion:

This tutorial stems from a discussion that brought on a few comments like “My recorded macro does not work when I run it again.” or “How and where do I start writing a macro?” and “Where can I find help on writing a macro for SolidWorks?”

When you write a macro, follow these simple steps:

• Record a macro to “discover” API calls you may need.
• Study the recorded macro to “discover” how and when things happen.
• Upgrade the recorded macro to make it more “universal” and capable of working with other models and features.
• Add additional code to expand on the macro’s functionality. (ex: multiple pre-select)
• Add your user interface, if needed.  Again, start small, test functions, and work your way up.
• Add code to accommodate improper selections.
• Let it loose and see how others use the macro.
• Be ready to add updates as problems are “discovered”.

When is any macro actually done?  It can be done as soon as you get it to work as expected, or it may not be done until it has been “idiot-proofed” meaning that you have thought of, and added code to accommodate all of the potential ways the macro could be misused (intentional or not).  This decision is up to the developer, the user(s), and the environment the macro will be used (or abused) in.  Keep in mind that changes to the SolidWorks API, due to SolidWorks upgrades, may force you to make additional changes to the macro.

You can find a few more macros built on this concept by going to the “Quick and Dirty” (http://www.lennyworks.com/solidworks/default.asp?ID=44) macro page on my website.