[Joel]

[Originally posted to the OmniGraffle users mailing list by David Kasprzyk, thought I'd post it here as well for easier access -- JP]

After much editing and such, and creating some shapes, I think I'm ready
to release my .graffleshapes tutorial for your benefit. Let me know if
you have any questions and I'd be happy to clarify any issues.

David's Shape Creation Tutorial:

The shapes file - shapes.graffleshapes:

All of the shapes and lineheads in OmniGraffle are defined in the
shapes.graffleshapes file. This file is part of the OmniGraffle.app
package. To access this file, right click (control-click if you don't
have two buttons) on the application to bring up the contextual menu.
Select 'Show Package Contents' from the menu, which will open up a new
window titled OmniGraffle. Open up the one folder inside, 'Contents',
then open up the 'Resources' folder in the new window. In the 'Resources'
window that opens, you should be able to find the shapes.graffleshapes
file. Since we don't want to damage the original file, I recommend option
dragging this file to the desktop, thus making a copy.

Creating your own personal shapes file:

Now that we have created our shapes.graffleshapes copy lets start by
renaming it, we'll call it shapestutorial.graffleshapes. Now that this is
done we need to place the file in the proper directory. All third party
graffleshapes files are stored in either,

Library/Application Support/OmniGraffle/Shapes/ if you want to give everyone
on your computer access or
~/Library/Application Support/OmniGraffle/Shapes/ if you want access only
for yourself

so lets move shapestutorial.graffleshapes into the local directory for now.

Overview of a .graffleshapes file:

Now lets open up the shapestutorial file and take a look at it. A
.graffleshapes file can be opened and edited with any text editor, such as
TextEdit and BBEdit. When you open up the file you will see the
information that creates OmniGraffle's default shapes. The basic outline
should look something like,

{
shapes = (
{
InspectorGroup = 32;
ShapeName = RoundedStack;
StrokePath = {
elements = (
...
);
};
TextBounds = "{{0.02, 0.02}, {0.855, 0.855}}";
},
{
...
}
);
}

That annoying syntax - A 'quick' discussion:

Since syntax is typically the cause of most errors in coding, it will
unfortunately be no different for creating graffleshapes. So to try and
assist you during your creation of graffleshapes I'll be going over
several of the main syntax issues.

First off all of the commands are case sensitive. Thus shapename is not
equivilant to ShapeName. All of the commands listed in this tutorial
should be copied directly for them to work properly.

Spaces and tabs are not required but they do make it easier to spot
problems if your shapes file doesn't load properly, and I highly recommend
using them.

Decimal numbers can be enter with or without the leading zero. So 0.5 is
just as valid in a graffleshapes file as .5 is. My best advice is to pick
a system and stay with it for convenience in debugging problems.

Commas and semicolons typically cause the most problems in getting your
shapes to properly load into OmniGraffle. I will therefore try and list
where semicolons and commas should go in you graffleshapes files.

Commas: Commas are used in two main sections of a graffleshapes file.
The first of these is to link elements together when defining a path. A
comma should follow every element that you define, with the exception of
the very last element. This can be seen in the following example:

elements = (
{element = MOVETO; point = "{-0.5, -0.5}"; } ,
{element = LINETO; point = "{0.5, -0.5}"; } ,
{element = LINETO; point = "{0.5, 0.5}"; } ,
{element = LINETO; point = "{-0.5, 0.5}"; } ,
{element = CLOSE; }
);

The second comma location is between each shape that is created. Like we
did with the elements, no comma should follow the last shape. The format
should be as shown below:

shapes = (
{
...
} ,
{
...
} ,
{
...
}
);

Semi Colons: While you end up using semi colons much more frequently than
commas, the placement of semi colons follows a specific rule.

The Rule of Semi Colons:
If you are setting a value, and thus using the = character, the you
must follow the expression with a semi colon. To emphasize the point here
are some examples:

shapes = (
...
);

StrokePath = {
...
};

element = MOVETO;

point = "{ ... }";

These quick guidelines should hopefully allow you to track down any
problems that you may experience in the creation of you graffleshapes.
Now that we have these guidelines set up, lets take a look at actually
creating the shapes.