com.google.appinventor.components.runtime

Class Canvas

java.lang.Object

com.google.appinventor.components.runtime.VisibleComponent

com.google.appinventor.components.runtime.AndroidViewComponent

com.google.appinventor.components.runtime.Canvas

All Implemented Interfaces:

Component, ComponentContainer

public final class Canvas
extends AndroidViewComponent
implements ComponentContainer

A two-dimensional touch-sensitive rectangular panel on which drawing can be done and sprites can be moved.

Conceptually, a sprite consists of the following layers, from back to front (with items in front being drawn on top):

• background color
• background image
• the "drawing layer", populated through calls to DrawPoint(int,int), #DrawCircle(int,int,float), DrawText(String,int,int), and DrawTextAtAngle(String,int,int,float), and SetBackgroundPixelColor(int,int,int)
• the sprite layer, where sprites with higher Z values are drawn in front of (after) sprites with lower Z values.

To the user, the first three layers are all the background, in terms of the behavior of SetBackgroundPixelColor(int,int,int) and GetBackgroundPixelColor(int,int). For historical reasons, changing the background color or image clears the drawing layer.

Field Summary

Fields inherited from class com.google.appinventor.components.runtime.AndroidViewComponent

container

Fields inherited from interface com.google.appinventor.components.runtime.Component

ACCELEROMETER_SENSITIVITY_MODERATE, ACCELEROMETER_SENSITIVITY_STRONG, ACCELEROMETER_SENSITIVITY_WEAK, ALIGNMENT_CENTER, ALIGNMENT_NORMAL, ALIGNMENT_OPPOSITE, ASSET_DIRECTORY, BUTTON_SHAPE_DEFAULT, BUTTON_SHAPE_OVAL, BUTTON_SHAPE_RECT, BUTTON_SHAPE_ROUNDED, COLOR_BLACK, COLOR_BLUE, COLOR_CYAN, COLOR_DEFAULT, COLOR_DKGRAY, COLOR_GRAY, COLOR_GREEN, COLOR_LTGRAY, COLOR_MAGENTA, COLOR_NONE, COLOR_ORANGE, COLOR_PINK, COLOR_RED, COLOR_WHITE, COLOR_YELLOW, DEFAULT_VALUE_COLOR_BLACK, DEFAULT_VALUE_COLOR_BLUE, DEFAULT_VALUE_COLOR_CYAN, DEFAULT_VALUE_COLOR_DEFAULT, DEFAULT_VALUE_COLOR_DKGRAY, DEFAULT_VALUE_COLOR_GRAY, DEFAULT_VALUE_COLOR_GREEN, DEFAULT_VALUE_COLOR_LTGRAY, DEFAULT_VALUE_COLOR_MAGENTA, DEFAULT_VALUE_COLOR_NONE, DEFAULT_VALUE_COLOR_ORANGE, DEFAULT_VALUE_COLOR_PINK, DEFAULT_VALUE_COLOR_RED, DEFAULT_VALUE_COLOR_WHITE, DEFAULT_VALUE_COLOR_YELLOW, DIRECTION_EAST, DIRECTION_MAX, DIRECTION_MIN, DIRECTION_NONE, DIRECTION_NORTH, DIRECTION_NORTHEAST, DIRECTION_NORTHWEST, DIRECTION_SOUTH, DIRECTION_SOUTHEAST, DIRECTION_SOUTHWEST, DIRECTION_WEST, FONT_DEFAULT_SIZE, LAYOUT_ORIENTATION_HORIZONTAL, LAYOUT_ORIENTATION_VERTICAL, LENGTH_FILL_PARENT, LENGTH_PREFERRED, LENGTH_UNKNOWN, SLIDER_MAX_VALUE, SLIDER_MIN_VALUE, SLIDER_THUMB_VALUE, TOAST_LENGTH_LONG, TOAST_LENGTH_SHORT, TYPEFACE_DEFAULT, TYPEFACE_MONOSPACE, TYPEFACE_SANSSERIF, TYPEFACE_SERIF

Constructor Summary

Constructors

Constructor and Description
Canvas(ComponentContainer container)

Method Summary

Methods

