beginning api

8/8/2019 Beginning API

1/16

Mod the Machine

Beginning API

October 10, 2008

Program Prototyping

In some of the previous postings I've talked about some of the advantages and disadvantages of the variouslanguages. One thing I mentioned was the use of VBA to prototype programs. A colleague stopped by my office earlier today asking for some help with a program he's writing for a customer. Apparently the customer,and now him, have been struggling with getting the program to work.

Here's a simplified description of what they were trying to do. While working in a drawing that containsretrieved dimensions they want to be able to get to the associated tolerance information from the part. I didn'timmediately know the answer to this either but was able to figure it out in a couple of minutes. The reason I was able to do this is because I know how to use VBA as a prototyping tool. The good part is that you can learnhow too. It's an extremely powerful tool when programming Inventor that you can take advantage of regardless of what language you're writing your program in.

I'll go through the procedure step-by-step that I used to figure out the solution to this specific problem. Although this looks at a specific case, the principles demonstrated here are generally applicable to any case.Below is the example for this case for this case which consists of a drawing view with three retrieveddimensions. Given a dimension we want to get the tolerance information from the associated parameter inthe model.

1. Have Inventor running with the document open that contains the type of data you want to query.2. Select the object you're interested in. In this case it's one of the dimensions.3. Open the VBA environment and write the following code. (I would write it in a module in your

application project then you can use it again later.)Public Sub DebugObject()

Dim oDoc As DocumentSet oDoc = ThisApplication.ActiveDocumentDim oObj As ObjectSet oObj = oDoc.SelectSet.Item(1)Stop

End Sub

4. Run the VBA macro. You'll get an error like the one shown below if there isn't an entity selected. Juststop the program, select the desired entity and run it again.

Page 1 of 16Mod the Machine: Beginning API

28/9/2010http://modthemachine.typepad.com/my_weblog/begging-api/


2/16

5. The macro will stop execution at the Stop statement. (You could have also put a break in the code but

the Stop statement is convenient.)6. Right-click the mouse anywhere within the variable oObj and select the "Add Watch..." command.

7. Click OK and accept the defaults in the "Add Watch" dialog.

8. The Watch window should appear, if it wasn't already shown, and the variable "oObj" will be displayed.The watch window shows three interesting things; Expression, Value, and Type. The expression is the

variable or property we're watching, the value is the value of that expression, and the type is the type of the variable or object the expression results in. In this example we can see the type of oObj is aDiameterGeneralDimension. You'll often see object types prefixed with "IRx" and you can just ignore theprefix. The Value is empty because a DiameterGeneralDimension doesn't have an explicit value.




3/16

9. Click on the "+" next to oObj to expand the object. Now all of the properties of theDiameterGeneralDimension are displayed. Each property also shows it's value and type. Some of theproperties return objects and have a "+" next to them so you can expand them and see the properties

associated with that object. In this case there are two properties that are interesting for the problem we'retrying to solve; Retrieved and RetrievedFrom. The Retrieved property indicates if this drawingdimension was created by retrieving a dimension from the model. You can see in the debug window thatthe value is True for the currently selected dimension. The RetrievedFrom property returns the modeldimension this was retrieved from. In this case the type of object returned is a FeatureDimension.

0. Expanding the RetrievedFrom property you see the properties of the FeatureDimension object. One of these is the Parameter property which returns a ModelParameter object. Expanding this we can see theTolerance property. Finally, expanding on this we can see the upper and lower tolerance values. All of this is shown below.




4/16

11. Here's the corresponding code that was written based on what was learned from the debugger window.

Public Sub GetDimTolerance()' Get the active document. Assumes it's a drawing.Dim oDrawDoc As DrawingDocumentSet oDrawDoc = ThisApplication.ActiveDocument

' Get the selected dimension, with error handling to' gracefully error out if a dimension isn't selected.On Error Resume NextDim oDim As GeneralDimensionSet oDim = oDrawDoc.SelectSet.Item(1)If Err Then

MsgBox "A drawing dimension must be selected."Exit Sub

End If

' Check to see if the selected dimension was retrieved.If oDim.Retrieved Then

