Moscrif API Docs for: 2012q3
Show:

Canvas Class

Library: core

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.

Methods

clipRect

(
  • left
  • top
  • right
  • bottom
  • region_op
)
Boolean chainable

Modify the current clip with the specified rectangle.

Parameters:

  • left Integer

    The rect to intersect with the current clip

  • top Integer

    The rect to intersect with the current clip

  • right Integer

    The rect to intersect with the current clip

  • bottom Integer

    The rect to intersect with the current clip

  • region_op Symbol

    The 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:

Boolean: Return true if the resulting clip is non-empty.

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
)
chainable

Preconcat the current canvas with the specified matrix.

Parameters:

  • matrix Matrix

    The 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]
)
Canvas chainable

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:

  • bitmap Bitmap

    The bitmap to be drawn

  • left Float

    The position of the left side of the bitmap being drawn

  • top Float

    The position of the top side of the bitmap being drawn

  • [paint] Paint optional

    The paint used to draw the bitmap (default NULL)

Returns:

Canvas: Return instance of itself.

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]
)
Canvas chainable

Function draws bitmap to the canvas accoridng to current Matrix. The Matrix contains coordinates about position, rotation, scale etc...

Parameters:

  • bitmap Bitmap

    The bitmap to be drawn.

  • matrix Matrix

    Matrix included source and target coordinates.

  • [paint] Paint optional

    The paint used to draw the bitmap, or null.

Returns:

Canvas: Return instance of itself.

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]
)
Canvas chainable

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:

  • bitmap Bitmap

    The bitmap to be drawn.

  • left Integer

    Left position of image.

  • top Integer

    Top position of image.

  • right Integer

    Right position of image.

  • bottom Integer

    Bottom position of image.

  • [paint] Paint optional

    The paint used to draw the bitmap, or null.

Returns:

Canvas: Return instance of itself.

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]
)
Canvas chainable

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 Bitmap

    The bitmap to be drawn.

  • srcLeft Integer

    specify the subset of the bitmap to be drawn.

  • srcTop Integer

    specify the subset of the bitmap to be drawn.

  • srcRight Integer

    specify the subset of the bitmap to be drawn.

  • srcBottom Integer

    specify the subset of the bitmap to be drawn.

  • dstLeft Integer

    The destination rectangle where the scaled/translated image will be drawn.

  • dstTop Integer

    The destination rectangle where the scaled/translated image will be drawn.

  • dstRight Integer

    The destination rectangle where the scaled/translated image will be drawn.

  • dstRight Integer

    The destination rectangle where the scaled/translated image will be drawn.

  • [paint] Paint optional

    The paint used to draw the bitmap, or null.

Returns:

Canvas: Return instance of itself.

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
)
Canvas chainable

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:

  • cx Float

    X-coordinate of the center of the cirle to be drawn

  • cy Float

    Y-coordinate of the center of the cirle to be drawn

  • radius Float

    Radius of the cirle to be drawn

  • paint Paint

    The paint used to draw the circle.

Returns:

Canvas: Return instance of itself.

Example:

canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawRect(100, 100, 50, paint);

drawLine

(
  • x0
  • y0
  • x1
  • y1
  • paint
)
Canvas

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:

  • x0 Float

    The x-coordinate of the start point of the line.

  • y0 Float

    The y-coordinate of the start point of the line.

  • x1 Float

    The x-coordinate of the end point of the line.

  • y1 Float

    The y-coordinate of the end point of the line.

  • paint Paint

    The region operation to apply to the current clip.

Returns:

Canvas: Return instance of itself.

Example:

    canvas.clear(0xffffffff);
    var paint = new Paint();
    canvas.drawLine(100, 100, 200, 200, paint);

drawOval

(
  • left
  • top
  • right
  • bottom
  • paint
)
Canvas chainable

Draw the specified oval using the specified paint. The oval will be filled or framed based on the Style in the paint.

Parameters:

  • left Integer

    Left bound of the rect to be drawn

  • top Integer

    Top bound of the rect to be drawn

  • right Integer

    Right bound of the rect to be drawn

  • bottom Integer

    Bottom bound of the rect to be drawn

  • paint Paint

    The paint used to draw the oval.

