mojombo / primer

                #####  #####   ### ##     ## ##### #####   
                 #   #  #   #   #   ##   ##   #  #  #   #  
                 #   #  #   #   #   ##   ##   #     #   #  
                 ####   ####    #   # # # #   ###   ####   
                 #      #  #    #   # # # #   #     #  #   
                 #      #   #   #   #  #  #   #  #  #   #  
                ###    ###  ## ### ### # ### ##### ###  ## 


Primer. By Tom Preston-Werner.

Primer is a Flash-like API layered on top of Canvas.


INSTALL
----------------------------------------------------------------------------

Just include jQuery and Primer libraries on your page.

  <script src="jquery-1.2.6.min.js" type="text/javascript"></script>
  <script src="primer.js" type="text/javascript"></script>
  

BASIC DRAWING EXAMPLE
-----------------------------------------------------------------------------

In your html create an empty div with an id you can reference later:

  <div id="primer"></div>

In your JavaScript, create a new Primer object for the div, specifying width
and height.

  $(function() {
    var primer = new Primer("#primer", 100, 100)
    
    ...
  })

Now that you have a Primer instance, you can start adding layers to it. Start
by creating an instance of Primer.Layer:

  var square = new Primer.Layer()

Now you can draw on the layer. Let's draw a 20x20 pixel gray square.

  square.fillStyle = "#888888"
  square.fillRect(0, 0, 20, 20)
  
The square won't be drawn until it is added to the Primer instance.

  primer.addChild(square)
  
  
BASIC ANIMATION EXAMPLE
-----------------------------------------------------------------------------

If you follow the instructions in [Basic Drawing Example], you'll have an
object called `square` that has been drawn to the screen. Moving the square
to another place is as easy as setting its `x` and `y` values.

  square.x = 10
  square.y = 10
  
The square has now moved to its new location. Contrary to raw Canvas work,
Primer layers redraw themselves any time they're moved. If we'd like the
square to move slowly across the screen, we can simply increase the `x` value
on an interval.

  function go() {
    square.x += 1
  }
  
  setInterval(go, 100)
  

BASIC EVENTS EXAMPLE
-----------------------------------------------------------------------------

In Primer it's easy to attach event listeners to your Layers. Let's say we
want to log "in" and "out" when you mouse over and mouse out of your gray
square.

  square.mouseover(function() {
    console.log("in")
  })
  
  square.mouseout(function() {
    console.log("out")
  })
  

BASIC TEXT EXAMPLE
-----------------------------------------------------------------------------

Primer implements a basic version of Canvas' text api with standard DOM
elements since no major browser release yet offers this. Let's draw the text
"Hello, World!" in 12px Monaco in red at (0, 0) with a max width of 100px:

  var text = Primer.Layer()
  text.font = "12px Monaco"
  text.fillStyle = "#FF0000"
  text.textAlign = "center"
  text.fillText("Hello, World!", 0, 0, 100)
  
The signature of fillText() is (text, x, y, width). The font attribute takes
standard CSS font values.

The text API currently does not support any transformations except
translation.