Tutorials

These tutorials are targeted at people with a reasonable web programming knowledge (HTML and JavaScript languages) and a basic web 3D programming knowledge (WebGL API).

Tutorial 3 : Canvas And Event Listener

This tutorial explains how SpiderGL manages the HTML5 canvas element. We will show some interaction examples by using some of the methods the UI component in order to explain how the event listener works.

View DemoDownload Source

The HTML5 canvas element is the basic component that allows to render interactive Computer Graphics within the Web Browser in an integrated manner, that is without the use of any plugins.
SpiderGL provides a whole component, called UI, to interact with the canvas, by providing methods that wrap the existing WebGL user interface functions and adding new ones.

Because of the large number of methods and tools presents in the UI component, here we will give only a little demonstration of its capabilities. For a more complete overview of the UI component, please refer to the online documentation.

In the code of this tutorial, compared to the earlier lessons, some new JavaScript function has been added and other modified to manage the HTML page behaviour. In particular, the function "tutorial" has been removed and from now on (in all the remaining tutorials), the relevant code will be put in the "CanvasHandler" class, declared at the begin of the page (just after the name space definition), and expanded with the JavaScript "prototype" syntax.
This first method, as the name suggest, contains the initialization code, that for this tutorial is practically none (just two log lines with some general information):

onInitialize: function () {
  log("SpiderGL Version: " + SGL_VERSION_STRING + "\n");
  log("Select the canvas and perform mouse and keyboard events");
}

All the next methods of "CanvasHandler.prototype" are related to the SpiderGL UI component, and manage the interaction with the canvas through the event listener. Let's start from the first: 

onKeyPress: function (key, obj) {
  log("Key typed: " + key);
}

The "onKeyPress" method defines the actions to perform when a key of the keyboard is pressed. This function manages two parameters: the key value, related to letter or number pressed, and a second one which refers to the event JavaScript object. In this example, when a key is pressed, a log message with the value of the key is printed out in the text area. 

onClick: function (button, x, y, obj) {
  log("Mouse click on canvas: (" + x + "," + y + ")");
}

The "onClick" method, as the name suggests, deals with a mouse click event on the canvas area. The parameters of this method are four: the first one containing the numeric code of the mouse button pressed, the next two for the spatial coordinates where the user did the click (respectively the x and the y coordinate), and the last one for the event JavaScript object. In this case, the "onClick" function output a log message with the spatial coordinates related to the click event. 

onDoubleClick: function (button, x, y, obj) {
  log("Mouse double click on canvas: (" + x + "," + y + ")");
}

The method ("onDoubleClick") is similar to the previous one (same parameters). The only difference is that it is call when a double click action is done on the canvas. 

onMouseWheel: function (delta, x, y, obj) {
  if (delta > 0) log("Mouse scroll on canvas: UP");
  if (delta < 0) log("Mouse scroll on canvas: DOWN");
}

To conclude our simple examples of event handling, we describe the "onMouseWheel" method. This method is called whenever the mouse scroll wheel is rotated on the canvas area. The function parameters are the same as the "onClick" and the "onDoubleClick" function, except for the first one, that is replaced by a new parameter ("delta") that expresses the direction of rotation. In our example, every time the "onMouseWheel" event is called the scroll direction is reported in the log area.

We underline that many others user actions can be caught by the event listener (mouse drag, canvas resize, etc.). Because the structure of all of them is similar to the methods shown above, so simply list them:

It is important focus a bit on the line of code just after the end of the "CanvasHandler.prototype" declaration, that is: 

sglHandleCanvasOnLoad("draw-canvas", new CanvasHandler());

This function is maybe the most important of all this tutorial, because it allows to setup the WebGL context and to associate the event handling after the HTML page is loaded.
When the "onload" event is launched, the "handleCanvasOnLoad" method (also part of the User Interface component) is called, passing its parameter (the canvas id, the handler function object, and potential others options) to the UI function "handleCanvas", that is the one that does the job to setup the WebGL context and the SpiderGL canvas event listener.

This is enough for this tutorial. Now, you know how to operate an HTML5 canvas element, linking it with a WebGL context and managing the user interaction using SpiderGL. It is time to render with our library the first objects... and this is what we will do in the next SpiderGL tutorial!

Tutorials List