ryanmccuaig.net

More Vectorworks TDD

2012-01-06T08:00:00Z

More Vectorworks TDD

Hans Martin Kern has added Part 4 to his discussion of test-driven Tool plug-ins. Feeling inspired to finally finish my own Part 4.

Fri 6 Jan 2012

Test-driven Vectorworks development

2011-08-19T07:00:00Z

Test-driven Vectorworks development

I’m a born-again test-driven developer (where practical), so it thrills me to discover that Hans Martin Kern of extragroup GmbH has written two article series to guide us through the development of C++ plugins for Vectorworks using TDD.

Series one is about creating a Parametric Object: Introduction, Part 1, Part 2, Part 3, Part 4, Part 5, Part 6, Part 7, Epilogue

Series two–still underway–is about creating a Tool: Introduction, Part 1, Part 2, Part 3

Read and learn. Bonus points for the Muppet Show references.

Fri 19 Aug 2011

Getting started with the Vectorworks SDK, Part 3

2011-03-14T07:00:00Z

Getting started with the Vectorworks SDK, Part 3

We have basic plug-in theory covered.

What follows is what you will need to install to play along at home, so please get your tools ready while you breathlessly await Part 4. I shall assume you’re running an Intel Mac with Snow Leopard 10.6.6. (My own hardware is a 2006-era Mac Pro; if you have the juice to run Vectorworks 2011, you have the juice to build plug-ins).

Install Homebrew

This is a useful prerequisite, but not required. There are a few Unix command-line tools you will need. I’ve found Homebrew to be the simplest way to get these installed and keep them up-to-date, since they have to be built from source, many of them depend on other tools, which depend on other tools and libraries, &c.

Install `ack`

You will want ack. Given the transitional state of the official documentation, I seem to spend a lot of time combing C++ header files for argument order, return values, examples of function usage, &c. Homebrew provides a command line version with brew install ack, and I also have the AckMate plug-in installed in TextMate. (Note that TextMate is in no way necessary for SDK development, but it’s useful for Vectorscript development).

Install `git` and Gitx

I use git for version control. You will want version control.

(NB: It will start to greatly annoy you that Vectorworks uses pessimistic locking at a grain that makes no sense in architectural teamwork—ie. a file on disk—and offers no version control or design option tools of any kind. This is one of my longstanding hobbyhorses. Feel free to join the cause).

git has a brutal command-line user interface pasted on top of a shockingly elegant, simple conceptual underpinning. Expect pain, but know that it’s worth it in the end. Book some couch time with gitcasts. Installing git is optional, but highly recommended: just brew install git. At a bare minimum, use Subversion should you already know it.

I rely on the open-source Gitx as a GUI. I use the brotherbard fork, which has some nice features that may make their way back into the main line some day. Tower looks promising, but I don’t have any real experience with it.

Any git GUI is unlikely to include every feature of the command-line version, so at least get comfortable with basic operations from the command line, however irritating it may be.

Install `rake`

I use rake to make sure the dozen or so tedious little steps required to build and deploy happen the same way every time. Many tools could work here – including plain old make, or ant if you happen to have a S&M thing for XML – but I’m simply most comfortable with rake. Because Ruby comes stock on Mac OS X, you can install it with a simple sudo gem install rake. Or, you can get fancy with the Ruby Version Manager, as I do; I tend to have several versions of Ruby installed at any one time for my other development projects.

Install Xcode

You will most certainly want Xcode, available from Apple.

(Update: Xcode is now free through the Mac App Store. Ignore the next three paragraphs).

The easiest way to get this is through the Mac App Store, where it’ll run you USD$5. The harder way is to get them as part of a Mac or iOS developer membership (USD$99/year). Regrettably, it’s only as of last week that these developer tools are no longer free. Putting aside for the moment any judgment on the principle of charging at all, I would argue the dev tools are definitely worth more than five bucks.

