Description. Learning Objectives. Your AU Expert

Transcription

1 PD17918 Creating Fusion 360 Custom Commands Brian Ekins Autodesk, Inc. Description Go beyond writing simple scripts with Fusion 360 and learn how to create powerful interactive custom commands. We ll begin with a brief introduction to Fusion 360 s programming interface, and then dig deeper into Fusion 360 s programming interface to cover the details of creating add-ins and commands. We'll look at taking an existing script and converting it to a command within an add-in. The command will use a custom dialog to get various types of inputs from the user and provide an interactive preview of the results. Finally, it will create the result as a single operation so it can be undone by one undo operation. Learning Objectives Understand the difference between scripts and add-ins. Understand how to implement Fusion 360 events. Understand how to use the different Fusion 360 command inputs. Understand the capabilities of Fusion 360 commands. Your AU Expert Brian began working in the CAD industry in the early 80 s, and he has worked in various positions, including CAD administrator, applications engineer, instructor, CAD API (application programming interface) designer, and consultant. As an applications engineer, he specialized in modeling complex forms (boat hulls, jewelry, shoes, etc.) and customizing the software to better fit customer requirements. He moved into API design, where he designed the programming interface for Solid Edge software, and he has worked for Autodesk, Inc., since 1998, where he is the designer of the programming interfaces for Inventor and is now focusing on Fusion 360 software. Brian also uses the software himself to design and build furniture at home.

2 This course provides a quick introduction to Fusion 360 s API and the ability to create custom commands. Fusion Scripts vs. Add-Ins Fusion supports both scripts and add-ins and there is actually very little difference between the two. They both have access to the full functionality of the API. There is one small difference, but it ends up making a big difference in how the two are perceived. The difference is that an add-in is started by Fusion when Fusion starts up. It s a small difference but it allows the user to easily access the commands defined by an add-in, as we ll see later. A script is executed by running the Scripts and Add-Ins command, choosing the script from the list, and clicking Run to execute it. To run the same script again, you need to go through the process all over again. I refer to scripts as Run and done ; they run, do everything they re supposed to do and then they terminate. When an add-in is run automatically by Fusion at start up, the add-in doesn t do very much except define its commands and add them to the Fusion toolbar. It then continues to run in the background waiting for one of its commands to be executed. All of the commands in the MAKE panel are add-in commands except for the 3D Print command, but most people probably assume they are standard Fusion commands. Each of the add-ins was started by Fusion as Fusion was coming up and each add-in created a command definition and added it to the MAKE menu. The add-ins are still running but aren t doing anything except waiting for Fusion to tell it when one of its commands has been executed. Then the add-in performs whatever action that command is supposed to do. Page 1

3 An add-in is not run and done but continues to run throughout the entire session and it makes its commands easily available to the user through the user-interface. A script can also support a command but a script can t create a button in the Fusion toolbar so you to go through the Scripts and Add-Ins command every time you want to run it. So, the real difference between a script and add-in is how you run it, but that makes a big difference to the user and to them a well written add-in command feels just like any standard Fusion command. What is a Command? A command can be defined in both a script and an add-in but they are more commonly used in add-ins just because of the fact that you can create a button to provide easy access to the command. You re already very familiar with what commands are because that s what you use when working with Fusion to do modeling, analysis, and NC. You execute a command, and the command guides you through collecting the needed input, typically by using a dialog, and then it creates the result, which can be undone. The API exposes the same internal command machinery that Fusion is using for its own commands so a custom command created using the API can look and behave like a standard Fusion command. Below is one of the example commands I m using for this presentation. It s a command to create dados and rabbets, which are woodworking joints and are essentially slots cut in boards. The command is implemented in an add-in which adds a button to the MODIFY panel of the toolbar. It uses a dialog to get the needed input from the user which includes the joint type, some selections, and some values, including one that also using a graphics handle to define the offset. A preview of the feature is shown and the result shows up as a single undo operation. Page 2

