{ (define LIBNAME "A Functional Drawing Library (HtDC)")
  (include "head.tinc") }

This <code>draw</code> package provides classes and methods for a visual
world. Here is its class diagram of public fields and methods: 
<pre>
<code>
import colors.*;
import geometry.*;

 +-----------------------------------+
 | abstract World                    |
 +-----------------------------------+       +---------------------------------------+
 | Canvas theCanvas                  |------>| Canvas                                |
 +-----------------------------------+       +---------------------------------------+
 | boolean bigBang(int,int,double)   |       +---------------------------------------+
 | boolean endOfTime(String)         |       | boolean show()                        |
 | World endOfWorld(String)          |       | boolean close()                       |
 |                                   |       | boolean drawCircle(Posn,int,Color)    |
 |                                   |       | boolean drawDisk(Posn,int,Color)      |
 | abstract World onTick()           |       | boolean drawRect(Posn,int,int,Color)  |
 | abstract World onKeyEvent(String) |       | boolean drawLine(Posn,Posn,Color)     |
 | abstract boolean draw()           |       | boolean drawString(Posn,String)       |
 | abstract boolean erase()          |       | boolean clearCircle(Posn,int,Color)   |
 +-----------------------------------+       | boolean clearDisk(Posn,int,Color)     |
                                             | boolean clearRect(Posn,int,int,Color) |
                                             | boolean clearLine(Posn,Posn,Color)    |
                                             +---------------------------------------+
</code>
</pre>

<a name="world" />
<p>The abstract <code>World</code> class exports the following methods: 
<ul>

<li><code>bigBang(width,height,speed)</code>, which initializes the world,
associates it with a <code>width</code> x <code>height</code> <a
href="#canvas"><code>Canvas</code></a>, displays
this canvas, enables keyevents, and finally starts the clock at a rate of one tick per
<code>speed</code> seconds. If it succeeds with all of its actions, the method
produces <code>true</code>. 

<p><strong>Note:</strong> <code>width</code> and <code>height</code> must be
  positive <code>int</code>s, <code>speed</code> must be a positive
  <code>double</code>.
</p>

<p>The canvas in <code>World</code> is called
  <code>theCanvas</code>. References to a "canvas" in conjunction with the
  <code>World</code> class denote this default canvas.
</p>
</li>

<li><code>endOfTime</code>, displays the given message, stops the clock and, if it succeeds, produces
 <code>true</code>. After the end of time, events no longer trigger calls
 to <code>onTick</code> or <code>onKeyEvent</code> (see below). The canvas
 remains visible. 
</li>

<li><code>endOfWorld</code>, displays the given message, stops the clock and, if it succeeds, produces the
 last <code>World</code>. After the end of the world,  events no longer trigger calls
 to <code>onTick</code> or <code>onKeyEvent</code> (see below). The canvas
 remains visible. 
</li>
</ul>
The methods may fail due to the unavailability of the physical devices,
inappropriate uses, etc. In those cases, they fail with an exception.</p>

<p>A derived concrete class must supply definitions for the following methods: 
<ul>
<li><code>onTick()</code>, which is invoked for every tick of the clock. Its
purpose is to create a <code>World</code> whose differences with
<code>this</code> one represent what happened during the amount of time it takes
the clock to tick. 
</li>

<li><code>onKeyEvent(key)</code>, which is invoked for every keyboard event
  associated with the canvas. Its purposes is to create a
  <code>World</code> whose differences with <code>this</code> one represent
  what happens due to the user's use of the keyboard. The latter is
  represented with the string-valued argument <code>key</code>.
</li>

<li><code>draw()</code>, which is invoked <em>after</em> one of the two event
handlers has been called. Its purpose is to present <code>this World </code>
graphically on its canvas. If it succeeds, its result is <code>true.</code>
</li>

<li><code>erase()</code>, which is invoked <em>before</em> one of the two event
 handlers has been called. Its purpose is to erase <code>this World</code>'s
 canvas, as much as needed. If it succeeds, its result is <code>true.</code>
 Simple erase methods just draw a white rectangle of appropriate width and
 height located at the origin. 
</li>
</ul>
A program may, in principle, start several instances of (subclasses of)
<code>World</code>. If it does, the event handlers are called in a unpredictable
order. </p>

<a name="canvas" />
<p>To create an instance of the <code>Canvas</code> class, a program must supply
two <code>int</code> values: one for the width of the canvas and one for its
height. The canvas is a rectangle, whose borders are parallel to the computer
screen's borders. A program can use the following methods on instances of
<code>Canvas:</code>
<ul>

<li><code>show()</code>, which initializes the canvas to a white area,
  enables the drawing methods, and finally displays the canvas. If it
  succeeds, it produces <code>true</code>. Invoking the method a second
  time without calling <code>close</code> before has no effect.  
</li>

<li><code>close()</code>, which hides the canvas. If it succeeds, it produces <code>true</code>. 

<p>Closing the Canvas using the display controls does not fully hide the
canvas; it is still necessary to invoke <code>close</code> before
<code>show</code> is re-enabled.</p> 
</li>

<li><code>drawCircle(p,r,c)</code>, which draws a circle on <code>this
Canvas</code> at <code>p</code> with radius <code>r</code> and color
<code>c</code>.  If it succeeds, it produces <code>true</code>.</li>

<li><code>drawDisk(p,r,c)</code>, which draws a disk on
<code>this Canvas</code> at <code>p</code> with radius <code>r</code> and color
<code>c</code>.  If it succeeds, it produces <code>true</code>.</li>

<li><code>drawRect(p,w,h, c)</code>, which draws a solid rectangle on <code>this
Canvas</code> at <code>p</code> with width <code>w</code>, height
<code>h</code>, and color <code>c</code>.  The rectangle's lines are parallel to
the canvas's borders. If it succeeds, it produces <code>true</code>.</li>

<li><code>drawLine(p0,p1,c)</code>, which draws a line on <code>this
Canvas</code> from <code>p0</code> to <code>p1</code> using color
<code>c</code>.  If it succeeds, it produces <code>true</code>.</li>

<li><code>drawString(p,s)</code>, which draws the string <code>s</code> at
<code>p</code> on <code>this Canvas</code>.  If it succeeds, it produces
<code>true</code>.</li>

<li><code>clearCircle(p,r,c)</code>, which erases a circle from <code>this
Canvas</code> at <code>p</code> with radius <code>r</code> and color
<code>c</code>.  If it succeeds, it produces <code>true</code>.</li>

<li><code>clearDisk(p,r,c)</code>, which erases a disk from
<code>this Canvas</code> at <code>p</code> with radius <code>r</code> and color
<code>c</code>.  If it succeeds, it produces <code>true</code>.</li>

<li><code>clearRect(p,w,w,c)</code>, which draws a solid rectangle from <code>this
Canvas</code> at <code>p</code> with width <code>w</code>, height
<code>h</code>, and color <code>c</code>.  The rectangle's lines are parallel to
the canvas's borders. If it succeeds, it produces <code>true</code>.</li>

<li><code>clearLine(Posn p0, Posn p1, Color c)</code>, which erases a line from <code>this
Canvas</code> from <code>p0</code> to <code>p1</code> using color
<code>c</code>.  If it succeeds, it produces <code>true</code>.</li>

</ul>
The methods may fail due to the unavailability of the physical devices,
inappropriate uses, etc. In those cases, they fail with an exception.</p>
</p>

{(include "foot.tinc")}