(It’s worth noting that (a) the sufficiently hardcore, cheap, or doctrinaire among us could build a Vectorworks plug-in using only emacs or vim, gcc and Rezilla, all GPL open source; and (b) life’s pretty short. Go buy Xcode).

Beware: the current version—Xcode 4—is a top-to-bottom rewrite, and is less than a week old as of this writing. For the near future googling whatever particular problem you’re having is likely to turn up stale hints for Xcode 3.

Install the SDK

Finally, the meat: Nemetschek makes the Vectorworks SDK available for free download. Pick the first link. Accept the license agreement, nab the Mac version of SDK 2011 and unzip it. It consists of a giant pile of .h and .cpp files, some sparse documentation, a couple of non-beginner-level sample projects, and .a static libraries that Nemetschek has compiled specifically for Mac OS X. We’ll talk about where to locate the SDK in the source tree in the next part.

In Part 4, we’ll (finally) get down to some actual coding.

Mon 14 Mar 2011

Getting started with the Vectorworks SDK, Part 2

2011-02-28T08:00:00Z

Getting started with the Vectorworks SDK, Part 2

Following on our last instalment, we’ll review the basic Vectorworks plug-in types, and then break down the architecture of our custom text note plug-in.

Regarding plug-ins in general, which you can mostly skip if you know anything at all about Vectorscript development

At application startup, Vectorworks will scan a few directories looking for custom code, namely /Applications/Vectorworks 2011/Plug-ins and ~/Applications/Library Support/Vectorworks/2011.noindex/Plug-ins. If it’s in the right format, it’ll automatically load it and make it available for use in drawings. Much of the core program function is implemented using plug-ins. Most plug-ins will have to be added to a workspace, so that it can be accessed through the UI.

There are 4 generic types of plug-in. Think of them as nouns and verbs. Parametric objects are the nouns. Menu commands, tools, and VectorScript libraries are the verbs.

The nouns

Parametric Objects are graphical objects that exist in the 3D space of the drawing. They can control their own appearance based on user-supplied parameters and some awareness of their context, eg. the drawing scale. They can be relatively simple, like the Break Line, or horrendously complicated, like the Nemetschek-supplied Door, Window, Space and Stair objects.

Unlike VectorScript, the SDK requires you to provide a corresponding Menu or Tool to actually place the Parametric Object in a drawing. This is usually an advantage.

The Parametric Object is sub-typed by its characteristic geometry into Point, Linear, Rectangular, 2D Path and 3D Path Objects. This will mainly define how many draggable control points it has.

The black art of good parametric object design starts in wedging your particular concept into one of these subtypes, based on whether a given parameter ought to be edited graphically or numerically. Much of this guidance is going to come from industry experience. A door, for example, is better defined as a Point object with its width set from a list of valid widths, since door widths tend to come in a continuous range of sizes. A window, on the other hand, is usually built to fit, so it’s better that it be a Linear or 2D Path object that can be edited graphically. It would be nice if there were hard-and-fast rules, but then it wouldn’t be an art. So it goes.

The verbs

Menu commands and Tools are used to provide a user interface to your custom functionality. In general, the choice between them requires a judgment call based on their UI:

use a Menu command if you don’t require any graphical input beyond having drawing objects preselected for action;
use a Tool if you do need graphical input, such as an insertion point, a wall into which you want a Parametric object inserted, etc.

Examples of Menu-type plug-ins would be ones for generating reports or grouping pre-selected objects. As you should expect from the names, Menu commands will be accessed from the menu bar, and Tools will be accessed from the tool palettes. There aren’t hard-and-fast rules here either; many plug-ins could go either way. It sounds a bit dumb, but one of my rules when I’m in doubt is: if I can’t come up with a good icon, it’s probably a Menu.

VectorScript libraries are used to provide new functions within VectorScript. They aren’t expressed within the graphical UI; ie. you can’t put them in a workspace. I find it comforting to know these exist: I can use them to drop down to C++ within an existing VectorScript plug-in to gain capabilities that aren’t present in VectorScript, but without necessarily having to rewrite the entire plug-in using the SDK. But, since that’s about all I know about them, I won’t touch on them further in this tutorial.