' Get the associated model dimension.Dim oFeatureDim As FeatureDimensionSet oFeatureDim = oDim.RetrievedFrom

' Get the associated model tolerance.Dim oTol As ToleranceSet oTol = oDim.RetrievedFrom.Parameter.Tolerance

' Display the tolerance value.Debug.Print "Tol: " & oTol.Upper & "/" & oTol.Lower




5/16

End IfEnd Sub

The specifics of what the code is doing in this case isn't important but the method we used to arrived at thiscode is. The debug window provides a "live" view of the object model that you can traverse through to see how

objects are connected through their various properties. Anytime you want to investigate how to use the API toaccess a certain object or to get to particular information.

Posted at 02:48 PM in Beginning API | Permalink | Comments (2) | TrackBack (0)

September 29, 2008

BA Document Projects

Inventor's implementation of VBA supports two types of VBA projects; document projects and externalprojects. They're defined by where the project is saved. Document VBA projects are saved within Inventordocuments, parts, assemblies, etc. External projects are saved as individual .ivb files. Using the File tab of the

Application Options dialog you can specify one external project to be loaded automatically when Inventorstarts up. This VBA project is frequently referred to as the application project .

When VBA was integrated into Inventor we looked at other VBA integrations for ideas. All of the applicationsthat supported VBA that I had used at the time all used the idea of document projects so it seemed like that was something we needed to provide as part of Inventor's implementation. However, when I had used someof these applications that only had document projects I didn't like them because it made maintaining codealmost impossible. For example, I was writing a reasonably large program in one of the applications and it was stored within a document. I would copy that document to use the program with other sets of data. WhenI wanted to make a fix or enhancement to the program I had multiple copies of it and didn't know which

version of the program existed where. As a result of this frustration we also added support for externalprojects in Inventor's implementation of VBA.

A feature of the document macros that Word and Excel supported that seemed good was the idea of automaticmacros. These are macros with a particular name that are run automatically when something happens in theapplication. For example, when a document is opened or saved a macro is run. This functionality makes it very easy for someone with limited programming experience to write a simple macro to respond to theseevents in Inventor.

A couple of releases after we added VBA to Inventor we started getting reports of some problems. Theproblem turned out to be a resource issue with VBA. People were creating document projects that usedautomatic macros and were using these Inventor documents that contained these projects as their templates.That meant that every file they created had a VBA document project. When a large assembly is loaded all of the referenced documents are also loaded, and in the case of these documents also meant loading theembedded VBA projects. It turns out that VBA has a limit to the number of VBA projects that can be loaded.

The other significant problem to having document macros in a template is that it creates the problem I already talked about of having your program duplicated in all your documents making it very difficult to fix orenhance that program. There is also another problem that recently came up with document projects and 64 bit Inventor.

My advice is: DO NOT USE document projects . The one exception to this is if you're writing a programthat is very specific to a single document. For example if you have a part and write a specific program to work

with only that part. In this case it's convenient to package the program with the document rather than worry about passing an additional file with it.




6/16

External VBA projects should provide most of the functionality you would want and also provide theadditional capability that you can create toolbar buttons to run the macros contained within them. Whatexternal VBA projects don't provide is the ability to do the equivalent of automatic macros. The best answerfor this is to create an Add-In. (There have been some Add-In utilities written that add support for automaticmacros to VBA external projects but I 've found for most people that these end up being confusing becausethey don't understand how they work and as a result don't know how to debug and diagnose problems whenthey occur.) An Add-In allows you to do anything you could do in VBA and more. The downside of an Add-Inis that there's a higher learning curve to getting started.

In my next posting I'll cover what's required to create an Add-In that replaces an existing automatic macro.

Posted at 11:34 AM in Beginning API, Visual Basic for Applications (VBA) | Permalink | Comments (1) |TrackBack (0)

September 22, 2008

Inventor API Fundamentals 004 - Connecting to the API

In the last posting I discussed the object model and that it provides a structured way to access the variousobjects that make up Inventors API. In order to use the object model you need to do two things; reference thelibrary that describes Inventors object model and gain access to the Application object. (The Applicationobject is the top-most object in the object model and through it you can access all the other objects.)

