org.gwtwidgets.client.ui.canvas
Class Canvas

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.Widget
          org.gwtwidgets.client.ui.canvas.Canvas

All Implemented Interfaces:

com.google.gwt.user.client.EventListener, com.google.gwt.user.client.ui.SourcesClickEvents, com.google.gwt.user.client.ui.SourcesFocusEvents, com.google.gwt.user.client.ui.SourcesKeyboardEvents, com.google.gwt.user.client.ui.SourcesMouseEvents, com.google.gwt.user.client.ui.SourcesMouseWheelEvents

Direct Known Subclasses:

FFCanvasImpl, IECanvasImpl, IECanvasStringImpl

public abstract class Canvas
extends com.google.gwt.user.client.ui.Widget
implements com.google.gwt.user.client.ui.SourcesClickEvents, com.google.gwt.user.client.ui.SourcesFocusEvents, com.google.gwt.user.client.ui.SourcesKeyboardEvents, com.google.gwt.user.client.ui.SourcesMouseEvents, com.google.gwt.user.client.ui.SourcesMouseWheelEvents

Abstract base class for canvas widgets. A canvas is a rectangular area which can display vector graphics - scalable shapes such as lines, polygons and images. There exist currently two implementations: the FFCanvasImpl which runs on browsers which support the canvas widget and the IECanvasImpl widget which emulates a canvas in Internet Explorer through VML.

Canvas implementations have no public constructor, instead they are derived from a CanvasFactory. The GWT compiler makes sure that CanvasFactory returns the correct canvas implementation for each browser.

Canvas instances are stateful, similar to a java Graphics object. A stroke, filling, rotation etc. applied affects all subsequent operations. Similar to a stream, a canvas must be flushed for the graphics operations to become visible - the opposite does not hold; there is no guarantee that graphics operations will not be visible without flushing.

The typical lifecycle of a canvas widget looks like:

 Canvas canvas = Canvas.create(640,480);
 panel.add(canvas);
 ...
 canvas.clear();
 ...
 canvas.setStroke(255,0,0,1);
 canvas.drawLine(0,0,100,100);
 ...
 canvas.flush();
 

Note that in order for the canvas to function in Internet Explorer, a special namespace must be used on the HTML page and a special CSS style must be included. For details please consult IECanvasImpl.

Some implementations may not allow you to draw shapes starting at greater coordinates towards lower coordinates, i.e. drawRectangle(100,100,10,10) may fail on certain browsers.

TODO: Define the exact semantics of rotation as they currently vary across implementations. TODO: Formalise whether borders extend or overlay shapes.

Author:

George Georgovassilis g.georgovassilis[at]gmail.com

See Also:

IECanvasImpl, FFCanvasImpl

Field Summary

protected double

rotation Rotation in radians.

Constructor Summary

Canvas()

Method Summary

void	addClickListener(com.google.gwt.user.client.ui.ClickListener listener)
void	addFocusListener(com.google.gwt.user.client.ui.FocusListener listener)
void	addKeyboardListener(com.google.gwt.user.client.ui.KeyboardListener listener)
void	addMouseListener(com.google.gwt.user.client.ui.MouseListener listener)
void	addMouseWheelListener(com.google.gwt.user.client.ui.MouseWheelListener listener)
abstract void	clear() Clears the canvas area and resets fill, stroke, strokeWeight, font and offset.
static Canvas	create(int width, int height) Return a suitable canvas for the browser the application is running in.
static Font	createBitmapFont(java.lang.String bitmapPath, java.lang.String descriptionPath, FontLoadListener listener) Creates a Font object from a bitmap representation.
abstract void	drawArc(double centerLeft, double centerTop, double width, double height, double fromAngle, double toAngle) Draws an arc with the stroke as border and fills it with the current fill.
abstract void	drawImage(com.google.gwt.user.client.Element image, double sx, double sy, double swidth, double sheight, double dx, double dy, double dwidth, double dheight) Draws an image.
abstract void	drawLine(double fromLeft, double fromTop, double toLeft, double toTop) Draws a line.
abstract void	drawPolygon(double[] x, double[] y) Draws a closed polygon with the current stroke as border and fills it with the current fill.
abstract void	drawPolyLine(double[] x, double[] y) Draws a consecutive line with the current stroke as border.
abstract void	drawRectangle(double left, double top, double width, double height) Draws a rectangle with the stroke as border and fills it with the current fill.
abstract void	drawText(java.lang.String text, double x, double y) Draw Text.
abstract void	flush() Makes all changes performed since the last flush visible.
double	getRotation() Gets the currently set rotation
void	onBrowserEvent(com.google.gwt.user.client.Event event)
abstract com.google.gwt.user.client.Element	prepareImage(com.google.gwt.user.client.Element image) On some platforms, it is faster to use prepared images rather than the source image directly.
void	removeClickListener(com.google.gwt.user.client.ui.ClickListener listener)
void	removeFocusListener(com.google.gwt.user.client.ui.FocusListener listener)
void	removeKeyboardListener(com.google.gwt.user.client.ui.KeyboardListener listener)
void	removeMouseListener(com.google.gwt.user.client.ui.MouseListener listener)
void	removeMouseWheelListener(com.google.gwt.user.client.ui.MouseWheelListener listener)
abstract void	setFill(int red, int green, int blue, double alpha) Applies a filling (interior) to surfaces.
abstract void	setFont(Font font) Apply font to all following text drawings.
abstract void	setOffset(double left, double top) Apply offset to all following drawings.
void	setRotation(double angle) Applies a rotation to all following drawing operations.
abstract void	setStroke(int red, int green, int blue, double alpha) Applies a stroke (outline) to all drawings.
abstract void	setStrokeWeight(double weight) Applies stroke width to strokes (outlines).