4 Should I create a Script or Add-In and do I need a command? As you can see above, implementing a command within an add-in can provide a familiar interface to the users of your add-in since they execute it the same as any other command and the command interface is something they re already used to. However, it is more work to write an add-in with a command than it is to do something similar in a script without a command. Here are some guidelines on determining when the extra effort is worth it. How much is the functionality going to be used? Is what you re automating something you do often or is it only for a specific project that you ll only need to use a few times? If it s something you won t use very often and it s likely to be only yourself using it, then I would choose to get by with a rough user-interface in a script. By a rough interface I mean that instead of a dialog it will depend on hard-coded values and several calls to the selectentity function to get any needed selections. In cases like this I ll create a script and not use any of the command functionality. Does the script do a lot of work? For example you might have a script that creates several sketches and a few features. Without a command every API call that adds or changes something in Fusion will result in an item being added to the undo list which means that to undo the entire action of the script will require undoing many steps. A command allows you to combine these into a single undo. Will you use the functionality often? If so, then it s convenient to have it available as a button in the UI instead of always going through the Scripts and Add-Ins command. That requires both an add-in and a command. Is there a lot of user input to be gathered? Having a command with a command dialog makes getting the required input much easier than having multiple selectentity calls and hard-coding values. Will others being using the functionality? If others are going to be using your functionality, an add-in with a command provides a much more professional and easier to use user-interface. Remember that commands can be implemented in both scripts and add-ins but I think if you go to the trouble of creating a command, it s not much more effort to create an add-in to be able to add a button to the user-interface. The Fusion 360 API This presentation focuses on commands in Fusion but to create commands you need to have an understanding of how Fusion s API works. The best place to get started is the online API documentation which you can access from the help menu in Fusion as shown to the right. Page 3

5 The programming portion of the online help is at the bottom of the table of contents in the Programming Interface topic. The Welcome to the Fusion 360 API topic provides information about some other resources. The Fusion 360 API User s Manual provides some overview discussions of various topics including how to create scripts and add-ins, basic concepts of the API, commands, solids, units, etc. This is the best place to get started with the API along with the github site referenced in the Welcome topic that links to several Youtube videos discussing the API. The Fusion 360 API Reference Manual part of the help is really the heart of the documentation. This provides detailed information about all the programming objects and their methods, properties, and events. Many of these topics also link to samples that illustrate their use. There is also the Sample Programs topic that organizes those same samples by topic. In addition to the samples in the help, there are also several samples that are delivered with Fusion that you can access from the Scripts and Add-Ins command dialog. The Scripts and Add-Ins tabs both have a Sample folder with programs that you can run and look at the source code. Fusion can be programmed using Python, JavaScript, and C++. I m going to focus on Python for this presentation because I think it s the best choice for the majority of people using Fusion. Developing the Basic Functionality For me, it s useful to break down the process of creating an add-in and command into smaller conceivable chunks. 1. The first step for me is finding out if Fusion is capable of doing the modeling tasks that I want to accomplish. As an example, let s say we want to create a command that will draw a sphere at every selected vertex, like in the example below for the selected Page 4

6 vertex. The Sphere command can t easily be used in the case below because it requires the selection of a plane to define the position and size of the sphere and none of the faces connected to the vertex in this case are planar. It also wouldn t be convenient if you need to create many spheres. The very first step, before writing any code is to go through the steps manually in Fusion to make sure Fusion is capable of doing what you want and to figure out the workflow needed to accomplish the desired task. As I said earlier, the Sphere command requires a plane to define the position and size of a sphere. The Sphere command is not exposed through the API so we ll need to create a sphere using a Revolve feature. So, we know know to create a sphere we ll need to create a sketch that can be used as input for a Revolve feature. To create a sketch we need to have a plane, and in the example above, there isn t a plane at the needed location, so we need to create one. This is the reason for the existince of construction planes; to create planes at positions to facilitate other modeling operations. In this case we can use the Plane Along Path construction plane creation method because it can handle a path of any shape and it can be positioned at the desired point, although you have to define the Distance input to correctly to have it positioned at the end of the selected edge. Once the construction plane is created then it s fairly simple to draw the sketch and revolve it to create the sphere. Page 5