Returns:

Canvas: Return instance of itself.

Example:

canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawOval(100, 100, 200, 200, paint);

drawPath

(
  • path
  • paint
)
Canvas chainable

Draw the specified path using the specified paint. The path will be filled or framed based on the Style in the paint.

Parameters:

  • path Path

    The path to be drawn.

  • paint Paint

    The paint used to draw the path .

Returns:

Canvas: Return instance of itself.

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
)
chainable

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 Symbol

    The 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 Array

    Array of points to draw

  • paint Paint

    The 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
)
Canvas chainable

Draw the specified rectangle using the specified paint. The rectangle will be filled or stroked based on the Style in the paint.

Parameters:

  • left Integer

    Left border of the rect to be drawn

  • top Integer

    Top border of the rect to be drawn

  • right Integer

    Right border of the rect to be drawn

  • bottom Integer

    Bottom border of the rect to be drawn

  • paint Paint

    The paint used to draw the rect.

Returns:

Canvas: Return instance of itself.

Example:

canvas.clear(0xffffffff);
var paint = new Paint();
canvas.drawRect(100, 100, 200, 200, paint);

drawRoundRect

(
  • left
  • top
  • right
  • bottom
  • rx
  • ry
  • paint
)
Canvas chainable

Draw rectangle with rounded corners. The rectangle will be filled or framed based on the Style in the paint.

Parameters:

  • left Integer

    Left bound of the round rectangle to be drawn

  • top Integer

    Top bound of the round rectangle to be drawn

  • right Integer

    Right bound of the round rectangle to be drawn

  • bottom Integer

    Bottom bound of the round rectangle to be drawn

  • rx Integer

    X-radius of the oval used to round the corners

  • ry Integer

    Y-radius of the oval used to round the corners

  • paint Paint

    The paint used to draw the circle.

Returns:

Canvas: Return instance of itself.

Example:

    canvas.clear(0xffffffff);
    var paint = new Paint();
    canvas.drawRoundRect(100, 100, 200, 200, 10, 10, paint);

drawText

(
  • text
  • x
  • y
  • paint
)
Canvas chainable

Draw text to x, y coordinates.

Parameters:

  • text String

    The text to be drawn.

  • x Integer

    X coordinate of left bottom corner.

  • y Integer

    Y coordinate of left bottom corner.

  • paint Paint

    The paint used to draw the text, or null.

Returns:

Canvas: Return instance of itself.

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]
)
Canvas chainable

Draw text into the box. The text is cut off by the box dimensions

Parameters:

  • text String

    The text to be drawn.

  • left Integer

    Left border of the textBox.

  • top Integer

    Top border of the textBox.

  • right Integer

    Right border of the textBox.

  • bottom Integer

    Bottom border of the textBox.

  • paint Paint

    The paint used to draw the text.

  • [align] Symbol optional

    Symbol that specifies the vertical text align. * #start * #center * #end

Returns:

Canvas: Return instance of itself.

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
)
Canvas static

Creates new canvas for offscreen drawing.

Parameters:

Returns:

Canvas: New instance of Canvas object.

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:

Canvas: Return instance of itself.

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
)
chainable

Preconcat the current canvas with the specified rotation.

Parameters:

  • degrees Float

    The 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
)
Canvas chainable

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 Symbol

    Save 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:

Canvas: Return instance of itself.

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
)
Canvas chainable

Preconcat the current canvas with the specified scale.

Parameters:

  • sx Float

    The amount to scale in X

  • sy Float

    The amount to translate in Y

Returns:

Canvas: Return instance of itself.

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
)
Canvas chainable

Preconcat the current canvas with the specified skew.

Parameters:

  • sx Float

    The amount to skew in X

  • sy Float

    The amount to skew in Y

Returns:

Canvas: Return instance of itself.

translate

(
  • dx
  • dy
)
Boolean chainable

Preconcat the current canvas with the specified translation.

Parameters:

  • dx Float

    The distance to translate in X

  • dy Float

    The distance to translate in Y

Returns:

Boolean: Return instance of itself.

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);
}