Canvas

Canvas object.

A Canvas instance is the base surface for any drawing. It is defined by a size and a position.

By default, canvas are exposed without any context (container-only canvas), but before drawing elements can be added to a canvas, the type of context needs to be set.

Nidium is currently supporting the following context types:

The 'document' object has a 2D canvas (document.canvas) created by default. This is called the "the root canvas". Every canvas, except the root canvas, has a parent canvas. Only canvas instances that are descendents of the root canvas are visible on the screen. The parent of a canvas can be set by using methods like Canvas.add.

// Create a new 200x100 canvas (logical pixels)
var canvas = new Canvas(200, 100);

// Add it to the root hierarchy
document.canvas.add(canvas);

// Get its 2D context
var ctx= canvas.getContext("2d");

// Draw something into it
ctx.fillStyle = "blue";
ctx.fillRect(0, 0, 100, 100);

new Canvas(width, height[, options])

Constructs a canvas instance.

The new canvas is orphaned and doesn't belong to the view hierarchy until added as a child to the root hierarchy. A canvas will not be displayed until it is a descendent of the root canvas (document.canvas).

Arguments:
width (Integer)

Width size

height (Integer)

Height size

options (Object)

Options object

lazy (Boolean)

lazy evaluation

add(child)

Add a canvas onto another canvas.

If a canvas is already attached to a parent, it will change it's parent.

Arguments:
child (Canvas)

Canvas instance to add to this instance.

bringToFront()

Brings a canvas in front of another canvas of the z-order.

This method sets the element's z-index by changing the order of the canvas in the parent's children.

clear()

Clears a Canvas by making it transparent.

cursor(type)

Set the cursor for this canvas.

The cursortype may be any of "default"|"arrow"|"beam"|"text"|"pointer"|"grabbing"|"drag"|"hidden"|"none"|"col-resize".

Arguments:
type (String)

Cursor name

getChildren()

Find all the children of a canvas object.

Returns an array of children, from the lowest z-index to the highest z-index. If the canvas does not have any children, it returns an empty array.

Returns: Canvas[]

The list of children of this instance.

getContext(mode) Slow Method

Creates a new Canvas context.

The created Canvas object provides methods and properties for drawing and manipulating images and graphics on a canvas element. A context object includes information about colors, line widths, fonts, and other graphic parameters that can be drawn on a canvas.

Nidium is currently supporting the following context types:

This operation is slow the first time the method is called, and the context can't be changed once it's created.

Arguments:
mode (String)

Context mode: 2d or webgl

Returns: CanvasRenderingContext2D | WebGLRenderingContext | null

The context or null

getFirstChild()

Find the first child of a canvas object.

The first child is the direct child with the lowest z-index.

Returns: Canvas | null

The firsth child of this instance or 'null' if there are no children.

getLastChild()

Find the last child of a canvas object.", The last child is the direct child with the highest z-index.

Returns: Canvas | null

The last child of this instance or 'null'

getNextSibling()

Find the next sibling of a canvas object.

Returns: Canvas | null

The next sibling of this instance or 'null'

getParent()

Find the parent of a canvas object.

If the canvas has no parent, null is returned.

Returns: Canvas | null

The parent object of this instance or 'null'

getPrevSibling()

Find the previous sibling of a canvas object.

Returns: Canvas | null

The previous sibling of this instance or 'null'

getVisibleRect()

Get the outerbounds of the canvas in absolute coordinates.

Returns: Object

dimensions

  • left (Float): left size
  • top (Float): top size
  • width (Float): width size
  • height (Float): height size

hide()

Hides a canvas and all it's children.

insertAfter(insert, reference)

Insert a canvas after another canvas.

Arguments:
insert (Canvas)

Canvas instance to insert

reference (Canvas)

Canvas instance reference

insertBefore(insert, reference)

Insert a canvas before another canvas.

Arguments:
insert (Canvas)

Canvas instance to insert

reference (Canvas)

Canvas instance reference

removeFromParent()

Detach a canvas from it's parent canvas.

If the canvas does not have a parent, this method does nothing. Only canvas instances that are descendents from the root canvas can be displayed. The root canvas does NOT have a parent.

The canvas remains in memory as long as it is a valid javascript instance. This way it can be re-attached to another canvas at a later stage.

