« Back to index

Drawing and Animation

Table of Contents:

• Ball
• Canvas
• ImageSprite

Ball

A round ‘sprite’ that can be placed on a Canvas, where it can react to touches and drags, interact with other sprites (ImageSprites and other Balls) and the edge of the Canvas, and move according to its property values.

For example, to have a Ball move 4 pixels toward the top of a Canvas every 500 milliseconds (half second), you would set the Speed property to 4 [pixels], the Interval property to 500 [milliseconds], the Heading property to 90 [degrees], and the Enabled property to true. These and its other properties can be changed at any time.

The difference between a Ball and an ImageSprite is that the latter can get its appearance from an image file, while a Ball’s appearance can only be changed by varying its PaintColor and Radius properties.

Properties

Enabled

Controls whether the Ball moves when its speed is non-zero.

Heading

The Ball’s heading in degrees above the positive x-axis. Zero degrees is toward the right of the screen; 90 degrees is toward the top of the screen.

Interval

The interval in milliseconds at which the Ball’s position is updated. For example, if the Interval is 50 and the Speed is 10, then the Ball will move 10 pixels every 50 milliseconds.

OriginAtCenter

Whether the x- and y-coordinates should represent the center of the Ball (true) or its left and top edges (false).

PaintColor

The color of the Ball.

Radius

The distance from the center of the Ball to its edge.

Speed

The speed at which the Ball moves. The Ball moves this many pixels every Interval milliseconds if Enabled is true.

Visible

Sets whether sprite should be visible.

X

The horizontal coordinate of the Ball, increasing as the Ball moves right. If the property OriginAtCenter is true, the coordinate is for the center of the Ball; otherwise, it is for the leftmost point of the Ball.

Y

The vertical coordinate of the Ball, increasing as the Ball moves down. If the property OriginAtCenter is true, the coordinate is for the center of the Ball otherwise, it is for the uppermost point of the Ball.

Z

How the Ball should be layered relative to other Balls and ImageSprites, with higher-numbered layers in front of lower-numbered layers.

Events

CollidedWith(other)

Event handler called when two enabled sprites (Balls or ImageSprites) collide. Note that checking for collisions with a rotated ImageSprite currently checks against its unrotated position. Therefore, collision checking will be inaccurate for tall narrow or short wide sprites that are rotated.

Dragged(startX,startY,prevX,prevY,currentX,currentY)

Event handler for Dragged events. On all calls, the starting coordinates are where the screen was first touched, and the “current” coordinates describe the endpoint of the current line segment. On the first call within a given drag, the “previous” coordinates are the same as the starting coordinates; subsequently, they are the “current” coordinates from the prior call. Note that the Ball won’t actually move anywhere in response to the Dragged event unless MoveTo is specifically called.

EdgeReached(edge)

Event handler called when the Ball reaches an edge of the screen. If Bounce is then called with that edge, the sprite will appear to bounce off of the edge it reached. Edge here is represented as an integer that indicates one of eight directions north(1), northeast(2), east(3), southeast(4), south (-1), southwest(-2), west(-3), and northwest(-4).

Flung(x,y,speed,heading,xvel,yvel)

When a fling gesture (quick swipe) is made on the sprite: 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 (-180 to 180 degrees) of the fling, as well as the x velocity and y velocity components of the fling’s vector.

NoLongerCollidingWith(other)

Event indicating that a pair of sprites are no longer colliding.

TouchDown(x,y)

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

TouchUp(x,y)

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

Touched(x,y)

When the user touches the sprite and then immediately lifts finger: provides the (x,y) position of the touch, relative to the upper left of the canvas.

Methods

Bounce(edge)

Makes this Ball bounce, as if off a wall. For normal bouncing, the edge argument should be the one returned by EdgeReached.

CollidingWith(other)

Indicates whether a collision has been registered between this Ball and the passed other sprite.

MoveIntoBounds()

Moves the sprite back in bounds if part of it extends out of bounds, having no effect otherwise. If the sprite is too wide to fit on the canvas, this aligns the left side of the sprite with the left side of the canvas. If the sprite is too tall to fit on the canvas, this aligns the top side of the sprite with the top side of the canvas.

MoveTo(x,y)