Modifier and Type	Method and Description
void	$add(AndroidViewComponent component) Adds a component to a container.
android.app.Activity	$context() Returns the activity context (which can be retrieved from the root container - aka the form).
Form	$form() Returns the form that ultimately contains this container.
int	BackgroundColor() Returns the button's background color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB.
void	BackgroundColor(int argb) Specifies the Canvas's background color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB.
java.lang.String	BackgroundImage() Returns the path of the canvas background image.
void	BackgroundImage(java.lang.String path) Specifies the path of the canvas background image.
void	Clear() Clears the canvas, without removing the background image, if one was provided.
void	Dragged(float startX, float startY, float prevX, float prevY, float currentX, float currentY, boolean draggedAnySprite) When the user does a drag from one point (prevX, prevY) to another (x, y).
void	DrawCircle(int centerX, int centerY, float radius, boolean fill) Draws a circle (filled in) with the given radius centered at the given coordinates on the canvas
void	DrawLine(int x1, int y1, int x2, int y2) Draws a line between the given coordinates on the canvas.
void	DrawPoint(int x, int y) Draws a point at the given coordinates on the canvas.
void	DrawText(java.lang.String text, int x, int y) Draws the specified text relative to the specified coordinates using the values of the FontSize(float) and TextAlignment(int) properties.
void	DrawTextAtAngle(java.lang.String text, int x, int y, float angle) Draws the specified text starting at the specified coordinates at the specified angle using the values of the FontSize(float) and TextAlignment(int) properties.
protected void	findSpriteCollisions(Sprite movedSprite) Checks if the given sprite now overlaps with or abuts any other sprite or has ceased to do so.
void	Flung(float x, float y, float speed, float heading, float xvel, float yvel, boolean flungSprite) When a fling gesture (quick swipe) is made on the canvas: provides the (x,y) position of the start of the fling, relative to the upper left of the canvas.
float	FontSize()
void	FontSize(float size)
int	GetBackgroundPixelColor(int x, int y) Gets the color of the given pixel, ignoring sprites.
int	GetPixelColor(int x, int y) Gets the color of the given pixel, including sprites.
android.view.View	getView() Returns the View that is displayed in the UI.
void	Height(int height) Set the canvas height The height can only be set to >0 or -1 (automatic) or -2 (fill parent)
float	LineWidth() Returns the currently specified stroke width
void	LineWidth(float width) Specifies the stroke width
int	PaintColor() Returns the currently specified paint color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB.
void	PaintColor(int argb) Specifies the paint color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB.
boolean	ready() Returns whether the layout associated with this view has been computed.
java.lang.String	Save() Saves a picture of this Canvas to the device's external storage.
java.lang.String	SaveAs(java.lang.String fileName) Saves a picture of this Canvas to the device's external storage in the file named fileName.
void	SetBackgroundPixelColor(int x, int y, int color) Sets the color of the given pixel.
void	setChildHeight(AndroidViewComponent component, int height)
void	setChildWidth(AndroidViewComponent component, int width)
int	TextAlignment() Returns the alignment of the canvas's text: center, normal (starting at the specified point in drawText()), or opposite (ending at the specified point in drawText()).
void	TextAlignment(int alignment) Specifies the alignment of the canvas's text: center, normal (starting at the specified point in DrawText() or DrawAngle()), or opposite (ending at the specified point in DrawText() or DrawAngle()).
void	TouchDown(float x, float y) When the user begins touching the canvas (places finger on canvas and leaves it there): provides the (x,y) position of the touch, relative to the upper left of the canvas
void	Touched(float x, float y, boolean touchedAnySprite) When the user touches the canvas and then immediately lifts finger: provides the (x,y) position of the touch, relative to the upper left of the canvas.
void	TouchUp(float x, float y) When the user stops touching the canvas (lifts finger after a TouchDown event): provides the (x,y) position of the touch, relative to the upper left of the canvas
void	Width(int width) Set the canvas width The width can only be set to >0 or -1 (automatic) or -2 (fill parent).

Methods inherited from class com.google.appinventor.components.runtime.AndroidViewComponent

Column, Column, CopyHeight, CopyWidth, getDispatchDelegate, Height, Row, Row, Visible, Visible, Width

Methods inherited from class java.lang.Object

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

Constructor Detail

Canvas

public Canvas(ComponentContainer container)

Method Detail

getView

public android.view.View getView()

Description copied from class: AndroidViewComponent

Returns the View that is displayed in the UI.

Specified by:

getView in class AndroidViewComponent

ready

public boolean ready()

Returns whether the layout associated with this view has been computed. If so, AndroidViewComponent.Width() and AndroidViewComponent.Height() will be properly initialized.

Returns:

true if it is safe to call AndroidViewComponent.Width() and AndroidViewComponent.Height(), false otherwise

$context

public android.app.Activity $context()

Description copied from interface: ComponentContainer

Returns the activity context (which can be retrieved from the root container - aka the form).

Specified by:

$context in interface ComponentContainer

Returns:

activity context

$form

public Form $form()

Description copied from interface: ComponentContainer

Returns the form that ultimately contains this container.

Specified by:

$form in interface ComponentContainer

Returns:

form

$add

public void $add(AndroidViewComponent component)

Description copied from interface: ComponentContainer

Adds a component to a container.

After this method is finished executing, the given component's view must have LayoutParams, even if the component cannot be added to the container until later.