How you reference the API and access the Application object will differ slightly for the different languages.These are discussed below along with example code that demonstrates getting the Application object andcalling its Caption property.

Inventors VBA

Because the VBA thats delivered with Inventor is integrated with Inventor, it provides the easiest access toInventors object model. In Inventor's VBA, the Inventor API library is already referenced and it provides aneasy way of accessing the Application object by providing a global property called ThisApplication , whichreturns the Application object. All you need to display Inventors caption with Inventors VBA is the code below.

MsgBox ThisApplication.Caption

External Application External Application refers to any application that runs outside of Inventor. Typically these are Windowsapplications (.exe programs) but this also includes VBA programs written using VBA in another application(i.e. Word or Excel). This term does not refer to Add-In applications.

How you Reference Inventors API varies for each of the programming environments and is discussed below for each one. The mechanics of gaining access to the Application object also varies with the differentprogramming languages; however, for all languages there are two basic ways to connect. The first is to see if Inventor is running and get the Application object associated with it. The second is to start Inventor and getthe associated Application object. Both are useful and which one to use depends on what youre trying toaccomplish. Connecting to a running instance of Inventor is probably the most common. Starting Inventor iscommon for batch processing types of programs.

VBA / VB 6

Referencing the API




7/16

Use the References command (in the Tools menu in VBA and the Project menu in VB 6) to add a referenceto Inventors object library, as shown below.

Referencing the Inventor Object Library in VBA and VB 6.

Connecting to a Running Instance of Inventor

Dim inventorApp As Inventor.Application

' Attempt to get a reference to a running instance of Inventor.On Error Resume NextSet inventorApp = GetObject(, "Inventor.Application")If Err Then

MsgBox "Inventor must be running."Exit Sub

End If

On Error GoTo 0

MsgBox inventorApp.Caption

Starting an Instance of Inventor


On Error Resume NextSet inventorApp = CreateObject("Inventor.Application")If Err Then

MsgBox "Error starting Inventor."Exit Sub

End IfOn Error GoTo 0

' Make Inventor visible. inventorApp.Visible = True

MsgBox inventorApp.Caption

VB.Net

Referencing the API The .Net languages use something called an interop assembly to be able to call a COM Automation API. WithInventor 2009, Inventor installs an interop assembly (Primary Interop Assembly or PIA) for all developers to

use. You reference this into your application using the Add Reference command and selecting Autodesk.Inventor.Interop from the .Net tab as shown below.




8/16

Referencing the Inventor Object Library in VB.Net

For versions of Inventor previous to Inventor 2009 you need to select Autodesk Inventor Object Libraryfrom the COM tab of the Add Reference dialog. This will generate a local interop assembly for your project.

Referencing the Inventor Object Library in VB.Net (Inventor 2008 and earlier)

Connecting to a Running Instance of Inventor The VBA / VB6 code above will work in VB.Net, but VB.Net also provides the try catch style of error handling which is usually nicer than the older On Error error handling.


' Attempt to get a reference to a running instance of Inventor. Try

inventorApp = GetObject(, "Inventor.Application")Catch ex As Exception

MsgBox("Inventor must be running.")Exit Sub

End Try

MsgBox(inventorApp.Caption)

Starting an Instance of Inventor Dim inventorApp As Inventor.Application




9/16


10/16

Referencing the API for an unmanaged VC++ project is done by including a header file provided by InventorsSDK. This header file imports Inventors object library and includes some other useful header files.

#include "InventorUtils.h"

Connecting to a Running Instance of Inventor There are different flavors of VC++ (managed and unmanaged) and different ways to use Inventors API from VC++. The samples below represent one style.

HRESULT Result = NOERROR;

CLSID inventorClsid;Result = CLSIDFromProgID (L"Inventor.Application", &inventorClsid);if (FAILED(Result)) return Result;

CComPtr pInventorAppUknown;Result = ::GetActiveObject (inventorClsid, NULL, &pInventorAppUknown);if (FAILED (Result)){

MessageBox(0, _T("Could not connect to Inventor."), _T("Error"), 0);return Result;

}

// QueryInterface for the Inventor Application object. CComPtr pInventorApp;Result = pInventorAppUknown->QueryInterface(__uuidof(Application),

