Technical Information for Legacy Plug-In Developers

Introduction

Plug-In developers are strongly encouraged to support cross-platform development. You should strongly consider building both Macintosh and Win32 versions of your plug-ins.

A plug-in is a single stand-alone executable binary file. On Windows, this means a self-contained valid Win32 .EXE binary (see note 1). On Macintosh, plug-ins must have a creator type of APPL (ie, a standard Application). Upon launching, it reads a temporary file off disk containing the current document artwork, makes appropriate modifications or additions, and creates a new temporary file before quitting. Auto-Illustrator waits for this second temporary file to exist, and then imports that, replacing the previous document with the new one. Using this system, a plug-in can do anything to the entire document (including erase everything). Because of this, plug-ins must be able to understand the data structure of the first temporary file, in order to recreate it in the second. If you dont do that, a user will loose all their existing artwork when they launch your plugin. If that isn't your intention, that's a bad thing.

A note on future compatability

Temporary Files

On Windows, temporary files are stored in the system's Temporary directory, which is usually WINDOWS\TEMP. Again, this will vary depending on system architecture, and you should use appropriate system calls to determine the correct location of that directory. You might be able to rely on the TEMP Environment variable to tell you that location - this is not officially confirmed by Signwave.

The filename of the first temporary file containing the initial document contents is swAI-plugin-export.aut. The format of this file is exactly the same as a regular Auto-Illustrator .aut file, as generated by a File | Save As... action. These are standard text files (see note 2) and you should examine a range of existing .aut files to see how these represent the document artwork. This document only briefly explains them.

A plug-in must create the second temporary file called swAI-plugin-import.aut in the temporary folder, and then quit immediately.

Temporary File Format

As of b0.2-r17, the format of .aut files changed. Plug-In developers must not use the file format of .aut files from versions before b0.2-r17, either for reading the first temporary file, or writing the second.

Each object in a document is represented by a single line in an .aut file. Some objects are not visible to the user, but should still be maintained. Each line contains a series of NAME=VALUE pairs. Each pair is separated by a single space character (0x20).

Each object is of a specific type. The type is determined by the first data pair, which is a TYPE declaration. At time of authoring (b0.4-r19) there are three visible types of objects usable, and one invisible. These are:

TYPE=PATH : This object contains COLOUR, SOLID, WEIGHT, GROUPS and PATH data
TYPE=TEXT : This object contains COLOUR, WEIGHT, FONT, GROUPS, TEXT and PATH data
TYPE=BUG : This object contains COLOUR, WEIGHT, AGE, DIRECTION and DEAD data
TYPE=DIMENSIONS : This object contains WIDTH, HEIGHT and COLOUR data

Data types and formats

