Tutorial

Basics

IvanK Lib is JavaScript 2D graphics library for GPU-accelerated <canvas> element. You can create a display object tree, which is rasterized by WebGL using colored or textured triangles. Graphic elements and events in IvanK have nothing to do with Display Object Model (DOM) or Cascading Style Sheets (CSS). You don't have to know DOM or CSS to use IvanK.

Each IvanK application always has a full size of HTML page. If you want it to be bigger or smaller, insert it into another webpage using <iframe> tag.

The center of coordinate system is the top left corner. X axis goes right, Y goes down. Metric units are pixels. Background of IvanK is transparent, so you can see the web page and other HTML elements behind the IFRAME.

The root of display tree is always a Stage object. It's created using var s = new Stage("canvas_id"), where "canvas_id" is an ID of target Canvas.

Class hierarchy

Event model

A class, which can dispatch or listen to events, should be a descendant of EventDispatcher. It has methods dispatchEvent, addEventListener and removeEventListener.

Some events are dispatched automatically by IvanK, such as ADDED_TO_STAGE or mouse events. You can listen to them in your code.

Mouse Events

As you move the mouse cursor over your IvanK.js application, the system is registering a Path, which is a list of InteractiveObjects located under cursor. The Path goes from Stage to the End - the last, "deepest" object on the path. It may look like this:

stage:Stage -> form:Sprite -> button:Sprite -> label:TextField

All mouse events are dispatched on the End of Path and they are "bubbling up" to the Stage. Bubbling means, that event is dispatched on the End - in label, and it "bubbles up" from child to parent, up to the stage being dispatched on every object in that Path.

MouseEvent.target is the End of Path of that event. MouseEvent.currentTarget is an object, which currently dispatches that event.

InteractiveObject.mouseEnabled says, whether that object can be at the End of the Path.

DisplayObjectContainer.mouseChildren says, whether its children can occur in the Path (it still "owns" their area).

Stage.focus is the latest End, which was clicked. KeyboardEvents are dispatched on Stage.focus.

With IvanK, you can disable the standard context menu (usually shown on right mouse click). It is disabled, when stage has MouseEvent.RIGHT_CLICK listener.

3D graphics

IvanK.js is high-level library and it does not offer an access to GPU buffers, shaders or any WebGL commands. The main 3D function is Graphics.drawTriangles3D, which allows to draw colored or textured triangles. Indices can range from 0 to 65535, because of 16-bit index size limitation of WebGL.

Every DisplayObject has it's 3D transformation properties: x/y/z, scaleX/scaleY/scaleZ and rotationX/rotationY/rotationZ. The whole transformation can be accessed as matrix through DisplayObject.transform.matrix3D. It can be used to connect the graphics with physical engines etc.

Best practice

When you are working on a large project (larger than any of demos), it is very useful to inherit your classes from IvanK classes and put some logic into them. Other good practice is, that each "node" in display tree accesses only the direct children and dispatches events to parent. It does it's work and does not care about sub-children or objects above it.

Here is an example of how to "extend classes" of IvanK: Custom classes demo.

Textures in WebGL

When you are testing your app locally, you may see some errors when loading textures. For security reasons, JavaScript is allowed to access only resources from the same domain. So, if you want to use images in your app, you must upload your app to a web server, or install some local HTTP server (LightTPD) or turn off the security mode (e.g. "--disable-web-security" parameter for Chrome).