Packaging

Plug-ins are packaged as bundles on Mac OS X, with the extension .vwlibrary. Our finished plug-in—and with rare exceptions all modern plug-ins—will have a directory structure like this:

rmTextNote.vwlibrary
└── Contents
      ├── Info.plist
      ├── MacOS
      │   └── rmTextNote
      └── Resources
          └── rmTextNote.qtr

This structure will be produced automatically as part of Xcode’s build process.

Info.plist is mostly OS X-related boilerplate, and will be generated automatically by Xcode. You shouldn’t have to edit it.
Contents/MacOS/rmTextNote is the binary resulting from compiling and linking your C++ source code.
Contents/Resources/rmTextNote.qtr is a resource file containing graphics, user interface strings and the like. It’s split out to make it easier to create versions of your plug-in in different languages. It’s also where you can most see Vectorworks’ lingering 1980s heritage: the file format is that of old ‘rsrc’ resource forks from Mac OS 9 and earlier. You might spelunk them with a modern resource editor, but .qtr resource files will be best created by compiling .r source files using Rez (or Rez.exe on Windows). Rez is installed as part of the OS X developer tools.

(If you see a .vwobject or .vwplugin bundle, you’re probably looking at an old-style plug-in that contains only a Parametric without its corresponding Menu or Tool. My preference is to put all related Parametrics, Menus and Tools in the same .vwlibrary. As the VCOM system takes hold, I expect you’ll start seeing only .vwlibrary bundles).

The anatomy of our text note plug-in

Our text note plug-in will provide both a Parametric object, and a Tool to place it. We will break it down into 6 classes and 5 files.

Somewhere in the plug-in object code there needs to be a plugin_main() function defined. Vectorworks will look for this function at runtime to figure out how it should hook in your code, roughly in the same way as most Unices go hunting about for int main(int argc, char *argv[]) to kick off execution of any code. This is where you tell Vectorworks whether you're building a Menu, Tool, Parametric and/or a Library plug-in. You could stick this pretty much anywhere, but we'll plant this in a file called ModuleMain.cpp. This file will be mostly boilerplate; the overall skeleton will vary little from plug-in to plug-in.
In plugin_main(), we will make reference to two definition classes: one for the Tool, and one for the Parametric. We'll namespace them, so that they can be referred to as Tool::Definition and Parametric::Definition. This is where we'll define the plug-in's name, type, icon, help strings, and Object Info Palette parameters.
Plug-ins will usually sit around waiting for events to be delivered to it by Vectorworks, and invoke various actions in response to those events. Examples would be:
- the user clicks on the Tool in the palette,
- the user edits a Parametric control point or parameter in the Object Info Palette,
- the user moves or rotates a Parametric,
- &c.
Plug-ins used to have one big switch statement at their core, and distinguished between different events by checking an integer constant delivered to it by Vectorworks. The modern way is to define a custom subclass of one of the stock event sink classes supplied in the SDK. If you want to respond to an event, add a custom method for that event. If you don't provide a custom method, Vectorworks will use the one our event sink inherited from the superclass, which usually does nothing. This is usually referred to as the Template Method design pattern, aka. hook methods.

To that end, we will be defining the classes Tool::EventSink and Parametric::EventSink to catch these events. These classes tend to run about 75% boilerplate.
I like to define a separate class that models the specific behaviour of a Parametric, and treat the event sinks mainly as dispatchers. This keeps the logic and parameters related to how a given entity behaves properly encapsulated, and lets us rely on the model class—called RMTextNote in this case—to provide consistent behaviour to either the Tool or Parametric event sink without duplicating code. The alternative is to keep logic in the event sinks. This is low-rent: it's convenient when there isn't much code, but managing the two concerns together—managing incoming events and maintaining the parametric's graphical consistency—gets cumbersome in a hurry.
For expediency, I keep a separate RMUtilities class around. This packages up the snippets that don't yet fit elsewhere, but that I tend to use on many plug-ins. For example, I use it to abstract various office standards, like the name of the initial insertion class. I also keep a lot of the logic related to proper scaling here as class methods. As my stable of plug-ins expands, I may move some of this to an abstract superclass of either the model or the event sinks, but that seems like overkill right now.

