Annotation (“Wireframe Dot”) Applescripts for Omnigraffle

This post has been a long time coming, so apologies to those who have been anticipating it for some time.

Some background: at Usability Matters we spend a large part of our time wireframing. When we were on Windows machines, we used Microsoft Visio for this, but after making the switch to Macs in the fall, we  now use Omnigraffle to wireframe.

Both Visio and Omnigraffle are extremely powerful tools, but they are both pretty pitiful at handling annotations. We use little red dots with numbers in them to highlight items on a wireframe that are of interest, something like this:

Sample Wireframe Showing Annotation Dots

Forgetting about the notes that accompany these dots (that’s a script for another day), the dots themselves can be difficult. The reason? We try to keep the annotation dots roughly in order from top to bottom on the page, so it’s easy to find what you’re looking for. (We don’t want clients saying, “Where the heck is number 5?!”)

The problem is that it’s not uncommon for me to have 20-30 dots on a single wireframe. What happens if I need a new “1”? Without a script, it means creating a new “1” dot, then changing the old “1” to “2”, the old “2” to “3”, etc. I don’t have time for that!

So… I wrote a script. Actually, four scripts. They handle everything about adding/removing annotation dots:

  • Adding a new dot
  • Incrementing all dots on a page (also known as a “canvas”)
  • Removing a dot
  • Decrementing all dots on a page

Because of some limitations within Omnigraffle, these might not work exactly as you expect, so bear with me as I describe how to use each:

Add a new dot

Used when you have a new feature that you need to document.

(This is possibly the least intuitive script, due to Omnigraffle limitations. Follow these instructions closely and if you can’t make heads or tails of it, just leave a comment or tweet @umatters and I’ll try to help!)

  1. Create the new dot, with the number you want it to have, and in the place you want it.
  2. Select the new dot.
  3. Choose the “Add new dot” script from your script menu (see “How to Install the Scripts” below to learn how to show your script menu).
  4. All dots with numbers higher than the new dot will be incremented! (Only dots on that specific page will be incremented. If a wireframe spans multiple pages, use “Increment all dots on page” for the rest of the pages.)

Increment all dots on page

Used when a wireframe spans multiple pages. “Add a new dot” will increment the dots on the page where the new feature is added, but then you’ll need to increment all dots on any subsequent pages.

  1. Choose the “Increment all dots on page” script from your script menu.
  2. All dots on the pages will be incremented.

Remove a dot

Used when you need to remove a feature that was documented.

  1. Select the dot to remove.
  2. Choose the “Remove a dot” script from your script menu.
  3. The dot will be removed, and all dots with higher numbers will be decremented.

Decrement all dots on page

Used when a wireframe spans multiple pages. “Remove a dot” will adjust the dots on the page where the feature was removed, but then you’ll need to decrement all dots on any subsequent pages.

  1. Choose the “Decrement all dots on page” script from your script menu.
  2. All dots on the pages will be decremented.

How to Install the Scripts

Honestly, Peter McMaster, who has written several useful Omnigraffle scripts, has put together such a comprehensive set of instructions, I think it’s best to refer you to him. I couldn’t explain it any better than he does. Make sure you follow the instructions to reveal your scripts menu.

Using the Usability Matters Dot

Included in the script zip file is an Omnigraffle stencil with the annotation dot that we use. You’re welcome to use this one (which should work automagically with the scripts).

Using Your Own Dots

To use your own dot:

  • Ensure the “Notes” field of your dot is set to “Wireframe dot” (look for “Notes” in the “Properties” inspector). This is the only way the scripts can find the dot shapes and update them.
  • OR: Change the “dotName” variable in each script to the “Note” field value of your current dot.

Then, go into each script and modify the fontSize and fontColor variables to match the ones you use for your own dot. (Unfortunately I couldn’t get the text alignment to work as a variable. It’s center by default, and you can change it in the guts of the script if you need to!)

One Warning

The scripts don’t work on dots that are grouped with other shapes – they have to be independent. Perhaps one day I’ll make it that sophisticated, but for now, try to avoid grouping your dots with anything else!

Ready? Go!

Download Scripts

I think that’s it. I really hope this makes sense. I’m happy to give in-person tutorials to people in Toronto, or Skype tutorials to anyone else. Just leave a comment on this post for help, or tweet me at @umatters.