Specified by:

$add in interface ComponentContainer

Parameters:

component - component associated with view

setChildWidth

public void setChildWidth(AndroidViewComponent component,
                 int width)

Specified by:

setChildWidth in interface ComponentContainer

setChildHeight

public void setChildHeight(AndroidViewComponent component,
                  int height)

Specified by:

setChildHeight in interface ComponentContainer

findSpriteCollisions

protected void findSpriteCollisions(Sprite movedSprite)

Checks if the given sprite now overlaps with or abuts any other sprite or has ceased to do so. If there is a sprite that is newly in collision with it, Sprite.CollidedWith(Sprite) is called for each sprite with the other sprite as an argument. If two sprites that had been in collision are no longer colliding, Sprite.NoLongerCollidingWith(Sprite) is called for each sprite with the other as an argument. Collisions are only recognized between sprites that are both Sprite.Visible() and Sprite.Enabled().

Parameters:

movedSprite - the sprite that has just changed position

Width

public void Width(int width)

Set the canvas width The width can only be set to >0 or -1 (automatic) or -2 (fill parent).

Overrides:

Width in class AndroidViewComponent

Parameters:

width -

Height

public void Height(int height)

Set the canvas height The height can only be set to >0 or -1 (automatic) or -2 (fill parent)

Overrides:

Height in class AndroidViewComponent

Parameters:

height -

BackgroundColor

public int BackgroundColor()

Returns the button's background color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB. An alpha of 00 indicates fully transparent and FF means opaque.

Returns:

background color in the format 0xAARRGGBB, which includes alpha, red, green, and blue components

BackgroundColor

public void BackgroundColor(int argb)

Specifies the Canvas's background color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB. An alpha of 00 indicates fully transparent and FF means opaque. The background color only shows if there is no background image.

Parameters:

argb - background color in the format 0xAARRGGBB, which includes alpha, red, green, and blue components

BackgroundImage

public java.lang.String BackgroundImage()

Returns the path of the canvas background image.

Returns:

the path of the canvas background image

BackgroundImage

public void BackgroundImage(java.lang.String path)

Specifies the path of the canvas background image.

See MediaUtil.determineMediaSource(com.google.appinventor.components.runtime.Form, java.lang.String) for information about what a path can be.

Parameters:

path - the path of the canvas background image

PaintColor

public int PaintColor()

Returns the currently specified paint color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB. An alpha of 00 indicates fully transparent and FF means opaque.

Returns:

paint color in the format 0xAARRGGBB, which includes alpha, red, green, and blue components

PaintColor

public void PaintColor(int argb)

Specifies the paint color as an alpha-red-green-blue integer, i.e., 0xAARRGGBB. An alpha of 00 indicates fully transparent and FF means opaque.

Parameters:

argb - paint color in the format 0xAARRGGBB, which includes alpha, red, green, and blue components

FontSize

public float FontSize()

FontSize

public void FontSize(float size)

LineWidth

public float LineWidth()

Returns the currently specified stroke width

Returns:

width

LineWidth

public void LineWidth(float width)

Specifies the stroke width

Parameters:

width -

TextAlignment

public int TextAlignment()

Returns the alignment of the canvas's text: center, normal (starting at the specified point in drawText()), or opposite (ending at the specified point in drawText()).

Returns:

one of Component.ALIGNMENT_NORMAL, Component.ALIGNMENT_CENTER or Component.ALIGNMENT_OPPOSITE

TextAlignment

public void TextAlignment(int alignment)

Specifies the alignment of the canvas's text: center, normal (starting at the specified point in DrawText() or DrawAngle()), or opposite (ending at the specified point in DrawText() or DrawAngle()).

Parameters:

alignment - one of Component.ALIGNMENT_NORMAL, Component.ALIGNMENT_CENTER or Component.ALIGNMENT_OPPOSITE

Touched

public void Touched(float x,
           float y,
           boolean touchedAnySprite)

When the user touches the canvas and then immediately lifts finger: provides the (x,y) position of the touch, relative to the upper left of the canvas. TouchedAnySprite is true if the same touch also touched a sprite, and false otherwise.

Parameters:

x - x-coordinate of the point that was touched

y - y-coordinate of the point that was touched

touchedAnySprite - true if a sprite was touched, false otherwise

TouchDown

public void TouchDown(float x,
             float y)

When the user begins touching the canvas (places finger on canvas and leaves it there): provides the (x,y) position of the touch, relative to the upper left of the canvas

Parameters:

x - x-coordinate of the point that was touched

y - y-coordinate of the point that was touched

TouchUp

public void TouchUp(float x,
           float y)

When the user stops touching the canvas (lifts finger after a TouchDown event): provides the (x,y) position of the touch, relative to the upper left of the canvas

