Getting started with the Vectorworks SDK
I’m not a fan of the stock text note tool in Vectorworks. The best I’ve yet used shipped with PowerCADD 2000. We’re going to make a PowerCADD-inspired Vectorworks text note tool to explore how to develop a simple Vectorworks C++ plug-in.
All source code is MIT-licensed and can be downloaded from Github.
To follow along at home, you will need…
- a Mac running Snow Leopard,
- Vectorworks 2011,
- Xcode, and
- git for getting the source code, best installed through homebrew;
- a smattering of Ruby for build automation and miscellaneous housekeeping; and
- a knowledge of C++ that exceeds mine, which I’d describe as just-enough-to-be-dangerous.
Our project
The PowerCADD text note tool required three clicks to place: first (x,y) is the arrowhead, second gives the (x,y) of the shoulder, and the third gives the (x) of the text point. The (y) of the text point is always the same as the shoulder. Click-click-click-type-done.
Reshaping the note happens by clicking on those same points. Dragging the arrow does what you’d expect. Dragging the shoulder will drag the text along with it, keeping the same relative distance between shoulder and text. Dragging the text is constrained to stay on the same (y) as the shoulder.
As the CAD guy for a mid-sized firm, my preference is to hard-code our tools to work with our own drawing standards. I’d rather make it easy to do the right thing instead of being ‘that guy,’ beating on our drafters about arrowhead styles so that they start to roll their eyes at my approach. Thus, the code here reflects my personal taste in classes, arrowheads and type. While my taste is in fact correct, it also isn’t shared by everyone. Feel free to change these little details.
Why not just use Vectorscript?
You can cobble together something that kinda works for most things using Vectorworks’s other customisation system: Vectorscript. I’ve coded in it for years, and it can get most jobs done more safely.
However, my tastes, skills and ambitions around what I want our CAD system to do have grown. There are a bunch of limitations to Vectorscript that now bug me:
- I want to be able work with multiple files;
- I want to experiment with pulling web-based information into drawings;
- I don’t want to have to keep writing my own version of things that are in the standard library of every common scripting language, eg. strip for strings, push/pop/unshift for arrays, etc. etc;
- I want better source code version control, without unmergeable binary containers;
- I’m tired of there being one obvious function call in a related family of functions be missing or weirdly different;
- I want to be able to do test-driven development; and, really,
- I was pretty much done with Pascal after Computer Camp in the summer of 1985.
There are some elements to the text note project that do benefit from the greater control over UI that the SDK offers. You could make something similar with Vectorscript, but it would have irritating little warts.
Modernity
Browsing through Nemetschek’s docs can be confusing. There’s a major conceptual transition going on in how one structures plugins, the deprecated way hasn’t been excised from the docs, and the new one isn’t yet explained clearly.
Some history: the original incarnation of the SDK was procedural (notwithstanding that it’s all C++). Calls into the Vectorworks app were of the form GS_GetOpacity(gCBP,...): the first parameter was always a global callback pointer gCBP providing a hook back into Vectorworks’ guts at runtime.
The procedural form is deprecated as of Vectorworks 2010. Nemetschek is now pushing an object-oriented form. Calls to the SDK are now method calls of the form gSDK->GetOpacity() on a runtime-defined global C++ object. (Admittedly, it’s a bit tomayto-tomahto. gSDK—an instance of VectorWorks::ISDK—seems to be just a thin God Class wrapper around the old functions).
The new form is an improvement once we start to get into using files, dialogs, and the like. More broadly, the plugin architecture is now being revised to something called Vectorworks Component Object Model (VCOM). I’m probably oversimplifying, but I understand VCOM as just meaning a switch to object-orientation. It replaces the old-style big spaghetti switch statement at the heart of old plugins with hook methods on a supplied object. This pattern is definitely more comfortable to me, since I’m used to seeing it in iOS and Mac OS X code, and encourages the other good things that come from object-orientation: maintainability, reusability, scalability.
In Part 2, we will go over the basic object architecture for our text note plugin, and get set up to start coding.