7 2. Now that we ve figured out how to model the desired geometry in Fusion we can start to figure out if it s possible to do the same thing using the API. I do this by writing a simple script that can perform the action I want. I start with a script so I don t waste time creating an add-in if what I want to do ends up not being possible. I m also starting with a script because a script is simpler and easier to debug than an add-in. So I create a new script. 3. Now it s time to write the code to do the needed task. I ve tried to document below my thought process as I work through solving the problem and the techniques I use to make the process easier. The initial script that Fusion creates looks like this: def run(context): ui = None try: app = adsk.core.application.get() ui = app.userinterface ui.messagebox('hello script') except: if ui: ui.messagebox('failed:\n{}'.format(traceback.format_exc())) I know that I ll be drawing everything in the root component of the active design and that I ll need a vertex so I add code to get those. I use the selectentity method for a simple way to get a selected vertex. def run(context): ui = None try: app = adsk.core.application.get() ui = app.userinterface des = adsk.fusion.design.cast(app.activeproduct) root = des.rootcomponent selection = ui.selectentity('select a vertex', 'Vertices') vert = adsk.fusion.brepvertex.cast(selection.entity) Page 6

8 Notice the use of the cast method when I get the Design and when getting the selected Vertex. This isn t needed for the program to run but is used as a way to tell Spyder what the des and vert variables represent. By doing this Spyder can now give you code hints, like that shown below. My experience is that having the code hints is a huge advantage and saves a lot of time writing the code because you don t have to refer to the help documentation as often, so it s well worth the small amount of extra time to type in the code to do the casting. In the code below, I ve defined the radius by hard-coding the value. That will change later but for now I just want to see if I can get the workflow to work. I also start adding the code to create the construction plane by getting one of the edges connected to the selected vertex and starting to call the setbydistanceonpath method. def run(context): ui = None try: app = adsk.core.application.get() ui = app.userinterface des = adsk.fusion.design.cast(app.activeproduct) root = des.rootcomponent selection = ui.selectentity('select a vertex', 'Vertices') vert = adsk.fusion.brepvertex.cast(selection.entity) radius = 1 # Get one of the edges connected to the vertex. edge = vert.edges.item(0) # Create a construction plane along the edge through the vertex. planeinput = root.constructionplanes.createinput() planeinput.setbydistanceonpath() Page 7

9 Because of the cast when assigning the des variable, Spyder is able to figure out that planeinput is a ConstructionPlaneInput object so I get code hints to know setbydistanceonpath exists and it shows me the names of the method s arguments, as shown below. It s not possible to remember all of the details of all the API methods and in this case I don t remember if the distance argument is a real value or if it requires a ValueInput object. A ValueInput is required when the result is used to create a parameter because a parameter can be defined using a real value or a string and the ValueInput lets you specify either one. To find out if the distance argument is a real value or a ValueInput I need to look at the programming help. I look up the topic ConstructionPlaneInput.setByDistanceOnPath by finding the ConstructionPlaneInput object topic in the table of contents on the left-hand side of the help page and then choosing the setbydistanceonpath method to go to that page where I can confirm that an edge is valid input for the pathentity argument and find that the distance argument requires a ValueInput. I also see that it can be a value between 0 and 1, where 0 is at the start and 1 is at the end. How do I know which value I need to create the construction plane at the end of the curve where the selected vertex is? I need to check to see if the selected vertex is closer to the start or end of the edge and use that information to set the distance to 0 or 1, which is done in the code below. It uses the geometry property of the Vertex object to get a Point3D object for the selected vertex and the vertices at the start and end of the edge and then uses the distanceto method of the Point3D object to determine which end the selected vertex is closer to. Page 8

10 def run(context): ui = None try: app = adsk.core.application.get() ui = app.userinterface des = adsk.fusion.design.cast(app.activeproduct) root = des.rootcomponent selection = ui.selectentity('select a vertex', 'Vertices') vert = adsk.fusion.brepvertex.cast(selection.entity) radius = 1 # Get one of the edges connected to the vertex. edge = vert.edges.item(0) # Determine if the vertex is at the start or end of the edge. if (vert.geometry.distanceto(edge.startvertex.geometry) < vert.geometry.distanceto(edge.endvertex.geometry)): distance = adsk.core.valueinput.createbyreal(0) else: distance = adsk.core.valueinput.createbyreal(1) # Create a construction plane along the edge through the vertex. planeinput = root.constructionplanes.createinput() planeinput.setbydistanceonpath(edge, distance) constplane = root.constructionplanes.add(planeinput) constplane.isvisible = False Because of the way the construction plane was created its origin is at the selected vertex and a sketch created on the construction plane will use that as its origin, which means that the (0, 0, 0) point of the sketch will be at the selected vertex position. If this wasn t true we could still use the modeltosketchspace method to determine where to draw the geometry but it s easier that we don t have to. The code below creates a new sketch and draws a 180 degree arc and a line connecting the ends of the arc and then gets the resulting profile. # Create a sketch and draw the half-circle. sk = root.sketches.add(constplane) arcs = sk.sketchcurves.sketcharcs arc = arcs.addbycenterstartsweep(adsk.core.point3d.create(0,0,0), adsk.core.point3d.create(radius,0,0), math.pi) lines = sk.sketchcurves.sketchlines line = lines.addbytwopoints(arc.startsketchpoint, arc.endsketchpoint) prof = sk.profiles.item(0) Page 9

