Canvas Class
Canvas encapsulates all states of drawing into a device (bitmap). This includes a reference to the device itself, and a stack of matrix/clip values. For any given draw call (e.g. drawRect), the geometry of the object being drawn is transformed by the concatenation of all the matrices in the stack. The transformed geometry is clipped by the intersection of all of the clips in the stack. While the Canvas hold the state of the drawing device, the state (style) of the object being drawn is held by Paint, which is provided as a parameter to each of the draw() methods. Paint holds attributes such as color, typeface, textSize, strokeWidth, shader (e.g. gradients, patterns), etc.
Item Index
Methods
clipRect
left
top
right
bottom
region_op
Modify the current clip with the specified rectangle.
Parameters:
-
left
IntegerThe rect to intersect with the current clip
-
top
IntegerThe rect to intersect with the current clip
-
right
IntegerThe rect to intersect with the current clip
-
bottom
IntegerThe rect to intersect with the current clip
-
region_op
SymbolThe region operation to apply to the current clip.
- #difference - Subtract the op region from the first region.
- #intersect - Intersect the two regions.
- #union - Union (inclusive-or) the two regions.
- #xor - Exclusive-or the two regions.
- #reverseDifference - Subtract the first region from the op region.
- #replace - Replace the dst region with the op region.
Returns:
Example:
canvas.clipRect(System.width / 4, System.height / 4, 3 * System.width / 4, 3 * System.height / 4, #intersect );
canvas.drawBitmap(this._img, 0, 0);
canvas.clipRect(System.width / 4, System.height / 4, 3 * System.width / 4, 3 * System.height / 4, #difference );
canvas.drawBitmap(this._img, 0, 0);
concat
matrix
Preconcat the current canvas with the specified matrix.
Parameters:
-
matrix
MatrixThe matrix to preconcatenate with the current matrix
Example:
app.onDraw = function(sender, canvas)
{
// create matrix
var m = new Matrix();
// apply more transformations (translate and rotation)
m.setTranslate(System.width / 2, System.height / 2);
// rotate 45° clockwise
m.preRotate(45);
// apply matrix to canvas
canvas.concat(m);
// draw bitmap
canvas.drawBitmap(this._img, this._img.width / -2, this._img.height / -2);
}
drawBitmap
bitmap
left
top
[paint]
Draw the specified bitmap, with its top/left corner at (x,y), using the specified paint in its original dimension. Note: if the paint contains a maskfilter that generates a mask which extends beyond the bitmap's original width/height, then the bitmap will be drawn as if it were in a Shader with CLAMP mode. Thus the color outside of the original width/height will be the edge color replicated.
Parameters:
Returns:
Example:
// load bitmap file
var bitmap = Bitmap.fromFile("dat://moscrif.jpg");
// draw bitmap in original resolution to the midle of screen
canvas.drawBitmap(bitmap, System.width / 2 - bitmap.width / 2, System.height / 2 - bitmap.height / 2);
drawBitmapMatrix
bitmap
matrix
[paint]
Function draws bitmap to the canvas accoridng to current Matrix. The Matrix contains coordinates about position, rotation, scale etc...
Parameters:
Returns:
Example:
// load bitmap file
var bitmap = Bitmap.fromFile("dat://moscrif.jpg");
// create rotate matrix
var matrix = new Matrix();
matrix.setRotate(45);
// draw bitmap rotated in 45° CW
canvas.drawBitmapMatrix(bitmap, matrix);
drawBitmapNine
bitmap
left
top
right
bottom
[paint]
Draw bitmap to the canvas. The bitmap is resized only on the centre. It is suitable mostly for background for Buttons, TextBoxes and other UI elements, because it saves the image's coordinates in corners.
Parameters:
Returns:
Example:
// load bitmap file
var bitmap = Bitmap.fromFile("dat://moscrif.jpg");
// draw bitmap to the whole screen
canvas.drawBitmapNine(bitmap, 0, 0, System.width, System.height);
drawBitmapRect
bitmap
srcLeft
srcTop
srcRight
srcBottom
dstLeft
dstTop
dstRight
dstRight
[paint]
Draw the source rectangle from source bitmap file to the destination rectangle on the canvas. Note: if the paint contains a maskfilter that generates a mask which extends beyond the bitmap's original width/height, then the bitmap will be drawn as if it were in a Shader with CLAMP mode. Thus the color outside of the original width/height will be the edge color replicated.
Parameters:
-
bitmap
BitmapThe bitmap to be drawn.
-
srcLeft
Integerspecify the subset of the bitmap to be drawn.
-
srcTop
Integerspecify the subset of the bitmap to be drawn.
-
srcRight
Integerspecify the subset of the bitmap to be drawn.
-
srcBottom
Integerspecify the subset of the bitmap to be drawn.
-
dstLeft
IntegerThe destination rectangle where the scaled/translated image will be drawn.
-
dstTop
IntegerThe destination rectangle where the scaled/translated image will be drawn.
-
dstRight
IntegerThe destination rectangle where the scaled/translated image will be drawn.
-
dstRight
IntegerThe destination rectangle where the scaled/translated image will be drawn.
-
[paint]
Paint optionalThe paint used to draw the bitmap, or null.
Returns:
Example:
//load bitmap file
var bitmap = Bitmap.fromFile("dat://moscrif.jpg");
//draw only left half of image to the whole screen
canvas.drawBitmapRect(bitmap, 0, 0, bitmap.width/2, bitmap.height, 0, 0, bitmap.width, System.height);
drawCircle
cx
cy
radius
paint
Draw the specified circle using the specified paint. If radius is <= 0, then nothing will be drawn. The circle will be filled or framed based on the Style in the paint.
Parameters:
Returns:
Example:
canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawRect(100, 100, 50, paint);
drawLine
x0
y0
x1
y1
paint
Draw a line segment with the specified start and stop x,y coordinates, using the specified paint. NOTE: since a line is always "framed", the paint's Style is ignored.
Parameters:
Returns:
Example:
canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawLine(100, 100, 200, 200, paint);
drawOval
left
top
right
bottom
paint
Draw the specified oval using the specified paint. The oval will be filled or framed based on the Style in the paint.
Parameters:
Returns:
Example:
canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawOval(100, 100, 200, 200, paint);
drawPath
path
paint
Draw the specified path using the specified paint. The path will be filled or framed based on the Style in the paint.
Returns:
Example:
canvas.clear(0xffffffff);
// get vectors coordinates
var (l, t, r, b) = this._path.getBounds();
var matrix = new Matrix();
// set scale
var scale = 0.5*System.width / Math.abs(r - l);
matrix.setScale(scale, scale);
// apply scale to vector
this._path.transform(matrix);
// get new image dimensions
(l, t, r, b) = this._path.getBounds();
// move image to the center of screen
this._path.offset(-1*l + (System.width - Math.abs(r - l)) / 2.0, -1*t + (System.height - Math.abs(t - b)) / 2.0);
// draw vector
canvas.drawPath(this._path, new Paint());
drawPoints
pointMode
points
paint
Draw a series of points, interpreted based on the PointMode mode. For #lines mode, count/2 line segments are drawn. For #points mode, each point is drawn centered at its coordinate, and its size is specified by the paint's stroke-width. It draws as a square, unless the paint's cap-type is round, in which the points are drawn as circles. For #lines mode, each pair of points is drawn as a line segment, respecting the paint's settings for cap/join/width. For #polygon mode, the entire array is drawn as a series of connected line segments. Note that, while similar, #kLine and #kPolygon modes draw slightly differently than the equivalent path built with a series of moveTo, lineTo calls, in that the path will draw all of its contours at once, with no interactions if contours intersect each other (think XOR xfermode). drawPoints always draws each element one at a time. @method drawPoints
Parameters:
-
pointMode
SymbolThe region operation to apply to the current clip.
- #points - DrawPoints draws each point separately.
- #lines - DrawPoints draws each pair of points as a line segment.
- #polygon - DrawPoints draws the array of points as a polygon.
-
points
ArrayArray of points to draw
-
paint
PaintThe paint used to draw the points
Example:
canvas.clear(0xffffffff);
var paint = new Paint();
paint.strokeWidth = 15;
paint.strokeCap = #round;
var pts = new Array({x: 100, y: 100}, {x: 150, y: 150}, {x: 50, y: 150});
canvas.drawPoints(#points, pts, paint);
pts = new Array({x: 100, y: 200}, {x: 150, y: 250}, {x: 50, y: 250}, {x: 100, y: 200});
canvas.drawPoints(#polygon, pts, paint);
pts = new Array({x: 100, y: 300}, {x: 150, y: 350}, {x: 150, y: 350}, {x: 50, y: 350}, {x: 50, y: 350}, {x: 100, y: 300});
canvas.drawPoints(#lines, pts, paint);
drawRect
left
top
right
bottom
paint
Draw the specified rectangle using the specified paint. The rectangle will be filled or stroked based on the Style in the paint.
Parameters:
Returns:
Example:
canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawRect(100, 100, 200, 200, paint);
drawRoundRect
left
top
right
bottom
rx
ry
paint
Draw rectangle with rounded corners. The rectangle will be filled or framed based on the Style in the paint.
Parameters:
-
left
IntegerLeft bound of the round rectangle to be drawn
-
top
IntegerTop bound of the round rectangle to be drawn
-
right
IntegerRight bound of the round rectangle to be drawn
-
bottom
IntegerBottom bound of the round rectangle to be drawn
-
rx
IntegerX-radius of the oval used to round the corners
-
ry
IntegerY-radius of the oval used to round the corners
-
paint
PaintThe paint used to draw the circle.
Returns:
Example:
canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawRoundRect(100, 100, 200, 200, 10, 10, paint);
drawText
text
x
y
paint
Draw text to x, y coordinates.
Parameters:
Returns:
Example:
//create paint object for text
var paint = new Paint();
// set color and size of text
paint.color = 0xffff0000;
paint.textSize = 25;
// get dimensions of text
var (w, h) = paint.measureText("Moscrif");
// draw text to the center of screen
canvas.drawText("Moscrif", (System.width - w) / 2, (System.height - h) / 2,paint);
drawTextBox
text
left
top
right
bottom
paint
[align]
Draw text into the box. The text is cut off by the box dimensions
Parameters:
-
text
StringThe text to be drawn.
-
left
IntegerLeft border of the textBox.
-
top
IntegerTop border of the textBox.
-
right
IntegerRight border of the textBox.
-
bottom
IntegerBottom border of the textBox.
-
paint
PaintThe paint used to draw the text.
-
[align]
Symbol optionalSymbol that specifies the vertical text align. * #start * #center * #end
Returns:
Example:
canvas.clear(0xffffffff);
//create paint object for text
var paint = new Paint();
// set color and size of text
paint.color = 0xffff0000;
paint.textSize = 25;
// draw text
canvas.drawTextBox("Moscrif", 0, 0, System.width, System.height, paint, #center);
fromBitmap
bitmap
Creates new canvas for offscreen drawing.
Parameters:
-
bitmap
Bitmap
Returns:
Example:
game.onStart = function()
{
// creates offscreen bitmap
this._bmp = Bitmap.fromRect(200, 100);
// creates canvas for the ofscreen bitmap
this._canvas = Canvas.fromBitmap(this._bmp);
// draws to bitmap - can be something more complex
this._canvas.drawLine(0, 0, 100, 100, new Paint());
}
game.onDraw = function(canvas)
{
canvas.clear(0xffffffff);
// draws the offscreen drawn bitmap
canvas.drawBitmap(this._bmp, 100, 100);
}
restore
() Canvas chainable
This call balances a previous call to save(), and is used to remove all modifications to the matrix/clip state since the last save call. An error occurs if restore() is called more times than save().
Returns:
Example:
canvas.drawText("Moscrif",System.width / 2, System.height / 4, new Paint());
//save "normal" canvas setings
canvas.save();
//scale canvas
canvas.scale(0.5,1);
//draw scaled text
canvas.drawText("Moscrif",System.width / 2, System.height / 2, new Paint());
//restore saved setings
canvas.restore();
//draw unscaled text
canvas.drawText("Moscrif",System.width / 2, 3 * System.height / 4, new Paint());
rotate
degrees
Preconcat the current canvas with the specified rotation.
Parameters:
-
degrees
FloatThe amount to rotate.
Example:
// set center position
var posx = System.width / 2;
var posy = System.height / 2;
// get text dimensions
var (w,h) = paint.measureText("Moscrif");
// 0°
canvas.drawText("Moscrif", posx, posy, paint);
canvas.rotate(90);
// 90°
canvas.drawText("Moscrif", posy, -1*posx + h, paint);
canvas.rotate(90);
// 180°
canvas.drawText("Moscrif", -1*posx + h, -1*posy + h, paint);
canvas.rotate(90);
// 270°
canvas.drawText("Moscrif", -1*posy + h, posx, paint);
save
saveflags=#matrixClip
This call saves the current matrix and clip information, and pushes a copy onto a private stack. Subsequent calls to translate, scale, rotate, skew, concat or clipRect, clipPath all operate on this copy. When the balancing call to restore() is made, this copy is deleted and the previous matrix/clip state is restored.
Parameters:
-
saveflags=#matrixClip
SymbolSave flags, the default is #matrixClip.
- #matrix - Save the matrix state, restoring it on restore().
- #clip - Save the clip state, restoring it on restore().
- #hasAlphaLayer - The layer needs to support per-pixel alpha.
- #fullColorLayer - The layer needs to support 8-bits per color component.
- #clipToLayer - The layer should clip against the bounds argument.
- #matrixClip
- #ARGB_NoClipLayer
- #ARGB_ClipLayer
Returns:
Example:
canvas.drawText("Moscrif",System.width / 2, System.height / 4, new Paint());
// save "normal" canvas setings
canvas.save();
// scale canvas
canvas.scale(0.5,1);
// draw scaled text
canvas.drawText("Moscrif", System.width / 2, System.height / 2, new Paint());
// restore saved setings
canvas.restore();
// draw unscaled text
canvas.drawText("Moscrif", System.width / 2, 3 * System.height / 4, new Paint());
scale
sx
sy
Preconcat the current canvas with the specified scale.
Returns:
Example:
//draw normal text
canvas.drawText("Moscrif",System.width / 2, System.height / 4, new Paint());
//scale canvas
canvas.scale(0.5,1);
//draw scaled text
canvas.drawText("Moscrif",System.width / 2, System.height / 2, new Paint());
skew
sx
sy
Preconcat the current canvas with the specified skew.
Returns:
translate
dx
dy
Preconcat the current canvas with the specified translation.
Returns:
Example:
app.onDraw = function(sender, canvas)
{
canvas.clear(0xff000000);
// move center of canvas from left top corner to center of the center of screen
canvas.translate(System.width / 2, System.height / 2);
// draw bitmap to the center of screen
canvas.drawBitmap(this._img, this._img.width / -2, this._img.height / -2);
}