Tdraw Specification

A TDraw file is the same as a DrawFile, but it is textual. This makes it easier to produce from scripts and similar, and of course easier to read for humans, if you, like me, enjoy recreational drawfile reading.

It also helps if you use CVS or similar version control systems - they can then treat the drawfiles as source files instead of opaque binary lumps of data. It would also be much easier to compose files from several sources.

The content of a TDraw file is very similar to the corresponding drawfile, except some of the redundant information is omitted (e.g. most bounding boxes). Data that must be binary is spelled out in hex (e.g. sprites and JPEGs).

TDraw files are strictly hierachical, and consist of nested items. Some of these items correspond directly to Draw objects, others are different.

It is not my intention to write TDraw files from scratch, no matter how fun it might be. This is why there are conversion programs both ways. The syntax for these files is very strict, because they are meant to be produced by programs rather than humans.

A small TDraw file could look like this:

   text=Hello World!

The indenting is not required, but all other (lack of) spacing is mandatory. All text is case sensitive, except font names. The order of items and attributes is sometimes significant, as noted below.

There are 3 types of lines in the file:

This introduces an item, and is followed by 0 or more attributes or items.
This defines the given attribute as having a certain value. The attribute name can consist of all chars except newline and '='. The value can contain anything except newline. The total length of the value must be less than 256 bytes.
This terminates an item.

All coordinates, sizes, etc. are measured in OS units (1/180") unless otherwise noted. Font sizes are in points.

Data types

Decimal floating point number (e.g. size=-1.25)
String, e.g. text=foobar
Colour in hex as RRGGBB (e.g. fg=ff87aa), or the word none.
One word in hex, e.g. 001234AB

TDraw items


The whole file is enclosed in this item.
Attribute Value Presence Default
version num 0 or 1 201
minor num 0 or 1 0
id str 0 or 1 tdr2drw
objects 0 or 1 none


This is a list of object items. Order does matter, it determines the rendering sequence. Also note the requirements of fonts.
Attribute Value Presence Default
fonts 0 or 1 none
text 0 or more none
path 0 or more none
sprite 0 or more none
group 0 or more none
tagged 0 or more none
textarea 0 or more none
options 0 or more none
jpeg 0 or more none
something 0 or more none

Object items


This table maps font numbers to names, the same as Draw object type 0. It consists of any number of attributes, each giving a number->font name mapping. If present, this object must precede all text objects.
Attribute Value Presence Default
num str 0 or more none


This is a line of text, the same as Draw object types 1 and 12. Omitting trans causes a type 1 object to be generated, otherwise type 12.
Attribute Value Presence Default
fg col 0 or 1 000000
bg col 0 or 1 ffffff
font num 0 or 1 1
size num 0 or 1 12
height num 0 or 1 equal to size
trans num,num,num,num 0 or 1 1,0,0,1
pos num,num 1 n/a
text str 1 n/a


This is a path, the same as Draw object type 2. It has two sub-items, described below.
Attribute Value Presence Default
fill col 0 or 1 none
line col 0 or 1 000000
width num 0 or 1 0
join str 0 or 1 bevelled
startcap str 0 or 1 butt
endcap str 0 or 1 butt
winding str 0 or 1 even-odd
tcapwidth num 0 or 1 1
tcaplength num 0 or 1 2
dashed 0 or 1 none
components 1 n/a
join can be 'mitred', 'round', or 'bevelled'.
startcap and endcap can be 'butt', 'round', 'square', or 'triangle'.
winding can be 'non-zero' or 'even-odd'.
tcapwidth and tcaplength are measured in multiples of width.


This is a sprite, like Draw object types 5 and 13. It is placed at pos and scaled to fit size, or using the transformation matrix given. Either size or trans must be present. The actual sprite data is explained below.
Attribute Value Presence Default
pos num,num 1 n/a
size num,num 0 or 1 trans
trans num,num,num,num 0 or 1 size
data 1 n/a


This is a group object, like Draw object type 6. The group name is unfortunately not displayed or edited by any drawfile editors I've ever seen. It could have been insanely useful on countless occasions.
Attribute Value Presence Default
name str 0 or 1 empty
objects 1 n/a


This is a tagged object, like Draw object type 7. The tag value is application specific. Note that objects must contain exactly one object.
Attribute Value Presence Default
tag num 1 n/a
objects 1 n/a


This object is like Draw object type 9. It is rather different than the rest. It contains a list of columns, which become Draw objects of type 10, enclosed within the type 9 object.
Attribute Value Presence Default
fg col 0 or 1 000000
bg col 0 or 1 ffffff
columns 1 n/a
content 1 n/a


This is the options object, Draw object type 11. It is honoured by some drawfile editors.
Attribute Value Presence Default
paper str 0 or 1 A4
showlimits str 0 or 1 off
landscape str 0 or 1 off
printerlimits str 0 or 1 on
gridspacing num 0 or 1 1
griddivision num 0 or 1 2
gridtype str 0 or 1 rectangular
gridautoadjust str 0 or 1 off
gridshow str 0 or 1 off
gridlock str 0 or 1 off
gridunits str 0 or 1 cm
zoom num:num 0 or 1 1:1
zoomlock str 0 or 1 off
toolbox str 0 or 1 on
entrymode str 0 or 1 select
undosize num 0 or 1 5000
paper can be 'A0' through 'A5'.
showlimits, landscape, printerlimits, gridautoadjust, gridshow, gridlock, zoomlock, and toolbox can be either 'on' or 'off'.
gridspacing is measured in gridunits
griddivision has no unit
gridtype can be either 'rectangular' or 'isometric'
gridunits can be either 'cm' or 'in'
zoom range is from 1:8 to 8:1
entrymode can be 'line', 'closed line', 'curve', 'closed curve', 'rectangle', 'ellipse', 'text', or 'select'.
undosize is measured in bytes.


This is a jpeg image, like Draw object type 16. It is placed at pos and scaled using the transformation matrix supplied.
Attribute Value Presence Default
pos num,num 1 n/a
trans num,num,num,num 0 or 1 1,0,0,1
data 1 n/a


This is a Draw object of the given type. It is used to store unknown objects that might have a meaning to some applications.
Attribute Value Presence Default
type num 1 n/a
bbox num,num,num,num 1 n/a
data 1 n/a

Path sub-items


This is the dash pattern definition.
Attribute Value Presence Default
offset num 0 or 1 0
pattern num,num,... 1 n/a


This item is special, because the order of attributes is significant, and they define the path to draw. They are under the same restrictions as normal draw paths, which means that the first component must be a move. The mandatory 'end of path' component is not required in this description. Note that the close attribute must be written as close=, since the '=' is mandatory.
Attribute Value Presence Default
move num,num 1 or more n/a
draw num,num 0 or more none
curve num,num,num,num,num,num 0 or more none
close none 0 or more none

Data item

This data item is simply a binary lump spelled out in hex. This is a waste of space, but fortunately filesize is not an issue in this project. The lines of hex words can be up to 256 bytes long, but are usually kept around 8 words per line to maintain readability.


Attribute Value Presence Default
val hex,hex,... 0 or more none

Textarea sub-items


This item contains the text in a textarea. There is a line attribute for each text line (that would normally be terminated by LF). The order of the lines is very significant.
Attribute Value Presence Default
line str 0 or more none


This item is a list of columns used in a textarea item. It simply contains the bounding boxes of all the columns. The order of the box attributes determines the sequence of the text flow between columns. The number of attributes must be equal to the number of columns set by \D in the textarea (or 1 if there is no \D).
Attribute Value Presence Default
box num,num,num,num 1 or more n/a