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:
[tdraw
[objects
[fonts
1=Homerton.Medium
2=Homerton.Bold
]
[text
font=1
size=10
pos=96,100
text=Hello World!
]
[path
width=1
[dashed
offset=4
pattern=8,8,12,4
]
[components
move=90,90
draw=90,130
draw=240,130
draw=240,90
draw=90,90
]
]
]
]
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:
- [item
- This introduces an item, and is followed by 0 or more attributes
or items.
- attribute=value
- 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
- num
- Decimal floating point number (e.g. size=-1.25)
- str
- String, e.g. text=foobar
- col
- Colour in hex as RRGGBB (e.g. fg=ff87aa), or the word
none.
- hex
- One word in hex, e.g. 001234AB
TDraw items
tdraw
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
|
objects
This is a list of object items. Order does matter, it determines the
rendering sequence. Also note the requirements of fonts.
Object items
fonts
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
|
text
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
|
path
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
|
Notes
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.
sprite
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
|
group
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
|
tagged
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
|
textarea
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
|
options
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
|
Notes
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.
jpeg
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
|
something
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
dashed
This is the dash pattern definition.
| Attribute | Value | Presence | Default
|
|---|
| offset | num | 0 or 1 | 0
|
| pattern | num,num,... | 1 | n/a
|
components
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.
data
| Attribute | Value | Presence | Default
|
|---|
| val | hex,hex,... | 0 or more | none
|
Textarea sub-items
content
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
|
columns
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
|