11 This results in the geometry shown below. Finally, the code below is added to create a revolve feature. # Create the revolution feature. revinput = root.features.revolvefeatures.createinput(prof, line, adsk.fusion.featureoperations.joinfeatureoperation) revinput.setangleextent(false, adsk.core.valueinput.createbyreal(math.pi*2)) rev = root.features.revolvefeatures.add(revinput) The program enables being able to quickly create the model shown below by running the script several times, once for each vertex. If you just need to create spheres at vertices once in a while and nobody else is going to use your program then this script is probably good enough. You can edit the hard-coded radius if you need to and it gets the job done. However, if you ll be using this functionality frequently and/or you want to share it with others there are some things that could be better. Page 10

12 First, is the hard-code radius value. It would be nicer if this can be specified through a userinterface instead of being hard-coded. Second, it s not very convenient to use because you have to run the Scripts and Add-Ins command, find and select the script in the list, and click Run. Third, it results in several items being created in the undo list so it s not simple to get rid of it once it s been created. Depending on how the new functionality will be used you might also want to add some other enhancements like the ability to select multiple vertices at once and grouping the created features in the timeline. By converting this to a command you can make the command available in the toolbar and add the other desired functionality. Before starting the work to create an add-in with the command, I m going to spend a little more time with the script to clean up the code and make it easier to re-use while it s still easier to run and debug as a script. The main change is that I ve broken out the code that does all of the work into the sphereatvertex function. All that s needed is to pass in the component where everything is to be created, the vertex, and the radius. It does the work and returns the first and last items that were added to the timeline, which are the construction plane, and the revolve feature. We ll use this later to group things in the timeline. There are a couple of other things I ve changed that I ve found makes things easier. Notice the creation of the _app and _ui variables at the top of the program. I m defining them here as global variables and using the cast method so that Spyder will know what they represent so it can give me code hints. Those variables get set in the run method and I have to use the global statement to be able to set their value. import adsk.core, adsk.fusion, adsk.cam, traceback import math _app = adsk.core.application.cast(none) _ui = adsk.core.userinterface.cast(none) def run(context): try: global _app, _ui _app = adsk.core.application.get() _ui = _app.userinterface des = adsk.fusion.design.cast(_app.activeproduct) root = des.rootcomponent selection = _ui.selectentity('select a vertex', 'Vertices') vert = adsk.fusion.brepvertex.cast(selection.entity) radius = 1 (startfeature, endfeature) = sphereatvertex(root, vert, radius) except: if _ui: _ui.messagebox('failed:\n{}'.format(traceback.format_exc())) # Draw a sphere in the specific component at the vertex using the radius. def sphereatvertex(comp, vertex, radius): try: # Get one of the edges connected to the vertex. edge = vertex.edges.item(0) # Determine if the vertex is at the start or end of the edge. if (vertex.geometry.distanceto(edge.startvertex.geometry) < vertex.geometry.distanceto(edge.endvertex.geometry)): Page 11