sendToBack()

Sends a canvas to the back of the z-order.

This method sets the element's z-index by changing the order of the canvas in the parent's children.

setContext(obj)

Sets the canvas context.

Arguments:
obj (CanvasRenderingContext2D)

Context object

setCoordinates(left, right)

Sets a canvas object at a certain position.

The behavior depends on the 'Canvas.position' type.

Arguments:
left (Integer)

Left point

right (Integer)

Right point

setScale(x_pos, y_pos)

Set a canvas object to a certain scale.

Arguments:
x_pos (Integer)

X position

y_pos (Integer)

Y position

setSize(width, height) Slow Method

Set a canvas object to a certain size.

The operation is slow when the canvas' context is already instantiated with 'Canvas.getContext', because it needs to restructure several things internally. If the canvas context did not have a Canvas.getContext call yet, it is a fast method.

Arguments:
width (Integer)

Width

height (Integer)

Height

setZoom(factor)

Zooms a canvas by a magnifying factor.

The content of the canvas is not redrawn (unlike a 'Canvas.setScale').

Arguments:
factor (Float)

Zoom factor

show()

Show a previously hidden canvas.

translate(left, right)

Translate a canvas object.

Arguments:
left (Integer)

Left point

right (Integer)

Right point

__fixed(readonly)

  • Type: Boolean

Findout if there is a fixed ancestor.

__left(readonly)

  • Type: Float

Get the calculated value for the left property of the canvas.

__outofbound(readonly)

  • Type: Boolean

Findout if the canvas is out of bound.

__top(readonly)

  • Type: Float

Get the calculated value for the top property of the canvas.

__visible(readonly)

  • Type: Boolean

Findout if the canvas will be displayed.

allowNegativeScroll

  • Type: Boolean

Get or set if negative scrolling is allowed.

bottom

  • Type: Float

Get or set the bottom position of the canvas.

The behavior depends on the value of the Canvas.position property.

clientHeight(readonly)

  • Type: Integer

Get the clientHeight of this canvas.

This is the physical height of a canvas including the top and bottom coating.

var canvas = new Canvas(100, 100); // create a 100x100 canvas
canvas.coating = 30; // add a coating (padding) of 30 outside the canvas
console.log(canvas.height) // ---> 100
console.log(canvas.clientHeight) // ---> 160 (30 coating top + 100 height + 30 coating bottom = 160)

clientLeft(readonly)

  • Type: Integer

Get the clientLeft of this canvas.

clientTop(readonly)

  • Type: Integer

Get the clientTop of this canvas.

clientWidth(readonly)

  • Type: Integer

Get the clientWidth of this canvas.

This is the physical width of a canvas including the left and right coating on each side.

var canvas = new Canvas(100, 100); // create a 100x100 canvas
canvas.coating = 30; // add a coating (padding) of 30 outside the canvas
console.log(canvas.width) // ---> 100
console.log(canvas.clientWidth) // ---> 160 (30 coating left + 100 width + 30 coating right = 160)

coating

  • Type: Float

Get or set the coating of a canvas.

Coating is always surrounding the canvas and does not change its size. Setting a coating greater than 0 allows you to draw at negative coordinates, beyond the bounding rectangle of the canvas.

var canvas = new Canvas(100, 100);
canvas.coating = 100;
canvas.left = 300;
canvas.top = 300;

var ctx = canvas.getContext("2d");
ctx.fillStyle = "red";
ctx.fillRect(0, 0, canvas.width, canvas.height);

ctx.strokeStyle = "blue";
ctx.strokeRect(-100, -100, canvas.width+200, canvas.height+200);

document.canvas.add(canvas);

contentHeight(readonly)

  • Type: Integer

Get the contentHeight of this canvas.

contentWidth(readonly)

  • Type: Integer

Get the contentWidth of this canvas.

ctx(readonly)

  • Type: Canvas

Get the context for the canvas.

fluidHeight

  • Type: Boolean

Get or set the fluid-height flag of the canvas.

fluidWidth

  • Type: Boolean

Get or set the fluid-width flag of the canvas.

height

  • Type: Integer

Get or set the height of the Canvas.

The operation is slow when the canvas' context is already instantiated with 'Canvas.getContext', because it needs to restructure several things internally. If the canvas' context did not have a 'Canvas.getContext' call yet, it is a fast method.

