home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / language / bob / doc / Draw next >
Encoding:
Text File  |  1994-12-31  |  7.1 KB  |  252 lines
  1.          Manual for the Armbob 2.1 draw library
  2.          --------------------------------------
  3.  
  4.                          GCW 29/12/94
  5.  
  6. Joe Taylor's DrawBasic package (Liber Abaci 1994) is a procedure
  7. library for BBC Basic to facilitate the construction of DrawFiles
  8. under program control. The Armbob draw library is intended for the
  9. same purpose, but cannot claim to offer the same range of facilities.
  10. This has been developed as an experiment in using Armbob's object-oriented
  11. features. It provides a basic platform for others to develop further. 
  12. Of necessity it strongly resembles DrawBasic, except with an Armbob 
  13. syntax rather than a Basic syntax.
  14.  
  15. Armbob does not have Basic's LIBRARY command. Instead one uses BobProj
  16. or BobPTask files to list the library files and the main program file
  17. to be compiled and run together. See the BobProj file Bob:DrawEx which
  18. contains the lines
  19.  
  20. bob:h.draw.object
  21. bob:h.draw.file
  22. bob:h.draw.figure
  23. bob:main.drawex
  24.  
  25. The first three lines are just a standard "header" for using the draw
  26. library. The file named in the last line is the one to look at to see
  27. an example of how the draw library is used.
  28.  
  29. The file bob:h.draw.object defines the low level class of "objects" and 
  30. their methods. None of the definitions in this file should be used 
  31. in your programs explictly. An object is essentially an array of bytes
  32. structured in some way.  
  33.  
  34. The file bob:h.draw.file defines the class of "drawfiles", using the low
  35. level notion of "object". Only some of the definitions in this file
  36. should be used in your programs explicitly. This note documents them.
  37.  
  38. The file bob:h.draw.figure uses only definitions in bob:h.draw.file.
  39. It is intended for definitions of geometrical subpath objects (see below),
  40. represented as drawfile methods. As a starter, it contains only the 
  41. drawfile methods
  42.  
  43. drawfile::circle(x,y,r)
  44.  
  45.        Draw a circle, centre (x,y), radius r.
  46.  
  47. drawfile::ellipse(x,y,a,b)
  48.  
  49.        Draw an ellipse, centre (x,y), with horizontal semi-axis of
  50.        length a, and vertical semi-axis of length b.
  51.  
  52. All units are in points - (1/80)".
  53.  
  54. Glossary
  55. --------
  56.  
  57. To create a new drawfile, called MyDrawFile, say, use the command
  58.  
  59.              MyDrawFile = new drawfile;
  60.  
  61. Drawfiles contain 1) a header, and 2) a list of "draw objects". These
  62. must be created in order. The command
  63.  
  64.              MyDrawFile->begin();
  65.  
  66. creates the header. At present the only draw objects permitted in
  67. Armbob are:
  68.  
  69.      1) text objects
  70.      2) path objects
  71.      3) group objects
  72.  
  73. Text
  74. ----
  75. A text object is created and named by a command of the form
  76.  
  77.             MyTextObject = MyDrawFile->text(string,x,y);
  78.  
  79. Here 'string' is a string expression, and (x,y) is the position where
  80. the bottom left of the string will placed. Text objects have various
  81. attributes that can be altered from their default values.
  82.  
  83.  colour
  84.  ------
  85.  The default colour for text is black. The command
  86.  
  87.             colour(MyTextObject,c);
  88.  
  89.  will set the text colour of MyTextObject to c. Colours can have
  90.  values in the range 0-15 (click on the palette icon to see which
  91.  they are), and the following synonyms are predefined:
  92.  
  93.   white  =  0;
  94.   black  =  7;
  95.   blue   =  8;
  96.   yellow =  9;
  97.   green  = 10;
  98.   red    = 11;
  99.   cream  = 12;
  100.   olive  = 13;
  101.   orange = 14;
  102.   azure  = 15;
  103.             
  104.  font
  105.  ----
  106.  The default font is the system font. Other fonts may be used using
  107.  the command
  108.  
  109.              font(MyTextObject,f);
  110.  
  111.  where f can take values 0-12. The following synonyms are predefined:
  112.  
  113.   System                  = 0;
  114.   Trinity_Medium          = 1;
  115.   Trinity_Medium_Italic   = 2;
  116.   Trinity_Bold            = 3;
  117.   Trinity_Bold_Italic     = 4;
  118.   Corpus_Medium           = 5;
  119.   Corpus_Medium_Oblique   = 6;
  120.   Corpus_Bold             = 7;
  121.   Corpus_Bold_Oblique     = 8;
  122.   Homerton_Medium         = 9;
  123.   Homerton_Medium_Oblique = 10;
  124.   Homerton_Bold           = 11;
  125.   Homerton_Bold_Oblique   = 12;
  126.            
  127.  font size
  128.  ---------
  129.  The default font size is 10 point. The font size can be modified
  130.  horizontally and vertically independently with commands:
  131.  
  132.            MyDrawFile->font_x(MyTextObject,pts_x);
  133.            MyDrawFile->font_y(MyTextObject,pts_y);
  134.  
  135.  where pts_x and pts_y are the horizontal and vertical font sizes in
  136.  points. Note that modifying the font size uses a drawfile method,
  137.  rather than a straightforward function. This is because altering the
  138.  font size might alter the bounding box for the whole drawfile.
  139.  
  140. Paths
  141. -----
  142. A path consists of 1) a header and 2) a sequence of subpaths. These
  143. must be created in order. To create the header of a path called MyPath
  144. use the command
  145.  
  146.                MyPath = MyDrawFile->path();
  147.  
  148. This must be followed by at least one subpath. Each subpath begins
  149. with a command
  150.  
  151.                MyDrawFile->move(x,y);
  152.  
  153. and is followed by a sequence of commands either of the same form or
  154. of the form
  155.  
  156.                MyDrawFile->draw(x,y);
  157.  
  158. or
  159.  
  160.                MyDrawFile->bezier(x1,y1,x2,y2,x3,y3);
  161.  
  162. and optionally terminated by a command
  163.  
  164.                MyDrawFile->close_with_line();
  165.  
  166. Of course, a sequence of such commands may be bundled up into a function
  167. or a drawfile method (see the file bob:h.draw.figure). The path is 
  168. terminated by the command
  169.  
  170.                MyDrawFile->endpath(MyPath);
  171.  
  172. Path objects have various attributes that can be altered from their 
  173. default values.
  174.  
  175.  Fill colour
  176.  -----------
  177.  The default fill colour is none. This can be altered with
  178.  
  179.                     fill(MyPath,c);
  180.  
  181.  where c is a colour (see above).  The value c = none = -1 gives 
  182.  a transparent fill colour.
  183.  
  184.  Outline colour
  185.  --------------
  186.  The default colour is black. This can be altered with
  187.  
  188.                     outline(MyPath,c);
  189.  
  190.  where c is a colour (see above).  The value c = none = -1 gives 
  191.  a transparent fill colour.
  192.  
  193.  Linewidth
  194.  ---------
  195.  The default is one point. This can be altered with
  196.  
  197.                     linewidth(MyPath,n);
  198.  
  199.  where n is the number of points.
  200.  
  201.  Join style
  202.  ----------
  203.  The default is mitred joins. This can be altered with
  204.  
  205.                     join_style(MyPath,x);
  206.  
  207.   where x can be Mitred, Round or Bevelled.
  208.  
  209.  Cap style
  210.  ------------
  211.  The default is butt caps. Endcaps can be altered with
  212.  
  213.                     endcap_style(MyPath,x);
  214.  
  215.  and startcaps can be altered with
  216.  
  217.                     startcap_style(MyPath,x);
  218.  
  219.  where x can be Butt, Round or Square.
  220.  
  221.  Winding Rule
  222.  ------------
  223.  The default winding rule is Non_Zero. This can be altered with
  224.  
  225.                   winding_rule(MyPath,rule);
  226.  
  227.  where rule is Non_Zero or Even_Odd.
  228.  
  229. Groups
  230. ------
  231. A group consists of a header followed by a sequence of drawfile
  232. objects, i.e. text, path or group objects. The header is created
  233. by a command of the form
  234.  
  235.                 MyGroup = MyDrawFile->group();
  236.  
  237. and the sequence of drawfile objects that comprise the group must be
  238. terminated by the command
  239.  
  240.                 MyDrawFile->endgroup(MyGroup);
  241.  
  242. Finally, a drawfile is saved to a file and displayed with the command
  243.  
  244.                 MyDrawFile->end(file);
  245.  
  246. It is quite permissible to define many drawfiles at once in the same
  247. program, with the commands for creating them interleaved however one
  248. wishes. Only the relative ordering of the commands for a given drawfile
  249. are important. The MyDrawFile-> prefix sorts out which commands apply
  250. to MyDrawFile. 
  251.  
  252.