Note that instantiating and destroying objects from most of these classes will be handled automatically by Vectorworks. The only one whose life cycle we’ll have to manage is the RMTextNote, which will exist on the heap.

Plug-in parameters

We’ll define 8 parameters for our text note. (Note that Vectorworks will automatically add Rotation to any Parametric). Some of these will be hidden or deactivated in relation to others.

Note is a string parameter that will hold the actual text. Vectorworks internals limit this to 255 characters, but this should be OK: we’re not writing novels here.
Marker is a predefined list, letting us toggle between using a dot and an arrow on the leader. Our office standard is to use a dot, unless pointing at something tiny. This one is set up as radio buttons, defaulting to Dot.
Show Bar In Margin? is a boolean that turns on a vertical bar to help set off the text when it gets to be several lines long.
Wrap Text? is a boolean that specifies if the text should wrap. Turning this on will turn on the display of the next two in the Object Info Palette.
Text Width (page) is a ‘dimension’ parameter, meaning it will take on the units of the current drawing. It only shows when text wrapping is turned on. It defines the width of the text block. We’ll also allow this to be set by dragging a control point in the drawing.
Vertical Alignment is a predefined list: one of (a) First Line, (b) Middle, (c) Last Line. It only shows when wrapping is on, and lets us tweak the wrapped text into a good spot. Usually First Line will suffice. Note that this parameter is shown as a popup menu. It could also have been radio buttons. I tend to use popups for long lists or short but seldom-adjusted lists.
Use Layer Scale? is a boolean that determines if the scale of the containing layer or sheet layer viewport is to be used in figuring out how big the note text and arrowhead should be, since these are measured in paper units. Turning this off will activate the next parameter.
Show at Scale 1 to is a real number parameter (not integer) that can be used to manually set the ratio between world and paper scale. Figuring out the correct scale is a particularly fraught issue in Vectorworks; we’ll spend a good deal of time on it. This parameter isn’t needed often, but it’s handy when the automatic scale determination isn’t doing what you want.

We’ll set the font and size to 8pt Helvetica initially, then allow it to be adjusted after placement from the Text menu like any piece of placed text. This capability is available automatically to any Parametric, provided it has been enabled, so we won’t need parameters for Font and Size.

(I also recommend adding a hidden integer Version parameter at the outset. We won’t use it in this tutorial, but it comes in handy as production plug-ins evolve).

In Part 3, we’ll get our development environment set up, and in Part 4 we’ll create a skeleton plug-in from which we’ll gradually hang working code.

Mon 28 Feb 2011

Getting started with the Vectorworks SDK

2011-02-18T08:00:00Z

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.

ryanmccuaig.net

More Vectorworks TDD

More Vectorworks TDD

Fri 6 Jan 2012

Test-driven Vectorworks development

Test-driven Vectorworks development

Fri 19 Aug 2011

Getting started with the Vectorworks SDK, Part 3

Getting started with the Vectorworks SDK, Part 3

Install Homebrew

Install ack

Install git and Gitx

Install rake

Install Xcode

Install the SDK

Mon 14 Mar 2011

Getting started with the Vectorworks SDK, Part 2

Getting started with the Vectorworks SDK, Part 2

Regarding plug-ins in general, which you can mostly skip if you know anything at all about Vectorscript development

The nouns

The verbs

Packaging

The anatomy of our text note plug-in

Plug-in parameters

Mon 28 Feb 2011

Getting started with the Vectorworks SDK

Getting started with the Vectorworks SDK

To follow along at home, you will need…

Our project

Why not just use Vectorscript?

Modernity

Fri 18 Feb 2011

Install `ack`

Install `git` and Gitx

Install `rake`