var canvas = new Canvas(100, 100);
canvas.height = 150;

id

  • Type: String

Get or set the id for this canvas.

inherrit(readonly)

  • Type: CanvasInherrit

Object instance of CanvasInherrit class.

innerHeight(readonly)

  • Type: Integer

Get the innerHeight of this canvas.

innerWidth(readonly)

  • Type: Integer

Get the innerWidth of this canvas.

left

  • Type: Float

Get or set the position of the top-left corner of the canvas.

The behavior depends on the value of the 'Canvas.position' property.

var canvas = new Canvas(200, 400);
var ctx = canvas.getContext("2d");
document.canvas.add(canvas);
ctx.fillStyle = "red";
ctx.fillRect(0, 0, 100, 100);
canvas.left = 100;

marginBottom

  • Type: Boolean

Get or set the bottom margin for the canvas.

marginLeft

  • Type: Float

Get or set the left margin for the canvas.

marginRight

  • Type: Float

Get or set the right margin for the canvas.

marginTop

  • Type: Boolean

Get or set the top margin for the canvas.

maxHeight

  • Type: Integer

Get or set the maximum height of the Canvas.

maxWidth

  • Type: Integer

Get or set the maximal width of the Canvas.

minHeight

  • Type: Integer

Get or set the minimal height of the Canvas.

minWidth

  • Type: Integer

Get or set the minimal width of the Canvas.

opacity

  • Type: Float

Get or set the opacity of a canvas.

The children of the canvas are affected as well. The value must be between '0.0' and '1.0'.

overflow

  • Type: Boolean

Get or set the overflow of a canvas.

This property defines whether children will be clipped inside the canvas boundaries or not.

var canvas = new Canvas(100, 100);
document.canvas.add(canvas);
var canvas2 = new Canvas(50, 50);
canvas.add(canvas2);
canvas2.left = 50;
canvas2.top = -10;
canvas.overflow = false;

position

  • Type: String

Set the coordinate model that is used for the drawing of the canvas layout.

This may be any of:

  • 'absolute' Placement is relative to the top-left corner of the application window.
  • 'fixed' Placement is relative to the parent canvas but not affected by the scroll position of the parent.
  • 'inline' Placement is relative to the previous sibling. The canvas will be placed to the right of the previous sibling.
  • 'inline-break' Same as inline, but if the canvas does not fit inside his parent, the new canvas will be pushed bellow.
  • 'relative' Placement is relative to the parent-canvas.
var canvas = new Canvas(200, 400);
var ctx = canvas.getContext("2d");
document.canvas.add(canvas);

ctx.fillStyle = "red";
ctx.fillRect(0, 0, 100, 100);

canvas.left = 100; // 100px relative to window.canvas
canvas.top = 50; // 50px relative to window.canvas

// at this stage, canvas is now positioned at (100,50) relative to its parent (window.canvas)

canvas.position = "absolute";

// at this stage, canvas is now positioned at (100,50) relative to the application window

right

  • Type: Float

Get or set the position of the top-right corner of the canvas.

The behavior depends on the value of the Canvas.position property.

scrollLeft

  • Type: Integer

Get or set the horizontal scroll position of the canvas.

The offset is applied to the left property of all with a fixed or absolute position.

This property is useful to implement mouse scrolling or to move multiple canvases at once.

The value can't be negative unless the property 'Canvas.allowNegativeScroll' is set to 'true'.

var canvas = new Canvas(200, 400);
var ctx = canvas.getContext("2d");
document.canvas.add(canvas)
ctx.fillStyle = "red";
ctx.fillRect(0, 0, 100, 100);
canvas.left = 100;
document.canvas.offsetLeft = 10;

scrollTop

  • Type: Integer

Get or set the vertical scroll position of the canvas.",

The offset is applied to the left property of all children. Children with a 'fixed' 'Canvas.position' or an 'absolute' 'Canvas.position' are not impacted.

This property is useful to implement mouse scrolling or to move multiple canvases at once.

The value can't be negative unless the property 'Canvas.allowNegativeScroll' is set to 'true'.

var canvas = new Canvas(200, 400);
var ctx = canvas.getContext("2d");
document.canvas.add(canvas)
ctx.fillStyle = "red";
ctx.fillRect(0, 0, 100, 100);
canvas.top = 100;
document.canvas.offsetTop = 10;