Parameters:

x - x-coordinate of the point that was touched

y - y-coordinate of the point that was touched

Flung

public void Flung(float x,
         float y,
         float speed,
         float heading,
         float xvel,
         float yvel,
         boolean flungSprite)

When a fling gesture (quick swipe) is made on the canvas: provides the (x,y) position of the start of the fling, relative to the upper left of the canvas. Also provides the speed (pixels per millisecond) and heading (0-360 degrees) of the fling, as well as the x velocity and y velocity components of the fling's vector. The value "flungSprite" is true if a sprite was located near the the starting point of the fling gesture.

Parameters:

x - x-coordinate of touched point

y - y-coordinate of touched point

speed - the speed of the fling sqrt(xspeed^2 + yspeed^2)

heading - the heading of the fling

xvel - the speed in x-direction of the fling

yvel - the speed in y-direction of the fling

flungSprite - true if a sprite was flung, false otherwise

Dragged

public void Dragged(float startX,
           float startY,
           float prevX,
           float prevY,
           float currentX,
           float currentY,
           boolean draggedAnySprite)

When the user does a drag from one point (prevX, prevY) to another (x, y). The pair (startX, startY) indicates where the user first touched the screen, and "draggedAnySprite" indicates whether a sprite is being dragged.

Parameters:

startX - the starting x-coordinate

startY - the starting y-coordinate

prevX - the previous x-coordinate (possibly equal to startX)

prevY - the previous y-coordinate (possibly equal to startY)

currentX - the current x-coordinate

currentY - the current y-coordinate

draggedAnySprite - true if Sprite.Dragged(float, float, float, float, float, float) was called for one or more sprites for this segment, false otherwise

Clear

public void Clear()

Clears the canvas, without removing the background image, if one was provided.

DrawPoint

public void DrawPoint(int x,
             int y)

Draws a point at the given coordinates on the canvas.

Parameters:

x - x coordinate

y - y coordinate

DrawCircle

public void DrawCircle(int centerX,
              int centerY,
              float radius,
              boolean fill)

Draws a circle (filled in) with the given radius centered at the given coordinates on the canvas

Parameters:

centerX - x-coordinate of the center of the circle

centerY - y-coordinate of the center of the circle

radius - radius of the circle

fill - true for filled circle; false for circle outline

DrawLine

public void DrawLine(int x1,
            int y1,
            int x2,
            int y2)

Draws a line between the given coordinates on the canvas.

Parameters:

x1 - x coordinate of first point

y1 - y coordinate of first point

x2 - x coordinate of second point

y2 - y coordinate of second point

DrawText

public void DrawText(java.lang.String text,
            int x,
            int y)

Draws the specified text relative to the specified coordinates using the values of the FontSize(float) and TextAlignment(int) properties.

Parameters:

text - the text to draw

x - the x-coordinate of the origin

y - the y-coordinate of the origin

DrawTextAtAngle

public void DrawTextAtAngle(java.lang.String text,
                   int x,
                   int y,
                   float angle)

Draws the specified text starting at the specified coordinates at the specified angle using the values of the FontSize(float) and TextAlignment(int) properties.

Parameters:

text - the text to draw

x - the x-coordinate of the origin

y - the y-coordinate of the origin

angle - the angle (in degrees) at which to draw the text

GetBackgroundPixelColor

public int GetBackgroundPixelColor(int x,
                          int y)

Gets the color of the given pixel, ignoring sprites.

Parameters:

x - the x-coordinate

y - the y-coordinate

Returns:

the color at that location as an alpha-red-blue-green integer, or Component.COLOR_NONE if that point is not on this Canvas

SetBackgroundPixelColor

public void SetBackgroundPixelColor(int x,
                           int y,
                           int color)

Sets the color of the given pixel. This has no effect if the coordinates are out of bounds.

Parameters:

x - the x-coordinate

y - the y-coordinate

color - the color as an alpha-red-blue-green integer

GetPixelColor

public int GetPixelColor(int x,
                int y)

Gets the color of the given pixel, including sprites.

Parameters:

x - the x-coordinate

y - the y-coordinate

Returns:

the color at that location as an alpha-red-blue-green integer, or Component.COLOR_NONE if that point is not on this Canvas

Save

public java.lang.String Save()

Saves a picture of this Canvas to the device's external storage. If an error occurs, the Screen's ErrorOccurred event will be called.

Returns:

the full path name of the saved file, or the empty string if the save failed

SaveAs

public java.lang.String SaveAs(java.lang.String fileName)

Saves a picture of this Canvas to the device's external storage in the file named fileName. fileName must end with one of ".jpg", ".jpeg", or ".png" (which determines the file type: JPEG, or PNG).

Returns:

the full path name of the saved file, or the empty string if the save failed