Here’s another post in the getting series where we’re looking at the creation of a new sketch command to create slot shapes. I’ll be adding each of the posts in this series to the Getting Started Tutorial category.
This post is more discussion than coding so you will have some background to follow what’s coming next. First, I want to go back to the previous program and look at that code in a bit more detail. The code below is from the previous post with the error handling removed and one of the lines has been broken into two to make it easier to follow what’s happening
1. ' Connect to a running instance of Inventor.
2. Dim invApp As Inventor.Application
3. invApp = System.Runtime.InteropServices.Marshal.GetActiveObject _
4. ("Inventor.Application")
5. ' Get the Documents collection.
6. Dim docs As Inventor.Documents
7. docs = invApp.Documents
8.
9. ' Create a new part document.
10. Dim partDoc As Inventor.PartDocument
11. partDoc = docs.Add(Inventor.DocumentTypeEnum.kPartDocumentObject)
Line 2 declares a variable to be of type Inventor.Application. The “Inventor” portion of the declaration is specifying the library and the “Application” portion is the name of the object. The Inventor API is exposed as objects. You’re already used to this concept since that’s also how Visual Basic works. For example, when you place a button control on a form, that results in the creation of a button object that you can access in your program. The button has properties that you can read and write to manipulate the button. It also has methods you can call and it has events that notify you when certain things happen to the button, like when it is clicked.
Inventor objects have the same concept but instead of representing something on a form, they represent something within Inventor. For example, for every extrude feature in a part there is an ExtrudeFeature object that you can access and use in a program. Inventor is a large and fairly complicated application and the API reflects that. Inventor 2013 has 1365 objects which have a total of 20,462 properties, methods, and events. Don’t let these big numbers discourage you though because you don’t need to understand all of it be able to use it.
These objects are accessed through something known as the object model or object hierarchy. A useful tool in working with the API is the object model chart, which is shown below. You can download a printable pdf version of the chart here.
Below is a snapshot of the upper-left corner of the chart that includes the few objects that are used in the small program discussed here. You can see in the chart that the top-level object is the Application object. This object represents the Inventor application and has functionality that lets you manipulate the entire application; things like resizing the main window and accessing application options. However, the most important thing the Application object does is support properties that return other objects. This is how you gain access to the other objects in the hierarchy. For example, the Application object supports the Documents property which returns the Documents object. This is illustrated in line 7 in the code sample above and that relationship can be seen in the chart below.
You can also view all of the objects and their associated methods, properties, and events from within Visual Basic using the Object Browser. To access the Object Browser in Visual Basic Express 2010, press F2. The Object Browser is shown below, with the Inventor library selected.
Below is the Object Browser with the Documents object selected in the list on the left and the Item property selected on the right. The Object Browser provides a convenient way to see the objects and what functionality they support. You can see in the picture below that the Item property is read-only and has a single argument called Index which is an Integer. You can also see that it returns an Inventor.Document object. (You can ignore the _ character in front of Document. It has something to do with how the API was implemented internally and I don’t understand it either. )
Tip: You can expose additional capabilities in the Visual Basic Express 2010 interface by changing your settings to “Expert Settings” in the “Tools” menu, as shown below. After doing this the “Object Browser” command will be displayed in the “View” menu.
Line 6, in the sample above, declares a variable to be of type Documents. The Documents object is a special type of object known as a collection object. Collection objects are used extensively throughout the API and are an important concept to understand.
Collection objects are utility objects used in the API. They don’t represent specific objects within Inventor but instead provide access to a group of related objects and in many cases also provide the ability to create new objects. The Documents object illustrates both of these.
The Documents object provides access to all of the documents that are currently open in Inventor. All collection objects support the properties Count and Item. The Count property tells you how many items are in the collection and the Item property lets you access the items within the collection. If you add the following to the end of the previous program it will display a message box telling you how many documents are currently open.
' Display the number of documents.
MessageBox.Show("There are " & docs.Count & " documents open.")
You use the Item property of a collection to get a specific object from the collection. This is somewhat similar to an array but the first item has in index of 1. Some collections will also let you specify the name of the object you want. The code below uses both the Count and the Item properties of the Documents object to iterate over all of the open documents and display the name of each one in the output window. (You may need to turn on the display of the output window from the menu “View –> Other Windows –> Output” or “Ctrl + Alt + O”.)
' Iterate over the open documents
For i As Integer = 1 To docs.Count
Debug.Print("Doc Name: " & docs.Item(i).DisplayName)
Next
If you’re iterating through a collection a more efficient technique for is to use the For Next statement. Code using a For Each vs. the For To will typically run faster and is easier to read. This is demonstrated below.
' Iterate over the open documents
For Each doc As Inventor.Document In docs
Debug.Print("Doc: " & doc.DisplayName)
Next
The Item property of the Documents collection does not support indexing by name. You can determine which Item properties do support this by looking at the description of the property in the API help. The Documents object supports a separate property for named lookup called ItemByName where instead of providing the index number you supply the filename of the document. If you specify an out of range number or a name that doesn’t exist the call will fail.
Adding objects to a collection is done by using the Add methods of the collection. This was demonstrated in the original program above in line 11 where the Add method is called. Some collections won’t have any add methods and others will have several. The arguments to the add methods will also vary greatly depending on what is being created. It’s takes much different information to create a new document versus creating a new extrude feature.
We’ll look at practical applications of collection objects and using them to create new objects in the upcoming posts. In the next post I’ll talk about creating sketches.
Another useful tool to look at Inventor’s objects is VBA’s debugger. I’ve described this in a previous post on program prototyping.
Subscribe