• COLOUR
  Colours are expressed in three 2-byte hexadecimal notation, exactly the same as HTML RGB colours, except they lack the leading hash (#) symbol. Examples are COLOUR=00FF00 for pure green, and COLOUR=00CCFF for sky-blue.

• WEIGHT
  For TYPE=PATH and TYPE=BUG objects, this specifies the stroke-width of this object's path. For TYPE=TEXT objects, it represents the point-size the text is rendered at. This is expressed in points (1/72 inch) although Auto-Illustrator doesn't adhere strictly to that scale in order to maintain compatability between PostScript, Shockwave SWF and bitmap (screen) renderers. You can safely assume that WEIGHT=0 will produce the thinnest possible hairline. Decimal numbers are allowed. Do not use scientific notation.

• GROUPS
  Auto-Illustrator can group objects together so that when one is selected, other objects in the same group are also selected. The GROUPS data is a comma-separated list of numbers. Each group has its own unique number. Objects that share a group number with other objects (which must also list this group number) belong to the same group. An object can belong to any number of groups. For example, one object may belong to GROUPS='1,2' while a second only belongs to GROUPS='1' (even though this example would infact be impossible - see note 3). Use only integer group numbers. You may optionally place single-quotation marks (') around the group values.

• PATH
  For TYPE=PATH and TYPE=BUG objects, the PATH data contains a list of forward-slash separated pairs of X and Y coordinates. For TYPE=TEXT objects, the PATH data contains a single comma-separated X,Y coordinate pair repsenting the lower left corner of a piece of text. The X and Y coordinates are separated by a comma. For example, PATH='50,50/100,50' defines a line between 50,50 and 100,50. PATH='100,100/150,100/150,150/100,100' defines a closed right-angle triangle. Note that these coordinates are expressed in PostScript coordinates, meaning that 0,0 is the bottom left corner of the page. You can determine the top right corner of the page by looking at the TYPE=DIMENSIONS object. You can use decimal numbers with full-stop (.) decimal places. Do not use scientific notation. You may optionally place single-quotation marks (') around the path data. See note 4 for important information about a serious bug in path data.

• SOLID
  An optional data tag that isn't a pair, specifies (for TYPE=PATH onjects only) that this object should be filled and stroked, rather than just stroked. The SOLID data tag appears like so: TYPE=PATH SOLID PATH=...

• FONT
  A string surrounded by single-quotation marks (') specifying the name of the font for TYPE=TEXT objects. This font name should be a standard Windows or Macintosh font name. Examples might include FONT='helvetica' or FONT='times new roman'.

• TEXT
  A string surrounded by single-quotation marks (') specifying the text to render for TYPE=TEXT objects. You cannot use single-quotation marks in TEXT strings yet. This is a known problem. Examples might include TEXT='I love Macintosh' or TEXT='My other vector application is Adobe Illustrator'

• AGE
  For TYPE=BUG objects only, the AGE data pair represents the current age of the bug in the document. This is really only used internally by the bug animation routine and isn't very useful outside Auto-Illustrator. If you intend to create bugs with plug-ins, set the AGE=0

• DIRECTION
  For TYPE=BUG objects only, the DIRECTION data pair represents the direction in which a bug is currently travelling in, and ranges from 0 to 7. The directions are 0=up 1=up/right 2=right 3=down/right 4=down 5=down/left 6=left 7=up/left. And example might be DIRECTION=3 which would cause the bug to travel towards the lower right corner of the document (assuming the user has orientated North to be upwards - this is beyond your control).

• DEAD
  An optional data tag that isn't a pair and is only for TYPE=BUG objects, the DEAD data tag specifies the bug is dead and is no longer travelling. These appear exactly the same as non-sold TYPE=PATH objects, but internally are represented differently. This is so that plug-ins may choose to resurrect dead bugs by removing the DEAD tag. It appears as so: TYPE=BUG DEAD DIRECTION=...

• WIDTH
  For the TYPE=DIMENSIONS object only, this represents the document's page width in points. You should read this value and use it to generate your new artwork, so that you know the page dimensions the user is working with. It appears as so: WIDTH=560

• HEIGHT
  For the TYPE=DIMENSIONS object only, this represents the document's page height in points. You should read this value and use it to generate your new artwork, so that you know the page dimensions the user is working with. It appears as so: HEIGHT=767

Important considerations

Your plug-in doesn't have to quit immediately. You could pop open a dialog box, accept user input in any manner of ways, wait until they have clicked an Okay button, and then generate the second temporary file before quitting. You should always be aware that Auto-Illustrator will resume operations as soon as it sees this second temporary file, so make sure your plug-ins quits itself as soon as it has created this file.

Use the right icon for your plug-ins. If you use a different plug-in icon from the existing icons bundled with Auto-Illustrator, users might get confused and not realise it is a plug-in, thus putting it in the wrong place.

Call your plug-in something sensible. The filename is what appears in the Filter menu (although the .exe extension is not shown on Windows systems).

You can do anything with plug-ins. The Swap Artwork plug-in uses a TCP/IP socket to swap artwork data with another machine on the Internet, for example. Exploit the possibilities by creating plug-ins that users will find stimulating and fun to use. A plug-in doesn't even have to generate any new artwork, remember!

You should play safe. When your plug-in launches, if it can't find the first temporary file, it shouldn't throw an error message saying "Can't find temporary file!". This is usually an indication that somebody has tried running your plug-in from outside of Auto-Illustrator. Of course this makes no sense, so in this situation it is wise to show an error message saying "This is an Auto-Illustrator plug-in. Place it in the Plug-Ins folder in the Auto-Illustrator application folder, and access it from the Filter menu" (for example).

Make sure you ask your users to place your plug-in in the correct folder in the Plug-Ins folder. Do you want your plug-in to be categorised as Generate, Degenerate, Transform, or General (ie, just listed at the bottom of the Filter menu)?

A final word...

Notes

Note 2
These text files adhere to the system's standard text file format. This means that Windows .aut files contain DOS-style CRLF line terminators, Macintosh .aut files contains Macintosh-style CR line terminators. This means you can load an .aut file into any regular text file editor (ie, Notepad on Windows, BBEdit on Macintosh).

Note 3
The generation and management of group values is very complex, as the user interface dictates that when a grouped object is selected, all other same-group relatives are selected. The grouping and ungrouping of objects appears to be in a hierarchical manner because the selection of objects is a knock-on recursive system: If another same-grouped object in the first group also has a second (different) group, then all those other objects in the second group number need to be selected, too - ad infinitum (in theory). Don't go changing group-numbers without paying careful consideration to this fact: incorrect behaviour confuses users and breaks the user-interface paradigm. If you need to create a new group, just make sure you choose a unique new group number.

Note 4
You must use a full-stop/period to mark your decimal place. Users of non-English operating systems (such as French, Swedish etc) will have their system set up to use a comma for decimal places (as defined in the Numbers Control Panel on Macintosh systems, for example). If you assume your programming language of choice always uses full-stops, don't. Proper internationalised software always delegates the choice of decimal place characters to the operating system. You must make sure you use full-stops (.) as your decimal places otherwise this will intefere with the X and Y coordinates of your PATH data.