jewl
Class Canvas

java.lang.Object
  jewl.Window
      jewl.Control
          jewl.Canvas

public class Canvas

extends Control

A general-purpose drawing surface. The shapes that can be drawn include lines, circles, ellipses, rectangles, polygons, polylines, text and images.

To draw on a canvas, use the add() method to add drawing objects (defined in the package jewl.canvas) to the canvas. The result of add() is an integer which can be used with the restore() method to restore the canvas to the state prior to the drawing object being added (that is, the object and any objects added subsequently will be removed). You can also record the state of the canvas at any time using the mark() method, and return to it using restore().

A canvas can optionally be set up to generate a command code when the mouse button is pressed. Methods in this class allow the mouse to be tracked. For example, "rubber banding" (where a line is drawn between the original and current mouse positions while the mouse button is held down) can be implemented by responding to the canvas command code like this:

      int state = canvas.mark();
      while (canvas.mouseDown()) {
        if (canvas.mouseMoved()) {
          canvas.restore(state);
          canvas.add(new LineObject(canvas.start(),canvas.end()));
        }
      }
  

Drawing objects are serializable, so the contents of a canvas can be saved to a file (or any output stream) using the save() method, and can be reloaded from a file (or any input stream) using the load() method.

Constructor Summary

Canvas(Container parent, int left, int top, int width, int height)
Construct a new canvas which is not interactive.

Canvas(Container parent, int left, int top, int width, int height, char action)
Construct a new canvas which responds to the mouse.

Method Summary

int	add(DrawingObject object) Add a new drawing object to the canvas.
void	clear() Clear the entire canvas.
Point	end() Get the current mouse position.
int	endX() Get the X coordinate of the current mouse position.
int	endY() Get the Y coordinate of the current mouse position.
void	load(java.io.InputStream stream) Load a drawing from an input stream.
int	mark() Record the current state of the canvas.
boolean	mouseDown() Test if the mouse button is down.
boolean	mouseMoved() Test if the mouse has been moved since the last time this method was called.
void	removeLast() Remove the last drawing object from the canvas.
void	restore(int mark) Restore the canvas to an earlier state.
void	save(java.io.OutputStream stream) Save a drawing to an output stream.
void	setBackground(java.awt.Color colour) Set the background colour of the canvas.
int	size() Get the number of drawing objects on this canvas.
Point	start() Get the point where the mouse button was pressed.
int	startX() Get the X coordinate of the point where the mouse button was pressed.
int	startY() Get the Y coordinate of the point where the mouse button was pressed.

Methods inherited from class jewl.Control

disable, enable, enable, getToolTip, isEnabled, setToolTip

Methods inherited from class jewl.Window

addEventListener, commandAvailable, getCommand, getFont, getHeight, getID, getLeft, getScreenHeight, getScreenWidth, getSource, getTop, getWidth, hide, init, isVisible, nextCommand, parent, root, setFont, setID, setLocation, setSize, show, show

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Canvas

public Canvas(Container parent,
              int left,
              int top,
              int width,
              int height)

Construct a new canvas which is not interactive.

Parameters:

parent - the parent window of the canvas.

left - the position of the left edge of the canvas relative to its parent. If this is negative, it is taken to be relative to the right edge of the parent window. If the parent window is resized, the canvas will be moved to maintain the same relative position.

top - the position of the top edge of the canvas relative to its parent. If this is negative, it is taken to be relative to the bottom edge of the parent window. If the parent window is resized, the canvas will be moved to maintain the same relative position.

width - the width of the canvas. If this is zero or negative, it is taken to be relative to the width of the parent window. If the parent window is resized, the canvas will be resized to maintain the same relative width.

height - the height of the canvas. If this is zero or negative, it is taken to be relative to the height of the parent window. If the parent window is resized, the canvas will be resized to maintain the same relative height.

Canvas

public Canvas(Container parent,
              int left,
              int top,
              int width,
              int height,
              char action)

Construct a new canvas which responds to the mouse.

Parameters:

parent - the parent window of the canvas.

left - the position of the left edge of the canvas relative to its parent. If this is negative, it is taken to be relative to the right edge of the parent window. If the parent window is resized, the canvas will be moved to maintain the same relative position.

top - the position of the top edge of the canvas relative to its parent. If this is negative, it is taken to be relative to the bottom edge of the parent window. If the parent window is resized, the canvas will be moved to maintain the same relative position.

width - the width of the canvas. If this is zero or negative, it is taken to be relative to the width of the parent window. If the parent window is resized, the canvas will be resized to maintain the same relative width.

height - the height of the canvas. If this is zero or negative, it is taken to be relative to the height of the parent window. If the parent window is resized, the canvas will be resized to maintain the same relative height.

action - the command code generated when the mouse button is pressed within this canvas.

Method Detail

add

public int add(DrawingObject object)

Add a new drawing object to the canvas.

Parameters:

object - the object to be drawn.

Returns:

An integer which can be used to restore the drawing to the state it was in before this object was added.

See Also:

mark(), restore(int)

load

public void load(java.io.InputStream stream)
          throws java.io.IOException

Load a drawing from an input stream.

Parameters:

stream - the input stream to read the drawing from.

Throws:

java.io.IOException - an error occurred when trying to read from the stream.

save

public void save(java.io.OutputStream stream)
          throws java.io.IOException

Save a drawing to an output stream.

Parameters:

stream - the output stream to write the drawing into.

Throws:

java.io.IOException - an error occurred when trying to write to the stream.

size

public int size()

Get the number of drawing objects on this canvas.

Returns:

The number of drawing objects on this canvas.

mark

public int mark()

Record the current state of the canvas.

Returns:

An integer which can be used to restore the drawing to its current state.

See Also:

restore(int)

restore

public void restore(int mark)

Restore the canvas to an earlier state.

Parameters:

mark - an integer representing the state to be restored, as returned by add or mark. A value of zero will erase the entire drawing.

See Also:

add(DrawingObject), mark()

removeLast

public void removeLast()

Remove the last drawing object from the canvas.

clear

public void clear()

Clear the entire canvas. This removes all the drawing objects and resets the background colour. If you want to erase the drawing without altering the background colour, use restore(0) instead.

See Also:

restore(int)

setBackground

public void setBackground(java.awt.Color colour)

Set the background colour of the canvas.

Parameters:

colour - the desired background colour. Although this is specified as a java.awt.Color, you can use jewl.Color or jewl.Colour instead.

See Also:

Color, Colour

mouseDown

public boolean mouseDown()

Test if the mouse button is down.

Returns:

True if the mouse button was pressed within the canvas and is still pressed, false otherwise.

mouseMoved

public boolean mouseMoved()

Test if the mouse has been moved since the last time this method was called.

Returns:

True if the mouse button is down and the mouse has been moved since this method was last called, false otherwise.

start

public Point start()

Get the point where the mouse button was pressed.

Returns:

The point where the mouse button was pressed.

startX

public int startX()

Get the X coordinate of the point where the mouse button was pressed. This is the same as start().x.

Returns:

The X coordinate of the point where the mouse button was pressed.

See Also:

start()

startY

public int startY()

Get the Y coordinate of the point where the mouse button was pressed. This is the same as start().y.

Returns:

The Y coordinate of the point where the mouse button was pressed.

See Also:

start()

end

public Point end()

Get the current mouse position.

Returns:

The current mouse position.

endX

public int endX()

Get the X coordinate of the current mouse position. This is the same as end().x.

Returns:

The X coordinate of the current mouse position.

See Also:

end()

endY

public int endY()

Get the Y coordinate of the current mouse position. This is the same as end().y.

Returns:

The Y coordinate of the current mouse position.