(void **) &pInventorApp);if (FAILED(Result)) return Result;// Get and display the caption. CComBSTR bstrCaption;Result = pInventorApp->get_Caption(&bstrCaption);if (SUCCEEDED(Result))

MessageBox(0, bstrCaption, _T("Inventor Caption"), 0);

Starting an Instance of Inventor

HRESULT Result = NOERROR;

CLSID inventorClsid;Result = CLSIDFromProgID (L"Inventor.Application", &inventorClsid);if (FAILED(Result)) return Result;

CComPtr pInventorAppUknown;Result = CoCreateInstance(inventorClsid, NULL, CLSCTX_LOCAL_SERVER,

__uuidof(IUnknown), (void **) &pInventorAppUknown);if (FAILED (Result)) {

MessageBox(0, _T("Could not start Inventor."), _T("Error"), 0);return Result;}

// QueryInterface for the Inventor Application object. CComPtr pInventorApp;Result = pInventorAppUknown->QueryInterface(__uuidof(Application),

(void **) &pInventorApp);if (FAILED(Result)) return Result;

// Make Inventor visible. pInventorApp->Visible = VARIANT_TRUE;

// Get and display the caption. CComBSTR bstrCaption;Result = pInventorApp->get_Caption(&bstrCaption);




11/16

if (SUCCEEDED(Result))MessageBox(0, bstrCaption, _T("Inventor Caption"), 0);


September 11, 2008

Inventor API Fundamentals 003 - The Object Model