Sets the x and y coordinates of the Ball. If OriginAtCenter is true, the center of the Ball will be placed here. Otherwise, the top left edge of the Ball will be placed at the specified coordinates.

MoveToPoint(coordinates)

Moves the Ball so that its origin is at the specified x and y coordinates.

PointInDirection(x,y)

Turns this Ball to point toward the point with the coordinates (x, y).

PointTowards(target)

Turns this Ball to point towards a given target sprite. The new heading will be parallel to the line joining the centerpoints of the two sprites.

Canvas

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

The BackgroundColor, PaintColor, BackgroundImage, Width, and Height of the Canvas can be set in either the Designer or in the Blocks Editor. The Width and Height are measured in pixels and must be positive.

Any location on the Canvas can be specified as a pair of (X, Y) values, where

• X is the number of pixels away from the left edge of the Canvas
• Y is the number of pixels away from the top edge of the Canvas

There are events to tell when and where a Canvas has been touched or a Sprite (ImageSprite or Ball) has been dragged. There are also methods for drawing points, lines, circles, shapes, arcs, and text.

Properties

BackgroundColor

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.

BackgroundImage

Specifies the name of a file containing the background image for the Canvas.

BackgroundImageinBase64

Set the background image in Base64 format. This requires API level >= 8. For devices with API level less than 8, setting this will end up with an empty background.

ExtendMovesOutsideCanvas

Determines whether moves can extend beyond the canvas borders. Default is false. This should normally be false, and the property is provided for backwards compatibility.

FontSize

Specifies the font size of text drawn on the Canvas.

Height

Specifies the Canvas’s vertical height, measured in pixels.

HeightPercent

Specifies the Canvas’s vertical height as a percentage of the Screen’s Height.

LineWidth

Specifies the width of lines drawn on the Canvas.

PaintColor

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.

TapThreshold

Specifies the movement threshold to differentiate a drag from a tap.

TextAlignment

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

Visible

Specifies whether the Canvas should be visible on the screen. Value is true if the Canvas is showing and false if hidden.

Width

Specifies the horizontal width of the Canvas, measured in pixels.

WidthPercent

Specifies the horizontal width of the Canvas as a percentage of the Screen’s Width.

Events