scrollable

  • Type: Boolean

Enable or disable scrolling on a canvas.

var c = new Canvas(200, 400);
c.overflow = false;
c.scrollableY = true;

var c2 = new Canvas(200, 1000);
c2.scrollable = false;

var ctx = c2.getContext("2d");
var grd = ctx.createLinearGradient(0,0,0,1000);
grd.addColorStop(0,"blue");
grd.addColorStop(1,"red");

ctx.fillStyle = grd;
ctx.fillRect(0, 0, 200, 1000);

c.add(c2);
document.canvas.add(c);

scrollableX

  • Type: Boolean

Enable or disable scrolling on X axis for a canvas.

scrollableY

  • Type: Boolean

Enable or disable scrolling on Y axis for a canvas.

staticBottom

  • Type: Boolean

Get or set the static-top flag of the canvas.

staticLeft

  • Type: Boolean

Get or set the static-left flag of the canvas.

staticRight

  • Type: Boolean

Get or set the static-right flag of the canvas.

staticTop

  • Type: Boolean

Get or set the static-right flag of the canvas.

top

  • Type: Float

Get or set the top position of the top-left corner of the canvas.

The behavior depends on the value of the Canvas.position property.

var canvas = new Canvas(200, 400);
var ctx = canvas.getContext("2d");
document.canvas.add(canvas);
ctx.fillStyle = "red";
ctx.fillRect(0, 0, 100, 100);
canvas.top = 100;

visible

  • Type: Boolean

Get or set the visibility of a canvas.

width

  • Type: Integer

Get or set the width of the Canvas.",

The operation is slow when the canvas' context is already instantiated with 'Canvas.getContext', because it needs to restructure several things internally. If the canvas' context did not have a 'Canvas.getContext' call yet, it is a fast method.

var canvas = new Canvas(100, 100);
canvas.width = 150;

Event: change(obj)

Callback for change events.

Change event are fired when the size of the canvas is updated.

Parameters:
obj (Object)

event object

property (String)

Name of the property being changed

value

(String | Float | Integer | Boolean): Value of the property being changed

Event: dblclick(event)

Event fired when the mouse pointer is over the element, and the mouse button has been pressed twice.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Canvas where the event is taking place

which (Integer)

ID of the button pressed

Event: dragend(event)

Event fired when the user has finished dragging a canvas.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Canvas where the event is taking place

source (Canvas)

Source canvas for this event

Event: dragover(event)

Event fired when a canvas is being dragged over a target canvas. This event is fired on the targeted canvas.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Target canvas for this event

source (Canvas)

Source canvas for this event

Event: dragstart(event)

Event fired when the user starts to drag a canvas.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Canvas where the event is taking place

source (Canvas)

Source canvas for this event

Event: drop(event)

Event fired when a canvas has been dragged over a target canvas. This event is fired on the targeted canvas.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Target canvas for this event

source (Canvas)

Source canvas for this event

Event: load(event)

Event fired when the canvas will be draw for the first time.

Parameters:
event (Object)

Event object

Event: mousedown(event)

Event fired when the mouse pointer is over the element, and the mouse button is pressed.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Canvas where the event is taking place

Event: mousemove(event)

Event fired when the mouse pointer is moving over the canvas.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Canvas where the event is taking place

xrel (Integer)

Relative value of x compared to the previous event

yrel (Integer)

Relative value of y compared to the previous event

Event: mouseup(event)

Event fired when the mouse pointer is over the element, and the mouse button has been pressed and then released.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Canvas where the event is taking place

Event: mousewheel(event)

Event fired when the mouse wheel is activated onto a canvas.

Parameters:
event (Object)

Event object

x (Integer)

Horizontal cursor position

y (Integer)

Vertical cursor position

clientX (Integer)

??

clientY (Integer)

??

layerX (Integer)

Horizontal cursor position relative to the canvas

layerY (Integer)

Vertical cursor position relative to the canvas

target (Canvas)

Canvas where the event is taking place

Event: resize(event)

Event fired after a canvas has been resized.

Parameters:
event (Object)

Event object


Caught a mistake or want to contribute to the documentation? Edit this page on GitHub!