         Manual for the Armbob draw library
         --------------------------------------

                         GCW 22/6/97

Joe Taylor's DrawBasic package (Liber Abaci 1994) is a procedure
library for BBC Basic to facilitate the construction of DrawFiles
under program control. The Armbob draw library is intended for the
same purpose, but cannot claim to offer the same range of facilities.
This has been developed as an experiment in using Armbob's object-oriented
features. It provides a basic platform for others to develop further. 
Of necessity it strongly resembles DrawBasic, except with an Armbob 
syntax rather than a Basic syntax.

Armbob does not have Basic's LIBRARY command. Instead one uses
#include preprocessor directives so that the draw library files and the 
main program file are compiled and run together. See the file drawex
in the Examples directory. It contains the directive

#include bob:draw.figure

This file, in turn contains the line "#include bob:draw.file" and bob:draw.file
contains the line "#include bob:draw.object".

The file bob:draw.object defines the low level class of "objects" and 
their methods. None of the definitions in this file should be used 
in your programs explictly. An object is essentially an array of bytes
structured in some way.  

The file bob:draw.file defines the class of "drawfiles", using the low
level notion of "object". Only some of the definitions in this file
should be used in your programs explicitly. This note documents them.

The file bob:draw.figure uses only definitions in bob:draw.file.
It is intended for definitions of geometrical subpath objects (see below),
represented as drawfile methods. As a starter, it contains only the 
drawfile methods

drawfile::circle(x,y,r)

       Draw a circle, centre (x,y), radius r.

drawfile::ellipse(x,y,a,b)

       Draw an ellipse, centre (x,y), with horizontal semi-axis of
       length a, and vertical semi-axis of length b.

All units are in points - (1/72)".

Glossary
--------

To create a new drawfile, called MyDrawFile, say, use the command

             MyDrawFile = new drawfile;

Drawfiles contain 1) a header, and 2) a list of "draw objects". These
must be created in order. The command

             MyDrawFile->begin();

creates the header. At present the only draw objects permitted in
Armbob are:

     1) text objects
     2) path objects
     3) group objects

Text
----
A text object is created and named by a command of the form

            MyTextObject = MyDrawFile->text(string,x,y);

Here 'string' is a string expression, and (x,y) is the position where
the bottom left of the string will placed. Text objects have various
attributes that can be altered from their default values.

 colour
 ------
 The default colour for text is black. The command

            colour(MyTextObject,c);

 will set the text colour of MyTextObject to c. Colours can have
 values in the range 0-15 (click on the palette icon to see which
 they are).
            
 font
 ----
 The default font is the system font. Other fonts may be used using
 the command

             font(MyTextObject,f);

 where f can take values 0-12 with the following meaning. 

  System                  = 0;
  Trinity_Medium          = 1;
  Trinity_Medium_Italic   = 2;
  Trinity_Bold            = 3;
  Trinity_Bold_Italic     = 4;
  Corpus_Medium           = 5;
  Corpus_Medium_Oblique   = 6;
  Corpus_Bold             = 7;
  Corpus_Bold_Oblique     = 8;
  Homerton_Medium         = 9;
  Homerton_Medium_Oblique = 10;
  Homerton_Bold           = 11;
  Homerton_Bold_Oblique   = 12;
           
 font size
 ---------
 The default font size is 10 point. The font size can be modified
 horizontally and vertically independently with commands:

           MyDrawFile->font_x(MyTextObject,pts_x);
           MyDrawFile->font_y(MyTextObject,pts_y);

 where pts_x and pts_y are the horizontal and vertical font sizes in
 points. Note that modifying the font size uses a drawfile method,
 rather than a straightforward function. This is because altering the
 font size might alter the bounding box for the whole drawfile.

Paths
-----
A path consists of 1) a header and 2) a sequence of subpaths. These
must be created in order. To create the header of a path called MyPath
use the command

               MyPath = MyDrawFile->path();

This must be followed by at least one subpath. Each subpath begins
with a command

               MyDrawFile->move(x,y);

and is followed by a sequence of commands either of the same form or
of the form

               MyDrawFile->draw(x,y);

or

               MyDrawFile->bezier(x1,y1,x2,y2,x3,y3);

and optionally terminated by a command

               MyDrawFile->close_with_line();

Of course, a sequence of such commands may be bundled up into a function
or a drawfile method (see the file bob:h.draw.figure). The path is 
terminated by the command

               MyDrawFile->endpath(MyPath);

Path objects have various attributes that can be altered from their 
default values.

 Fill colour
 -----------
 The default fill colour is none. This can be altered with

                    fill(MyPath,c);

 where c is a colour (see above).  The value c = none = -1 gives 
 a transparent fill colour.

 Outline colour
 --------------
 The default colour is black. This can be altered with

                    outline(MyPath,c);

 where c is a colour (see above).  The value c = none = -1 gives 
 a transparent fill colour.

 Linewidth
 ---------
 The default is one point. This can be altered with

                    linewidth(MyPath,n);

 where n is the number of points.

 Join style
 ----------
 The default is mitred joins. This can be altered with

                    join_style(MyPath,x);

  where x can be Mitred, Round or Bevelled.

 Cap style
 ------------
 The default is butt caps. Endcaps can be altered with

                    endcap_style(MyPath,x);

 and startcaps can be altered with

                    startcap_style(MyPath,x);

 where x can be Butt, Round or Square.

 Winding Rule
 ------------
 The default winding rule is Non_Zero. This can be altered with

                  winding_rule(MyPath,rule);

 where rule is Non_Zero or Even_Odd.

Groups
------
A group consists of a header followed by a sequence of drawfile
objects, i.e. text, path or group objects. The header is created
by a command of the form

                MyGroup = MyDrawFile->group();

and the sequence of drawfile objects that comprise the group must be
terminated by the command

                MyDrawFile->endgroup(MyGroup);

Finally, a drawfile is saved to a file and displayed with the command

                MyDrawFile->end(file);

It is quite permissible to define many drawfiles at once in the same
program, with the commands for creating them interleaved however one
wishes. Only the relative ordering of the commands for a given drawfile
are important. The MyDrawFile-> prefix sorts out which commands apply
to MyDrawFile. 