As discussed in the previous post , Inventor exposes its programming interface using COM Automationtechnology. A COM Automation interface is an object oriented type of interface. This means the API defines aset of objects and these objects have various functions (methods and properties) that allow you to query, edit,and create new objects. For Inventors API, most of the API objects will already be familiar to you becausethey represent the same things youre working with when you use Inventor interactively, (which is why it'simportant to have a good knowledge of Inventor before attempting to use the API). For example, in the APIthere is a Parameter object that represents a parameter in a part or assembly. The Parameter object supportsmethods and properties that allows you to query and edit the parameter it represents. For example, a

Parameter object has a property called Name that will return the name of the parameter and you can set the value of the property to change the name of the parameter.

The Object Model is an important concept to understand in order user the API. The API objects are linkedtogether in a logical way. In order to get a certain object you need to understand how they're linked because you'll need to go from one object to another to get to a specific object. The structure of the objects is referredto as the object model. The object model is typically represented as a hierarchal chart that shows therelationship between objects. If youre familiar with C++ class diagrams, this IS NOT the same as that. It doesnot show a class hierarchy but illustrates an ownership hierarchy. For example, a dimension constraint isowned by a sketch, it's not derived from the sketch. If you have a reference to an API object you should beable to traverse the object model to access any other object as long as you understand the structure of theobject model.

There are a few tools available to help you view and understand this object model:

Object Model Chart This is a chart that illustrates the object hierarchy. Its most useful in a hardcopy form because of it's size it's hard to view on a computer screen. Initially, it can look a bitoverwhelming because there are so many objects but because youll typically just be using a few objects

within a certain area of the API you'll end up learning it in small pieces.

Object Model Chart (click to expand in a new window)




12/16

This chart is delivered as part of the Inventor API SDK (Software Development Kit) but you can alsodownload it here.

Online Help Part of the programming help thats delivered with Inventor contains a description of every object along with details about the methods, properties, and events each object supports. You access

the programming help from the Help menu in Inventor.

Inventor API Programming Help (click to expand in a new window)

Object Browser The object browser is a user-interface for viewing the objects and their associatedmethods and properties. Object browsers exist in various forms in the different languages but the object

browser that's part of VBA is probably the best for viewing Inventor's objects. From within VBA you show

the object browser by running the Object Browser command (F2). The drop-down in the upper-left of theObject Browser dialog lets you choose which programming library you want to view. The field below thatallows you to search the library. The dialog contains two main areas. The one of the left is a list of all of the objects in the selected library. When you select an object, the area on the right shows the methods andproperties of that object. Selecting a method or property will display specific information about it at the

bottom of the dialog.




13/16

VBA Object Browser (click to expand in a new window)

VBA Debugger The VBA debugger is also useful outside of the normal context of debugging aprogram. Because of VBAs support of COM Automation it allows you to examine live objects and theirproperties while traversing through multiple levels of the object model. This is an extremely powerful and

useful tool no matter what language youre using, and well worth learning how to use.

If you're unfamiliar with debugging in VBA, here's a crash course.

1. Have Inventor running and a part open that contains a few features.2. Open Inventor's VBA development environment (Alt-F11).3. Double-click on a module in a project to open a code window. In the picture below it's Module1 from

the ApplicationProject.4. Create the Sub as shown in the picture below.5. Position the cursor anywhere within the Sub you just wrote and press F8 to start debugging.6. Right-click the mouse over ThisApplication and choose "Add Watch..." from the context menu. Click

OK on the Add Watch dialog.

Using the VBA Debugger (click to expand in a new window)

7. VBA will open the Watches window with the variable you selected displayed in the window, as shown below. The object shown in this example is the Application object. The Application object representsthe entire Inventor application and is the top most object in the object model. You can click the "+"

next to the name to expand the object to show its properties. Each property shows its current value,or if the property returns another object it will have a "+" next to it. You can traverse through thehierarchy by expanding the plus signs.

This provides a live view of the object model. In the example below, the ActiveDocument property isexpanded to show the currently active document. For a part, most of the interesting information iscontained within an object called PartComponentDefinition which is returned by theComponentDefinition property of the PartDocument. You'll see this object provides access toparameters, features, and other part related objects. Playing with this, along with the object modelchart, you can get a better understanding of the object model.




14/16

VBA Watch Window (click to expand in a new window)


September 10, 2008

Inventor API Fundamentals 002 - Choosing a Language

To program Inventor you need to use some type of programming language. The good and the bad news is thatthere are a lot of choices. Its good because it provides flexibility for everyone to choose something they likeand best fits their requirements. Its bad because you have to make a choice and if youre new to all of this youmay not know what to look for in making that choice. Discussing computer languages can be a dangeroustopic because people tend to have strong opinions and can be passionate about their language of choice. In

reading any of the following, just remember that its my opinion.For learning Inventors API, I believe you should use Inventor's VBA (Visual Basic for Applications). Im notsaying its the best language to use when writing applications for Inventor, but I think it is the best for learningand experimenting with the API.

When programming Inventor, Inventor doesnt care which language you use. Inventor exposes itsprogramming interface using Microsoft technology called COM Automation . This technology provides aformalized way to describe the details of a programming interface in a generic way. When you call an Inventor API function the call goes through this Automation interface and when Inventor receives the call it doesnteven know what programming language the call came from. The only language requirement whenprogramming Inventor is that it supports COM Automation, which most languages do.

My reason for recommending VBA is because VBA was designed specifically for programming COM Automation interfaces. Because of this there are two big advantages to using VBA; the Object Browser anddebugging. The Object Browser is a tool within VBA that allows you to look at the objects and functionsprovided by an API. Other languages also provide object browsing functionality but they dont work as well asthe VBA browser for viewing COM Automation interfaces. As far as debugging, almost all languages supportthe ability to debug your programs; however VBA supports better debugging a COM Automation interface by allowing you to view more details about objects. Another point in VBAs favor is thats it integrated withInventor, which means if you have Inventor you have VBA. This integration also makes it easier to accessInventors API than when using any other language. One other advantage is that the API samples in theonline help are currently all written in VBA.

All of the reasons Ive listed above make VBA an easier language to use when learning the API and even later




15/16

when prototyping and investigating the capabilities of the API. No matter what your programming experienceand language preferences I highly recommend gaining a basic understanding of VBA because I believe it will benefit your overall programming efficiency when programming Inventors API. You can think of VBA as astyle of pseudo-code that you can run and test. The API principles you learn with VBA aren't language specificand are easily transferred to any other language.

Even with the advantages of using VBA discussed above, I dont recommend VBA for writing an Application.It's ok for small macros but for larger work there are better choices. All languages have pros and cons and VBAs cons dont make it the best language for writing applications. My current personal choice for writingapplications is Visual Basic .Net, which Visual Basic 2008 is the most current version. My choice of VisualBasic over most of the other available languages is primarily personal preference but there are a couple of reasons I would also recommend it to a newer programmer. First, it provides an easier upgrade path from VBA and second, I believe it is easier to use than the other languages.

One version of Visual Basic worth spending a little time discussing here is Visual Basic 6. Many of the existinglarger samples provided with Inventor's SDK were written using VB 6. This is an older version of the Visual

Basic language and has many of the same advantages as VBA since it uses the same underlying engine. It wasmade to program COM Automation types of programming interfaces and has the same object browser anddebugging support that VBA has. A big problem with VB 6 is that it has been discontinued and is no longeravailable from Microsoft. It also does not support writing applications for 64 bit Windows. If youre going tomake the effort to learn a programming language it doesnt seem very good to spend your time learning and writing a lot of code with an obsolete language. Becuase of that I cant recommend using VB 6.

The .Net languages, C# and Visual Basic, both support COM Automation programming. Even though they both have the object browser tool and support debugging they don't work as well as they do in VBA. However,they have a lot of other advantages over VBA (and VB 6) that makes them a better choice for larger applicationdevelopment. Whether you choose Visual Basic or C# is really just personal preference.

The other popular language, primarily with professional developers, is Visual C++. Visual C++ is a very powerful language but is also difficult to learn and use. It supports programming a COM Automationinterface but is significantly harder than either Visual Basic or C# to use. If you choose to use Visual C++ youcan expect a higher learning curve and longer development times.

Finally, there are a few fringe languages. Some of these have been around for a long time, (i.e. Delphi), andothers are relatively new (i.e. Python). As I said earlier, Inventor doesnt know or care what language youreusing and you can use whatever you choose. However, youll have a hard time finding any samples or support when using these languages. For me, theyre interesting to look at but at this point I would be hesitant to begin a large development project using any of them.

No matter what language you choose I still recommend using VBA for prototyping investigating the API. Forthe rest of this series of articles Ill be using VBA to demonstrate the use of the API. Where there are actualdifferences when using other languages with Inventors API, Ill try and have code that demonstrates thosedifferences and whats needed in the various languages to get things to work.

Posted at 07:42 AM in Beginning API | Permalink | Comments (2) | TrackBack (0)

August 21, 2008

Inventor API Fundamentals 001 - Getting Started

I plan on having a series of posts that are intended for those of you that are new to programming and/orInventor's programming interface and want to get started writing programs for Inventor. I'll also break in on




16/16

the series occasionally with various other topics that are usually more advanced or that I find interesting at themoment. This post is the first in the getting started series. Here is the process I would suggest for anyone wanting to program Inventor.

1. Learn how to use Inventor interactively. This is more important than you might think. Most of

Inventors programming interface is just an alternative way of doing the same things you do interactively through the user-interface. For example, if you create an extrude feature through the user-interface yousee the required input; profile, solid or surface output, operation, extent information, and taper angle.

You supply all of this information through the Extrude dialog and by interacting with the model. Tocreate an Extrude through the API you call a method that has exactly the same type of input. The sameset of information is being gathered by both the command (user-interface) and the programminginterface and then both interfaces end up calling the same internal function to create the actual extrusion.

Understanding how Inventor works and the requirements for the various commands is easiest to learnthrough the user-interface. Since these same concepts also apply when using the programming interface

it will make learning the programming interface much easier.

2. Choose and learn a programming language. To effectively program you need to have a basicunderstanding of the programming language youre using. To effectively customize Inventor you DONOT need to be an expert in that language. Any language has a lot of features and intricacies that youcould spend more time than most of us have learning them. A basic understanding of the languageshould be enough. In my next posting Ill discuss several different languages and the pros and cons of each.

3. Begin learning Inventors programming interface. There are some basic concepts to learn to get started

and then you can expand into different functional areas of Inventor. You dont need to learn the entire API at once. Looking at different areas of the Inventor's API will be a running theme of this blog.

So, for now just keep working with Inventor and well look at programming languages next time.

Posted at 10:00 AM in Beginning API | Permalink | Comments (0) | TrackBack (0)


beginning api

Documents