Once you’ve installed RevitLookup, how do you use it to explore the Revit API?
In this post, I’m going to show you how to use RevitLookup to explore the Properties and Methods of your Revit elements. Being able to explore the Revit API with RevitLookup will make it much easier to code in Dynamo, Python or in PropertyWizard.
For this example, you just need a Revit model that contains a door.
You’ll see that RevitLookup has one button on the Add-Ins tab of the ribbon. If you press the button, you get a drop-down menu:
There are lots of options here that I’ll explain another time. In this post I’m going to focus on ‘Snoop Current Selection’.
It’s a bit awkward to use because first you have to select something in Revit – which will flip the ribbon to the Modify tab – so then you have to switch back to the Add-Ins tab, click the RevitLookup button and choose ‘Snoop Current Selection’.
Nevertheless, if you select your door in Revit and choose ‘Snoop Current Selection’ from the RevitLookup menu, you should get a Snoop Objects window like this:
The left pane of the window lists the door you selected. In the Revit API, a door is a ‘FamilyInstance’, and RevitLookup identifies the door by its Name and ElementID.
The right pane lists the door’s API Properties and Methods and their values. This is the heart of RevitLookup.
Values in RevitLookup
You will see four kinds of values in the right pane:
- Simple values, which are shown in normal text
- API object references, shown in bold
- empty values, shown as <null>
- error values, shown in red text
Simple values are straightforward – for example the door’s ‘Id’ value is its ElementId, and its ‘Pinned’ value is False, which means that it isn’t pinned.
API object references are an invitation to explore further – if you click on them, RevitLookup will open another Snoop window that shows the new object. By clicking on through, you can explore further and further into the Revit database.
Empty, null values are just that – they mean that there’s nothing set for that value in the Revit database. For example, the ‘GroupId’ and ‘AssemblyInstanceId’ values are both null for my door – meaning that it isn’t in a group or an assembly.
Error values are where RevitLookup hasn’t been coded to handle that particular API Method or Property. Mostly, these are in relatively obscure or awkward areas and they don’t affect RevitLookup’s usefulness at all.
Properties and Methods
The first two rows of the right pane don’t show values – the first shows the word ‘Element’ on a blue background, and the second says ‘Properties’. What do those mean?
I’ll come back to ‘Element’ next, but if you scroll down you will find a row that just says ‘Methods’. These Properties and Methods rows are sub-headings to distinguish these the two kinds of Revit API value. The difference only really matters when you want to call them from code (e.g. from Dynamo Python). As far as RevitLookup is concerned they are both very similar – it just lists the Properties first and then the Methods.
Similarly, the ‘Element’ row is another kind of heading. If you scroll down further, you will find two more blue rows for the door – ‘Instance’ and ‘FamilyInstance’, each with their own Properties and Methods sub-headings. This is because of the hierarchical, object-oriented nature of the Revit API – and of the .Net Framework it’s built on.
‘Element’ is at the lowest level of the tree and provides the most general Properties and Methods – these are common to all Revit Elements. ‘Instance’ is the next level, and provides a set of more specialised Properties and Methods – these are common to FamilyInstances like the door, but also to Revit Links and CAD Links (RevitLinkInstances and Import Instances respectively). Finally, ‘FamilyInstance’ provides the most specialised Properties and Methods that only make sense for individual instances of families.
So that’s a quick tour round RevitLookup, showing you how to get started exploring the Revit API.
I’ve looked at the ‘Snoop Current Selection’ command that you can use to examine selected elements. I’ve talked about the different kinds of value you can see in RevitLookup, and how you can drill down from one object to another through the object references. And finally, I’ve introduced the object-oriented hierarchy and the specialised sets of properties and methods that you have at each level of the hierarchy.
Next time, I’m planning to explore Parameters in RevitLookup, and then look at some of the other RevitLookup commands. But if you’d be interested in something else, or have any questions, please let me know in the comments.
And, while you’re here, why not take a look at my five-star Revit add-in, PropertyWizard, which lets you add formulas into your Revit projects (like family formulas, but in projects). So hard to describe – so useful in practice!