Dragged(startX,startY,prevX,prevY,currentX,currentY,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.

Flung(x,y,speed,heading,xvel,yvel,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 (-180 to 180 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.

TouchDown(x,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

TouchUp(x,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

Touched(x,y,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.

Methods

Clear()

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

DrawArc(left,top,right,bottom,startAngle,sweepAngle,useCenter,fill)

Draw an arc on Canvas, by drawing an arc from a specified oval (specified by left, top, right & bottom). Start angle is 0 when heading to the right, and increase when rotate clockwise. When useCenter is true, a sector will be drawed instead of an arc. When fill is true, a filled arc (or sector) will be drawed instead of just an outline.

DrawCircle(centerX,centerY,radius,fill)

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

DrawLine(x1,y1,x2,y2)

Draws a line between the given coordinates on the canvas.

DrawPoint(x,y)

Draws a point at the given coordinates on the canvas.

DrawShape(pointList,fill)

Draws a shape on the canvas. pointList should be a list contains sub-lists with two number which represents a coordinate. The first point and last point does not need to be the same. e.g. ((x1 y1) (x2 y2) (x3 y3)) When fill is true, the shape will be filled.

DrawText(text,x,y)

Draws the specified text relative to the specified coordinates using the values of the FontSize and TextAlignment properties.

DrawTextAtAngle(text,x,y,angle)

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

GetBackgroundPixelColor(x,y)

Gets the color of the given pixel, ignoring sprites.

GetPixelColor(x,y)

Gets the color of the given pixel, including sprites.

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.

SaveAs(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).

SetBackgroundPixelColor(x,y,color)

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

ImageSprite

A ‘sprite’ that can be placed on a Canvas, where it can react to touches and drags, interact with other sprites (Balls and other ImageSprites) and the edge of the Canvas, and move according to its property values. Its appearance is that of the image specified in its Picture property (unless its Visible property is false.

To have an ImageSprite move 10 pixels to the left every 1000 milliseconds (one second), for example, you would set the Speed property to 10 [pixels], the Interval property to 1000 [milliseconds], the Heading property to 180 [degrees], and the Enabled property to true. A sprite whose Rotates property is true will rotate its image as the sprite’s heading changes. Checking for collisions with a rotated sprite currently checks the sprite’s unrotated position so that collision checking will be inaccurate for tall narrow or short wide sprites that are rotated. Any of the sprite properties can be changed at any time under program control.

Properties

Enabled

Controls whether the ImageSprite moves when its speed is non-zero.

Heading

The ImageSprite’s heading in degrees above the positive x-axis. Zero degrees is toward the right of the screen; 90 degrees is toward the top of the screen.

Height

The height of the ImageSprite in pixels.

Interval

The interval in milliseconds at which the ImageSprite’s position is updated. For example, if the Interval is 50 and the Speed is 10, then the ImageSprite will move 10 pixels every 50 milliseconds.

Picture

Specifies the path of the sprite’s picture.

Rotates

If true, the sprite image rotates to match the sprite’s heading. If false, the sprite image does not rotate when the sprite changes heading. The sprite rotates around its centerpoint.

Speed

The speed at which the ImageSprite moves. The ImageSprite moves this many pixels every Interval milliseconds if Enabled is true.

Visible

Sets whether sprite should be visible.

Width

The width of the ImageSprite in pixels.

X

The horizontal coordinate of the left edge of the ImageSprite, increasing as the ImageSprite moves right.

Y

The vertical coordinate of the top edge of the ImageSprite, increasing as the ImageSprite moves down.

Z

How the ImageSprite should be layered relative to other Balls and ImageSprites, with higher-numbered layers in front of lower-numbered layers.

Events

CollidedWith(other)

Event handler called when two enabled sprites (Balls or ImageSprites) collide. Note that checking for collisions with a rotated ImageSprite currently checks against its unrotated position. Therefore, collision checking will be inaccurate for tall narrow or short wide sprites that are rotated.

Dragged(startX,startY,prevX,prevY,currentX,currentY)

Event handler for Dragged events. On all calls, the starting coordinates are where the screen was first touched, and the “current” coordinates describe the endpoint of the current line segment. On the first call within a given drag, the “previous” coordinates are the same as the starting coordinates; subsequently, they are the “current” coordinates from the prior call. Note that the ImageSprite won’t actually move anywhere in response to the Dragged event unless MoveTo is specifically called.

EdgeReached(edge)

Event handler called when the ImageSprite reaches an edge of the screen. If Bounce is then called with that edge, the sprite will appear to bounce off of the edge it reached. Edge here is represented as an integer that indicates one of eight directions north(1), northeast(2), east(3), southeast(4), south (-1), southwest(-2), west(-3), and northwest(-4).

Flung(x,y,speed,heading,xvel,yvel)

When a fling gesture (quick swipe) is made on the sprite: 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 (-180 to 180 degrees) of the fling, as well as the x velocity and y velocity components of the fling’s vector.

NoLongerCollidingWith(other)

Event indicating that a pair of sprites are no longer colliding.

TouchDown(x,y)

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

TouchUp(x,y)

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

Touched(x,y)

When the user touches the sprite and then immediately lifts finger: provides the (x,y) position of the touch, relative to the upper left of the canvas.

Methods

Bounce(edge)

Makes this ImageSprite bounce, as if off a wall. For normal bouncing, the edge argument should be the one returned by EdgeReached.

CollidingWith(other)

Indicates whether a collision has been registered between this ImageSprite and the passed other sprite.

MoveIntoBounds()

Moves the sprite back in bounds if part of it extends out of bounds, having no effect otherwise. If the sprite is too wide to fit on the canvas, this aligns the left side of the sprite with the left side of the canvas. If the sprite is too tall to fit on the canvas, this aligns the top side of the sprite with the top side of the canvas.

MoveTo(x,y)

Moves the ImageSprite so that its left top corner is at the specified x and y coordinates.

MoveToPoint(coordinates)

Moves the ImageSprite so that its origin is at the specified x and y coordinates.

PointInDirection(x,y)

Turns this ImageSprite to point toward the point with the coordinates (x, y).

PointTowards(target)

Turns this ImageSprite to point towards a given target sprite. The new heading will be parallel to the line joining the centerpoints of the two sprites.