13 distance = adsk.core.valueinput.createbyreal(0) else: distance = adsk.core.valueinput.createbyreal(1) # Create a construction plane along the edge through the vertex. planeinput = comp.constructionplanes.createinput() planeinput.setbydistanceonpath(edge, distance) constplane = comp.constructionplanes.add(planeinput) constplane.isvisible = False # Create a sketch and draw the half-circle. sk = comp.sketches.add(constplane) arcs = sk.sketchcurves.sketcharcs arc = arcs.addbycenterstartsweep(adsk.core.point3d.create(0,0,0), adsk.core.point3d.create(radius,0,0), math.pi) lines = sk.sketchcurves.sketchlines line = lines.addbytwopoints(arc.startsketchpoint, arc.endsketchpoint) prof = sk.profiles.item(0) # Create the revolution feature. revinput = comp.features.revolvefeatures.createinput(prof, line, adsk.fusion.featureoperations.joinfeatureoperation) revinput.setangleextent(false, adsk.core.valueinput.createbyreal(math.pi*2)) rev = comp.features.revolvefeatures.add(revinput) # Return the first and last features created in the timeline. return(constplane, rev) except: _ui.messagebox('failed:\n{}'.format(traceback.format_exc())) Creating the Add-In It s possible to convert a script into an add-in by adding the stop function and editing the.manifest file to contain the add-in specific information, but it s easier to create a new add-in in Fusion and copy your code from the script to the add-in. To create an add-in you use the Scripts and Add-Ins command dialog choosing Add-In, Python, and entering a name for the add-in, as shown to the right. The code for a new add-in looks very similar to the code for a script with the only difference being that now a stop function in addition to the run function. When a script is run, the run function is executed and then the script is done. When an add-in is run, the run function is executed but the add-in continues to run even after the run function has finished and the stop function is called by Fusion when the add-in is stopped by the user or when Fusion is shut down. Page 12

14 Creating a Command You create a command and add it to the user-interface in the run function. If you re add-in is set to run at start-up this happens as Fusion is starting up so you re command will immediately be available to the user. To create a command you first create a CommandDefinition object. This object has all of the information that a command needs to display itself in the user-interface and it also supports the commandcreated event which is what Fusion fires to your add-in when the user clicks on the button to run the command. It s not required, but it s usually best to have an icon for your command. If you don t specify an icon, only the text is displayed and the button can t be promoted to the main toolbar. A command icon is defined by creating a png image file. Actually there are several png images needed to account for the different ways a command is shown. Inside the folder that was created for the add-in I ve added a new Resources folder where I ll keep any images needed for the command. Inside this folder I ve created a SphereAtVertex folder where I ll keep the images for the command button. There are three sizes of images needed; 16x16, 32x32, and 64x64 pixels. The 16x16 image is used in the drop-down and the 32x32 is used when the command has been promoted to the main toolbar as shown for the Extrude command below. To support high density monitors like Apple Retina displays, you should also provide a 64x64 image which is used in place of the 32x32 on a standard display. The 32x32 is used as the 16x16 image in this case. The images I ve created for the command we ve been working on are shown below. You must name the images with the names shown below. The 32x32.png and 16x16@2x.png are the same image but just copied and renamed. The naming indicates that it s to be used as the 16x16 image in a high density display and the 32x32@2x.png is actually the 64x64 image. Below is the code that s added to the run function to create the new command and add a button to the ADD-INS panel. The images above are referenced by referring to the folder that they re in. Notice the reference to SolidScriptsAndAddinsPanel to get the ADD-INS panel. Everything in the UI has a name and can be referenced by name. To learn more about this and to see how to discover these names see the User Interface Customization topic in the API help. Page 13

15 import adsk.core, adsk.fusion, adsk.cam, traceback _app = adsk.core.application.cast(none) _ui = adsk.core.userinterface.cast(none) def run(context): try: global _app, _ui _app = adsk.core.application.get() _ui = _app.userinterface # Create the command definition. cmddef = _ui.commanddefinitions.addbuttondefinition('sphereatvertex', 'Sphere at Vertex', 'Create Sphere at Vertex', 'Resources/SphereAtVertex') # Add the button the ADD-INS panel. addinspanel = _ui.alltoolbarpanels.itembyid('solidscriptsaddinspanel') addinspanel.controls.addcommand(cmddef) except: if _ui: _ui.messagebox('failed:\n{}'.format(traceback.format_exc())) The code above adds the button and the code below is added to the stop function to remove the command and button when the add-in is unloaded. def stop(context): try: cmddef = _ui.commanddefinitions.itembyid('sphereatvertex') if cmddef: cmddef.deleteme() addinspanel = _ui.alltoolbarpanels.itembyid('solidscriptsaddinspanel') control = addinspanel.controls.itembyid('sphereatvertex') if control: control.deleteme() except: if _ui: _ui.messagebox('failed:\n{}'.format(traceback.format_exc())) The result of the code above is that the button shown to the right gets added to the ADD-INS panel and is removed if the add-in is unloaded. The user can also click the arrow beside the command to promote it to display at the top where it will be shown using the larger image. Page 14