Methods inherited from class com.google.gwt.user.client.ui.Widget

doAttachChildren, doDetachChildren, getParent, isAttached, onAttach, onDetach, onLoad, onUnload, removeFromParent, setElement

Methods inherited from class com.google.gwt.user.client.ui.UIObject

addStyleDependentName, addStyleName, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkEvents, toString, unsinkEvents

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

rotation

protected double rotation

Rotation in radians.

Constructor Detail

Canvas

public Canvas()

Method Detail

onBrowserEvent

public void onBrowserEvent(com.google.gwt.user.client.Event event)

Specified by:

onBrowserEvent in interface com.google.gwt.user.client.EventListener

Overrides:

onBrowserEvent in class com.google.gwt.user.client.ui.Widget

setRotation

public void setRotation(double angle)

Applies a rotation to all following drawing operations.

Parameters:

angle - Angle in radians

getRotation

public double getRotation()

Gets the currently set rotation

Returns:

angle in radians

setStroke

public abstract void setStroke(int red,
                               int green,
                               int blue,
                               double alpha)

Applies a stroke (outline) to all drawings. For lines and polylines this is the appearance of the line.

Parameters:

red - Red component from 0 ( =none ) to 255 (full),

green - Green component from 0 ( =none ) to 255 (full),

blue - Blue component from 0 ( =none ) to 255 (full),

alpha - Alpha (opacity) component from 0 (=transparent) to 1 (=opaque)

setFill

public abstract void setFill(int red,
                             int green,
                             int blue,
                             double alpha)

Applies a filling (interior) to surfaces. This affects #drawImage(Element, double, double, double, double, double, double), drawPolygon(double[], double[]), and drawText(String, double, double).

Parameters:

red - Red component from 0 ( =none ) to 255 (full),

green - Green component from 0 ( =none ) to 255 (full),

blue - Blue component from 0 ( =none ) to 255 (full),

alpha - Alpha (opacity) component from 0 (=transparent) to 1 (=opaque)

setStrokeWeight

public abstract void setStrokeWeight(double weight)

Applies stroke width to strokes (outlines). Defaults to 1.

Parameters:

weight -

setOffset

public abstract void setOffset(double left,
                               double top)

Apply offset to all following drawings.

Parameters:

left - offset to be added to the X ordinate

top - offset to be added to the Y ordinate

drawRectangle

public abstract void drawRectangle(double left,
                                   double top,
                                   double width,
                                   double height)

Draws a rectangle with the stroke as border and fills it with the current fill.

Parameters:

left -

top -

width -

height -

drawLine

public abstract void drawLine(double fromLeft,
                              double fromTop,
                              double toLeft,
                              double toTop)

Draws a line.

Parameters:

fromLeft -

fromTop -

toLeft -

toTop -

drawArc

public abstract void drawArc(double centerLeft,
                             double centerTop,
                             double width,
                             double height,
                             double fromAngle,
                             double toAngle)

Draws an arc with the stroke as border and fills it with the current fill.

Parameters:

centerLeft -

centerTop -

width -

height -

fromAngle - Angle in radians.

toAngle - Angle in radians.

drawPolyLine

public abstract void drawPolyLine(double[] x,
                                  double[] y)

Draws a consecutive line with the current stroke as border.

Parameters:

x - X ordinates of each line node

y - Y ordinates of each line node.

drawPolygon

public abstract void drawPolygon(double[] x,
                                 double[] y)

Draws a closed polygon with the current stroke as border and fills it with the current fill. It is not defined how convex polygons are to be filled.

Parameters:

x - X ordinates of each line node

