pf-canvas

Simple jQuery canvas utility - This is a little tool that takes a DOM element and a drawing function to create a canvas.

Examples

First require the module to use it. I suggest using jQuery, too.

var canvas = require('pf-canvas');
var $ = require('jquery');

Use the module to draw a static image.

$(function() {
  // Draw a simple blue square
  canvas('#example-1', function(ctx) {
    // Drawing loop code
    ctx.fillStyle = 'blue';
    ctx.fillRect(10, 10, 80, 80);
  }, {
    // Canvas options
    // You can also set the size of `#example-1` through CSS and not use this
    width: '100px',
    height: '100px'
  });
});

Use the module to draw an animated image which works by looping over the drawing function.

$(function() {
  // Draw a centered, rotating triangle
  var PI23 = Math.PI*2/3, PI43 = Math.PI*4/3;
  var color = '#'+('000000'+(16777216*Math.random()|0).toString(16)).slice(-6);
  var size = 50;
  var theta = 0;

  canvas('#example-2', function(ctx) {
    // Clear the canvas
    var width = ctx.canvas.width, height = ctx.canvas.height;
    var centerX = width/2,        centerY = height/2;
    ctx.clearRect(0, 0, width, height);

    // Draw the triangle
    ctx.fillStyle = color;
    ctx.beginPath();
    ctx.moveTo(centerX + size*Math.cos(theta),      centerY + size*Math.sin(theta));
    ctx.lineTo(centerX + size*Math.cos(theta+PI23), centerY + size*Math.sin(theta+PI23));
    ctx.lineTo(centerX + size*Math.cos(theta+PI43), centerY + size*Math.sin(theta+PI43));
    ctx.closePath();
    ctx.fill();

    // Rotate the triangle every frame
    theta += .03;
  }, {
    // Tell the canvas to redraw on every frame
    redraw: 'always',
    // Tell the canvas to resize on window resize
    resize: true
  });
});

Often times the drawing function needs its own variables such as color, size, and theta in the example above. To scope those variables properly, I prefer to rewrite the above as follows

$(function() {
  var PI23 = Math.PI*2/3, PI43 = Math.PI*4/3;

  canvas('#example-2', (function() {
    // Initialization code
    var color = '#'+('000000'+(16777216*Math.random()|0).toString(16)).slice(-6);
    var size = 50;
    var theta = 0;

    // Loop code
    return function(ctx) {
      var width = ctx.canvas.width, height = ctx.canvas.height;
      var centerX = width/2,        centerY = height/2;
      ctx.clearRect(0, 0, width, height);
      ctx.fillStyle = color;
      ctx.beginPath();
      ctx.moveTo(centerX + size*Math.cos(theta),      centerY + size*Math.sin(theta));
      ctx.lineTo(centerX + size*Math.cos(theta+PI23), centerY + size*Math.sin(theta+PI23));
      ctx.lineTo(centerX + size*Math.cos(theta+PI43), centerY + size*Math.sin(theta+PI43));
      ctx.closePath();
      ctx.fill();
      theta += .03;
    };
  })(), {
    redraw: 'always',
    resize: true
  });
});

The element passed is also returned with a 'draw' event that can be used to manually redraw the canvas.

$(function() {
  canvas('#example-3', function(ctx) {
    // Fill the canvas with a random color
    ctx.fillStyle = '#'+('000000'+(16777216*Math.random()|0).toString(16)).slice(-6);
    ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
  }, {
    width: '100px',
    height: '100px'
  }).click(function() {
    // Trigger the draw event on click
    $(this).trigger('draw');
  });
});

View these examples in examples/index.html. To build it, run

npm install browserify -g
npm run build

API

canvas(elem, draw, options)

• elem (DOM, jQuery, Array, String) - The element to turn into a canvas

elem will be passed through jQuery's jQuery() function to transform it into a jQuery object. Thus it can be a DOM element, a jQuery object, an array of such, a CSS selector string, or HTML string. (See http://api.jquery.com/jQuery/)

• draw (Function) - The drawing function to be looped

draw is a function with signature function(ctx) and ctx being the canvas's CanvasRenderingContext2D. To get the canvas's width and height, you may use ctx.canvas.width and ctx.canvas.height.

• options (Object) - Optional. An object of options
  • id (String) - Default: null. An id to give the canvas element
  • class (String) - Default: null. A class to give the canvas element
  • width (String) - Default: null. Set the width of both elem and the canvas
  • height (String) - Default: null. Set the height of both elem and the canvas
  • redraw (String) - Default: 'never'. Determine when to call the draw function
  • resize (Boolean) - Default: false. Determine when the canvas is resized

redraw is one of 'never', 'always', 'resize'. If set to 'never', draw is only called once upon initialization. If set to always, draw is called constantly according to requestAnimationFrame(). If set to 'resize', draw is called when the window is resized.

resize will update the canvas object to match the dimensions of elem on window resize, if set to true. Note that even if the dimensions of the canvas do not change, a resize will cause the canvas to clear.

• returns (jQuery) - The jQuery wrapped elem variable