Canvas¶
| Category | Requires | Version |
|---|---|---|
| Drawing and Animation | API 21, Android 5.0 Lollipop | 15 |
Overview¶
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.
Permissions
Events¶
Dragged¶
When the user does a drag from one point (prevX, prevY) toanother (x, y). The pair (startX, startY) indicates where theuser first touched the screen, and "draggedAnySprite" indicates whether asprite is being dragged.
| Params | |
|---|---|
| start X | Number |
| start Y | Number |
| prev X | Number |
| prev Y | Number |
| current X | Number |
| current Y | Number |
| dragged Any Sprite | Boolean |
Flung¶
When a fling gesture (quick swipe) is made on the canvas: providesthe (x,y) position of the start of the fling, relative to the upperleft 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 velocitycomponents of the fling's vector. The value "flungSprite" is true if a spritewas located near the the starting point of the fling gesture.
| Params | |
|---|---|
| x | Number |
| y | Number |
| speed | Number |
| heading | Number |
| x vel | Number |
| y vel | Number |
| flung Sprite | Boolean |
Scaled¶
This event is invoked when two-finger pinches. ScaleFactor is the ratio of the average distance between two-fingers from current and previous scale event.
| Params | |
|---|---|
| scale Factor | Number |
Touch Down¶
When the user begins touching the canvas (places finger on canvas andleaves it there): provides the (x,y) position of the touch, relativeto the upper left of the canvas
| Params | |
|---|---|
| x | Number |
| y | Number |
Touch Up¶
When the user stops touching the canvas (lifts finger after aTouchDown event): provides the (x,y) position of the touch, relativeto the upper left of the canvas
| Params | |
|---|---|
| x | Number |
| y | Number |
Touched¶
When the user touches the canvas and then immediately lifts finger: providesthe (x,y) position of the touch, relative to the upper left of the canvas. TouchedAnySpriteis true if the same touch also touched a sprite, and false otherwise.
| Params | |
|---|---|
| x | Number |
| y | Number |
| touched Any Sprite | Boolean |
Methods¶
Clear¶
Clears anything drawn on this Canvas but not any background color or image.
Draw Arc¶
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.
| Params | |
|---|---|
| left | Number |
| top | Number |
| right | Number |
| bottom | Number |
| start Angle | Number |
| sweep Angle | Number |
| use Center | Boolean |
| fill | Boolean |
Draw Circle¶
Draws a circle (filled in) with the given radius centered at the given coordinates on the canvas
| Params | |
|---|---|
| center X | Number |
| center Y | Number |
| radius | Number |
| fill | Boolean |
Draw Line¶
Draws a line between the given coordinates on the canvas.
| Params | |
|---|---|
| x1 | Number |
| y1 | Number |
| x2 | Number |
| y2 | Number |
Draw Point¶
Draws a point at the given coordinates on the canvas.
| Params | |
|---|---|
| x | Number |
| y | Number |
Draw Polygon¶
Creates a polygon with with specified number of sides from a radius.
| Params | |
|---|---|
| center X | Number |
| center Y | Number |
| num Sides | Number |
| poly Radius | Number |
| corner Radius | Number |
| rotation | Number |
| fill | Boolean |
| clear Canvas | Boolean |
Draw Shape¶
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.
| Params | |
|---|---|
| point List | List |
| fill | Boolean |
Draw Text¶
Draws the specified text relative to the specified coordinates using the values of the FontSize and TextAlignment properties.
| Params | |
|---|---|
| text | Text |
| x | Number |
| y | Number |
Draw Text At Angle¶
Draws the specified text starting at the specified coordinates at the specified angle using the values of the FontSize and TextAlignment properties.
| Params | |
|---|---|
| text | Text |
| x | Number |
| y | Number |
| angle | Number |
Get Background Pixel Color¶
Returns: Number
Gets the color of the specified point. This includes the background and any drawn points, lines, or circles but not sprites.
| Params | |
|---|---|
| x | Number |
| y | Number |
Get Pixel Color¶
Returns: Number
Gets the color of the specified point.
| Params | |
|---|---|
| x | Number |
| y | Number |
Save¶
Returns: Text
Saves a picture of this Canvas to the device's external storage. If an error occurs, the Screen's ErrorOccurred event will be called.
Save As¶
Returns: Text
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.
| Params | |
|---|---|
| file Name | Text |
Set Background Pixel Color¶
Sets the color of the specified point. This differs from DrawPoint by having an argument for color.
| Params | |
|---|---|
| x | Number |
| y | Number |
| color | Number |
Properties¶
Background Color¶
Color Default: #FFFFFFFF 
Read Write - Designer Blocks
The color of the canvas background.
Background Image¶
Text Read Write - Designer Blocks
The name of a file containing the background image for the canvas
Extend Moves Outside Canvas¶
Boolean Default: False Read Write - Designer Blocks
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.
Font Bold¶
Boolean Default: False Write - Designer
Property for FontBold
Font Italic¶
Boolean Default: False Write - Designer
Property for FontItalic
Font Size¶
Number Default: 14.0 Read Write - Designer Blocks
The font size of text drawn on the canvas.
Font Typeface¶
Number Default: 0 Write - Designer
Property for FontTypeface
Font Typeface Import¶
Available as Advanced Property
Text Write - Designer Blocks
Set a custom font.
Height¶
Number Read Write - Blocks
Set the canvas heightThe height can only be set to >0 or -1 (automatic) or -2 (fill parent) orto a value less then or equal to LENGTH_PERCENT_TAG (which is laterconverted to pixels.
Height Percent¶
Number Write - Blocks
Specifies the component's vertical height as a percentageof the height of its parent Component.
Line Width¶
Number Default: 2.0 Read Write - Designer Blocks
The width of lines drawn on the canvas.
Paint Color¶
Color Default: #000000FF Read Write - Designer Blocks
The color in which lines are drawn
Text Alignment¶
Number Default: 1 Read Write - Designer Blocks
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¶
Boolean Default: True Read Write - Designer Blocks
Returns true iff the component is visible.
Width¶
Number Read Write - Blocks
Set the canvas widthThe width can only be set to >0 or -1 (automatic) or -2 (fill parent)or to a value less then or equal to LENGTH_PERCENT_TAG (which is laterconverted to pixels.
Width Percent¶
Number Write - Blocks
Specifies the component's horizontal width as a percentageof the Width of its parent Component.