y - Y ordinates of each line node.

clear

public abstract void clear()

Clears the canvas area and resets fill, stroke, strokeWeight, font and offset.

flush

public abstract void flush()

Makes all changes performed since the last flush visible.

drawImage

public abstract void drawImage(com.google.gwt.user.client.Element image,
                               double sx,
                               double sy,
                               double swidth,
                               double sheight,
                               double dx,
                               double dy,
                               double dwidth,
                               double dheight)

Draws an image.

Parameters:

image - Image element. Please note that this must be a genuine <img> tag element, using a clipped GWT image will not work. Images are rotated around their center and not around the center of the coordinate system.

sx - Offset from the left in the image from which to start drawing

sy - Offset from the top in the image from which to start drawing

swidth - Width of the part in the image which to draw

sheight - Height of the part in the image which to draw

dx - X position in the canvas to draw the selected image area to

dy - Y position in the canvas to draw the selected image area to

dwidth - Width of the destination area. Can be used for scaling.

dheight - Height of the destination area.

drawText

public abstract void drawText(java.lang.String text,
                              double x,
                              double y)

Draw Text. #setFont(BitmapFontImpl) must be called prior to drawing the first text.

Parameters:

text -

x - X ordinate of the canvas location to draw text to.

y - Y ordinate of the canvas location to draw text to.

setFont

public abstract void setFont(Font font)

Apply font to all following text drawings.

Parameters:

font -

create

public static Canvas create(int width,
                            int height)

Return a suitable canvas for the browser the application is running in.

Parameters:

width - Width in pixels

height - Height in pixels

Returns:

createBitmapFont

public static Font createBitmapFont(java.lang.String bitmapPath,
                                    java.lang.String descriptionPath,
                                    FontLoadListener listener)

Creates a Font object from a bitmap representation.

Parameters:

bitmapPath - URL to bitmap as created by the BitmapFontCreator

descriptionPath - URL to the font description path as created by the BitmapFontCreator

listener - Optional listener to notify when a font is loaded or an error occurred.

Returns:

addClickListener

public void addClickListener(com.google.gwt.user.client.ui.ClickListener listener)

Specified by:

addClickListener in interface com.google.gwt.user.client.ui.SourcesClickEvents

removeClickListener

public void removeClickListener(com.google.gwt.user.client.ui.ClickListener listener)

Specified by:

removeClickListener in interface com.google.gwt.user.client.ui.SourcesClickEvents

addFocusListener

public void addFocusListener(com.google.gwt.user.client.ui.FocusListener listener)

Specified by:

addFocusListener in interface com.google.gwt.user.client.ui.SourcesFocusEvents

removeFocusListener

public void removeFocusListener(com.google.gwt.user.client.ui.FocusListener listener)

Specified by:

removeFocusListener in interface com.google.gwt.user.client.ui.SourcesFocusEvents

addKeyboardListener

public void addKeyboardListener(com.google.gwt.user.client.ui.KeyboardListener listener)

Specified by:

addKeyboardListener in interface com.google.gwt.user.client.ui.SourcesKeyboardEvents

removeKeyboardListener

public void removeKeyboardListener(com.google.gwt.user.client.ui.KeyboardListener listener)

Specified by:

removeKeyboardListener in interface com.google.gwt.user.client.ui.SourcesKeyboardEvents

addMouseListener

public void addMouseListener(com.google.gwt.user.client.ui.MouseListener listener)

Specified by:

addMouseListener in interface com.google.gwt.user.client.ui.SourcesMouseEvents

removeMouseListener

public void removeMouseListener(com.google.gwt.user.client.ui.MouseListener listener)

Specified by:

removeMouseListener in interface com.google.gwt.user.client.ui.SourcesMouseEvents

addMouseWheelListener

public void addMouseWheelListener(com.google.gwt.user.client.ui.MouseWheelListener listener)

Specified by:

addMouseWheelListener in interface com.google.gwt.user.client.ui.SourcesMouseWheelEvents

removeMouseWheelListener

public void removeMouseWheelListener(com.google.gwt.user.client.ui.MouseWheelListener listener)

Specified by:

removeMouseWheelListener in interface com.google.gwt.user.client.ui.SourcesMouseWheelEvents

prepareImage

public abstract com.google.gwt.user.client.Element prepareImage(com.google.gwt.user.client.Element image)

On some platforms, it is faster to use prepared images rather than the source image directly. The following code demonstrates how to handle prepared images:

Element image = DOM.createImage();
DOM.setImgSrc(image,"test.png");
Element preparedImage = canvas.prepareImage(image);
canvas.drawImage(preparedImage,0,0,100,100,0,0,100,100);


Parameters:

image -

Returns:

A prepared image