16 Debugging Add-Ins I said before that I prefer doing the initial work of getting the basic functionality to work in a script rather than add-in because a script is easier to debug, but it is possible to also debug an add-in and you ll need to do that later in the development process. It s not really much different than debugging a script but there s enough difference that I like starting with a script. Here s the important thing when debugging an add-in. Always start and stop your debugging session using Debug and Stop buttons on the Scripts and Add-ins dialog, as shown below. If you use the commands within Spyder to start and stop an add-in you ll run into problems and will likely have to stop and re-start Fusion to recover. These commands work fine when debugging a script but not with an add-in. Connection to Events The code above creates a new command definition and adds a button to execute it to the toolbar. However, when you click that button nothing will happen because no code has been added to react to the execution of a command. You do that by adding an event handler. When the user clicks your command, Fusion creates a new Command object and fires the commandcreated event. Your add-in needs to have a handler connected to this event so it can react and do the appropriate thing. Events aren t limited to commands but are used in Fusion in many different areas. However, they are an extremely important part of implementing a command. The information below is general information about how to connect to Fusion events using Python. You can find out what events are available by looking at the Fusion API help. For objects that support events, there is an Events section within the topic that lists the events that object Page 15

17 supports. Below is the topic for the CommandDefinition object which shows it supports the commandcreated event. A trick to making it relatively easy to use events is to take advantage of the help documentation. You can implement most of the event code by copying and pasting the code from the help. Below is the Syntax portion of the help for the command created event. Page 16

18 Here are the steps to implementing the code for the commandcreated event. 1. Add the declaration for the handlers variable to the top of your program with the other global variables. This is only needed when using Python and is something you only have to do once because all other events you implement in this the add-in will use his same global variable. import adsk.core, adsk.fusion, adsk.cam, traceback _app = adsk.core.application.cast(none) _ui = adsk.core.userinterface.cast(none) _handlers = [] 2. Add the handler code. Just copy and paste the middle portion of code from the help into your program. It can be copied anywhere within the add-in code. In the example below I ve pasted it before the run function but it could be after too. It just depends on what makes the most sense to you about how to organize your code. You can change the name from MyCommandCreatedHandler to something that makes more sense for your specific case too. We ll replace the contents of the handler later when we do the implementation. _app = adsk.core.application.cast(none) _ui = adsk.core.userinterface.cast(none) _handlers = [] # Event handler for the commandcreated event. class MyCommandCreatedHandler(adsk.core.CommandCreatedEventHandler): def init (self): super(). init () def notify(self, args): eventargs = adsk.core.commandcreatedeventargs.cast(args) # Code to react to the event. _ui.messagebox('in MyCommandCreatedHandler event handler.') def run(context): try: global _app, _ui _app = adsk.core.application.get() _ui = _app.userinterface 3. The next step is to connect the event to the handler. This is done where you have access to the object that supports the event. In this case it makes sense to do it in the run Function because we ve just created the commanddefinition and want to connect to an event it supports to be able to react when the user runs the command. The highlighted code below is what was copied and pasted from the help. If you changed the name of the event handler you ll need to edit the name in green to whatever the new name of the event handler function is. You ll also need to replace commanddefinition_var with whatever the variable name is for you command definition. In this case it s cmddef. Page 17

19 def run(context): try: global _app, _ui _app = adsk.core.application.get() _ui = _app.userinterface _handlers = [] # Create the command definition. cmddef = _ui.commanddefinitions.addbuttondefinition('sphereatvertex', 'Sphere at Vertex', 'Create Sphere at Vertex', 'Resources/SphereAtVertex') # Connect the handler to the event. oncommandcreated = MyCommandCreatedHandler() commanddefinition_var cmddef.commandcreated.add(oncommandcreated) _handlers.append(oncommandcreated) # Add the button the ADD-INS panel. addinspanel = _ui.alltoolbarpanels.itembyid('solidscriptsaddinspanel') addinspanel.controls.addcommand(cmddef) except: if _ui: _ui.messagebox('failed:\n{}'.format(traceback.format_exc())) That s all that s needed. If you run the add-in now and click the button, you should see the message box pop up with the message, In MyCommandCreatedHandler event handler.. This is the same procedure you ll follow to implement any event; create the event handler function and connect the event to the handler. Handling Events The handling of an event is done in your event handler. An important thing here is the information that is passed into the event handler. For all events, an object is passed into the event handler through the args argument that provides more information associated with that event. From the cast statement in the event handler code you pasted from the help, you can infer what type of object is passed in. In the case of the command created event it is a CommandCreatedEventArgs object as shown in blue below. The main thing the CommandCreatedEventArgs object does is provide access to the Command object that was just created. The code below gets the command and the command definition to display the name of the command when it s run. # Event handler for the commandcreated event. class MyCommandCreatedHandler(adsk.core.CommandCreatedEventHandler): def init (self): super(). init () def notify(self, args): eventargs = adsk.core.commandcreatedeventargs.cast(args) cmd = eventargs.command # Code to react to the event. _ui.messagebox('executed: ' + cmd.parentcommanddefinition.name) Page 18

