Canvas

Last Updated On 2021-07-16

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, and circles.

Properties

You can set the below properties in the UI part of the builder.

BackgroundColor - it's a color value which is set to &hffffffff by default.
BackgroundImage - it's a asset value which is set to blank by default.
ExtendMovesOutsideCanvas - it's a boolean value which is set to false by default.
FontSize - it's a non negative float value which is set to 14.0 by default.
HeihMargin - it's a four value which is set to 0,0,0,0 by default.
HeihPadding - it's a four value which is set to 0,0,0,0 by default.
LineWidth - it's a non negative float value which is set to 2.0 by default.
MarginBottom - it's a non negative float value which is set to 0 by default.
MarginLeft - it's a non negative float value which is set to 0 by default.
MarginRight - it's a non negative float value which is set to 0 by default.
MarginTop - it's a non negative float value which is set to 0 by default.
PaddingBottom - it's a non negative float value which is set to 0 by default.
PaddingLeft - it's a non negative float value which is set to 0 by default.
PaddingRight - it's a non negative float value which is set to 0 by default.
PaddingTop - it's a non negative float value which is set to 0 by default.
PaintColor - it's a color value which is set to &hff000000 by default.
TextAlignment - it's a textalignment value which is set to 1 by default.
Visible - it's a visibility value which is set to true by default.

Block Properties

You can set the below blocks properties in the blocks section of the builder.

BackgroundColor

The color of the canvas background.

BackgroundImage

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.

Height

Specifies the `Canvas`'s vertical height, measured in pixels.

HeightPercent

Specifies the vertical height of the Canvas as a percentage of the height of the Screen.

LineWidth

The width of lines drawn on the canvas.

MarginBottom

Property for MarginBottom

MarginLeft

Property for MarginLeft

MarginRight

Property for MarginRight

MarginTop

Property for MarginTop

PaddingBottom

Property for PaddingBottom

PaddingLeft

Property for PaddingLeft

PaddingRight

Property for PaddingRight

PaddingTop

Property for PaddingTop

PaintColor

The color in which lines are drawn

TextAlignment

Determines the alignment of the text drawn by DrawText() or DrawAngle() with respect to the point specified by that command: point at the left of the text, point at the center of the text, or point at the right of the text.

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 width of the Screen.

Methods

You can set the below method blocks in the blocks section of the builder.

Clear

Clears anything drawn on this Canvas but not any background color or image.

DrawArc

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

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

DrawLine

Draws a line between the given coordinates on the canvas.

DrawPoint

Draws a point at the given coordinates on the canvas.

DrawShape

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

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

DrawTextAtAngle

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

GetBackgroundPixelColor

Gets the color of the specified point. This includes the background and any drawn points, lines, or circles but not sprites.

GetPixelColor

Gets the color of the specified point.

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

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.

SetBackgroundPixelColor

Sets the color of the specified point. This differs from DrawPoint by having an argument for color.

Events

You can set the below event blocks in the blocks section of the builder.

Dragged

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

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.

TouchDown

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

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

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.