20 Command Dialogs Fusion has its own custom dialog capability that all of the Fusion commands use. If you run any of the Fusion commands and look closely you ll see a lot of things that are common amongst all of the commands. To illustrate, below is the Extrude command dialog. It contains several different inputs of different types all stacked vertically. For example, the top input provides the ability to get selections from the user. The next three and the last one provide a list of options for the user to choose from. The next one gets a distance either by entering it in the dialog or by dragging the widget in the graphics window. The next one gets an angle value entered by the user. Each of these is referred to as a command input. The Command object that is passed into the commandcreated event provides access to a CommandInputs object which supports many add methods to create the various kinds of command inputs. If you define any inputs, then a dialog will be displayed, otherwise no dialog is shown and the command will be immediately executed after the command created event has completed. Below is the modified version of the previous command created event. It now adds two command inputs to define a dialog that has a selection input to get one or more vertices and a value input to get the radius. class MyCommandCreatedHandler(adsk.core.CommandCreatedEventHandler): def init (self): super(). init () def notify(self, args): eventargs = adsk.core.commandcreatedeventargs.cast(args) cmd = eventargs.command inputs = cmd.commandinputs # Connect to command inputs. des = adsk.fusion.design.cast(_app.activeproduct) um = des.unitsmanager global _vertices, _radius _vertices = inputs.addselectioninput('vertices', 'Vertices', 'Select the vertices.') _vertices.addselectionfilter('vertices') _vertices.setselectionlimits(1, 0) _radius = inputs.addvalueinput('radius', 'Radius', um.defaultlengthunits, adsk.core.valueinput.createbystring('1')) Page 19

21 The code above defined the dialog shown to the right. There are a lot of other types of command inputs that you can add to your dialogs. Most of the inputs that you see the Fusion commands using are available through the API. Be sure to see the Command Inputs topic in the API help for the latest list and more details about the various types. Doing the Work Now you have a dialog but clicking OK in the dialog still doesn t do anything because there s another event you need to handle in order to know when to do the work that the command is supposed to do. When the user clicks the OK button it results in Fusion firing the executed event. It s in this event where you can do the work. Any creation done within this event is also wrapped within a single transaction, which means it can be undone with a single undo operation. The Command object supports many command related events and you can choose which ones to connect to depending on what you want your command to do. The code below connects a handler to the executed event within the command created event handler. The initial code for this is done by copying and pasting from the API help. _radius = inputs.addvalueinput('radius', 'Radius', um.defaultlengthunits, adsk.core.valueinput.createbystring('1')) # Connect to command related events. onexecute = MyExecuteHandler() cmd.execute.add(onexecute) _handlers.append(onexecute) And here s the handler for the execute event where it s getting the input values (the selected vertices and the radius) from the command inputs on the dialog and is calling the sphereatvertex function we wrote earlier. Notice that it gets all of the selected vertices and stores them in a list before doing anything else. This is because performing any modeling operations will clear any current selections and they will no longer be available. class MyExecuteHandler(adsk.core.CommandEventHandler): def init (self): super(). init () def notify(self, args): eventargs = adsk.core.commandeventargs.cast(args) # Get the input values. vertices = [] for vertexcount in range(_vertices.selectioncount): vertices.append(_vertices.selection(vertexcount).entity) radius = _radius.value rootcomp = _app.activeproduct.rootcomponent for vertex in vertices: sphereatvertex(rootcomp, vertex, radius) Page 20

22 Now when the command is run, the dialog will be displayed, the user can select any number of vertices, specify the radius, and click OK. The spheres will be created and all of the construction will be grouped together in a single undo, as shown to the right. Showing a Preview Most Fusion commands show you a preview of the expected result before you click OK so you know the current values are correct and you know what to expect. This is also supported for API created commands by using the executepreview event. You can do anything in this event handler that you would normally do. Often this is the same modeling operations you ll perform when the command is executed but it can also be a more simplified preview. Each time the execute preview event is fired, Fusion automatically aborts whatever you created before so you re always starting from scratch. Below is the code in the command created event handler that connects to the execute preview event handler. # Connect to command related events. onexecute = MyExecuteHandler() cmd.execute.add(onexecute) _handlers.append(onexecute) onexecutepreview = MyExecutePreviewHandler() cmd.executepreview.add(onexecutepreview) _handlers.append(onexecutepreview) And here s the execute preview event handler. Notice that it s the same as the execute event handler. class MyExecutePreviewHandler(adsk.core.CommandEventHandler): def init (self): super(). init () def notify(self, args): eventargs = adsk.core.commandeventargs.cast(args) # Get the input values. vertices = [] for vertexcount in range(_vertices.selectioncount): vertices.append(_vertices.selection(vertexcount).entity) radius = _radius.value rootcomp = _app.activeproduct.rootcomponent for vertex in vertices: sphereatvertex(rootcomp, vertex, radius) There s something that s inefficient in this case because the part is modified during the execute preview and then that work is all thrown away and rebuilt again exactly the same in the execute event. You can avoid this by setting the isvalidresult property of the passed in CommandEventArgs object to True. This tells Fusion that the result built in the execute preview can be used as the final result so when the user clicks OK, the execute event won t be fired and Page 21

23 the current result will be used. Of course, if you re drawing a simplified preview then you won t want to set this and will perform the full set of operations in the execute event handler. rootcomp = _app.activeproduct.rootcomponent for vertex in vertices: sphereatvertex(rootcomp, vertex, radius) eventargs.isvalidresult = True Controlling Selections If you look at the implementation of the command created event handler where it creates the selection command input as shown below, it uses the addselectionfilter method to specify that only vertices can be selected. It also uses setselectionlimits method to specify that at least one entity has to be selected. # Connect to command inputs. des = adsk.fusion.design.cast(_app.activeproduct) um = des.unitsmanager global _vertices, _radius _vertices = inputs.addselectioninput('vertices', 'Vertices', 'Select the vertices.') _vertices.addselectionfilter('vertices') _vertices.setselectionlimits(1, 0) _radius = inputs.addvalueinput('radius', 'Radius', um.defaultlengthunits, adsk.core.valueinput.createbystring('1')) Using this you have some control over the selection process but it s very coarse control. In many, probably most, cases this is enough control but in some cases you may need more control than this provides. Using the selection event of the Command object you have complete control of the selection process by dynamically choosing what s selectable as the user moves the mouse over the model. For example, if you want to limit the selection to vertices that only connect linear edges. Below is an implementation for the selection event handler to do this. class MySelectionEventHandler(adsk.core.SelectionEventHandler): def init (self): super(). init () def notify(self, args): eventargs = adsk.core.selectioneventargs.cast(args) # Get the selected vertex. vert = adsk.fusion.brepvertex.cast(eventargs.selection.entity) # Check that all of its edges have line geometry. alllinear = True edge = adsk.fusion.brepedge.cast(none) for edge in vert.edges: if edge.geometry.objecttype!= adsk.core.line3d.classtype(): alllinear = False break if alllinear: eventargs.isselectable = True else: eventargs.isselectable = False Page 22

24 Fusion uses the selection criterion that s been defined on the active selection command input, as discussed above. So in this case, any BRepVertex object is still valid for selection. As the user moves the mouse over the model and move over a vertex, Fusion sees that it is a valid object and fires the selection event. It fires the even before the entity is highlighted so the user doesn t see anything happen. The entity the mouse is over is provided through the entity property of the SelectionEventArgs object. You can now do whatever you need to do to determine if that entity should be available for selection. In this example, it looks at the geometry of the each of the edges that connects to the vertex to see if they re all linear. If you decide the object meets your selection criteria, you set the isselectable property of the SelectionEventArgs to True. Now the entity will highlight indicating it can be selected and the user can select if it they choose. If you set the isselectable property to False, then it s not highlighted and it s not selectable. Mouse and Keyboard Events You can also listen for and respond to various mouse and keyboard events by using other events supported by the Command object. See the Command object topic in the API help for the complete list of what s available. Page 23