Canvas 2D Web Apps/Framework

This chapter introduces the cui2d framework, which is used (and explained in detail) in the following chapters. cui2d is a light-weight collection of JavaScript functions that supports the creation of user interfaces with the canvas 2D context. Thus, instead of starting from scratch in every chapter and introducing GUI elements one by one, a framework is presented that includes these GUI elements. There are a couple of advantages to this approach: Next, the framework is introduced with the help of an example.
 * You can get started and apply the GUI elements without having to work through the details of their implementation.
 * All GUI elements that are discussed in this wikibook are available by including one script file and they (are supposed to) work together without problems.
 * Automatically generated (by JSDoc3) reference documentation of cui2d is available online.
 * It is easier to understand the implementation of individual GUI elements by seeing the big picture of how they work together. In fact, some of the aspects of the implementation just don't make sense without this big picture.

A “Hello, World!” Example
The example of this chapter just shows a page with the text “Hello, World!” using cui2d. It is also available online and should work fine on desktop and mobile web browsers. The parts for downloading the web app to a mobile device are missing but a version that includes them is available online. (See the chapter on iOS web apps for a discussion of these parts.)

Discussion
The first few lines just start the HTML file. The line was included to avoid complications with scaling the content on mobile devices. In fact, the page in this example is not only scalable but can also be rotated and dragged around with two-finger gestures. (With a mouse, the page can only be dragged. Sorry.) However, all these transformations are controlled by the web app instead of the operating system.

The line includes the file ; thus, that file should be in the same directory as the HTML page such that the web browser can find it.

The function  is specified in the   tag at the end of the HTML page and will be called after the page has been loaded.

first sets some default options, which are applied by the cui2d framework before any page is repainted. This makes it possible to change these options for all pages in a single place. After that, it uses the call  to initialize the cui2d framework and start with displaying   which is defined next:

This defines a global variable  and creates a new   object of width 400 pixels and height 300 pixels. The coordinate system for this page has its origin (0,0) in the top, left corner, is 400 pixels wide and 300 pixels high. The content and the behavior of the page is defined by the function, which is specified as third argument in the constructor of the   object and is defined next:

Every GUI component in cui2d has a single “process” function, which repaints the GUI component (or the whole canvas in the case of a page) if the argument  is. Otherwise (if  is not  ), it tries to process the user event. Thus, each process function has two tasks. Even  in this example performs both tasks; however, for user events it only returns , which means that the user event has not been processed. In this example, these events allow the page to be dragged with a mouse or transformed in multiple ways with two-finger gestures. If you change the code to return  then it is assumed that the process function has “consumed” these events and, thus, the page cannot be transformed in any way (except by changing the orientation of a mobile device).

In the case that no event has been specified, the function just writes some text at the center of the page, sets a new fill color and fills the whole page. Note that we render from front to back, which is the standard in cui2d. Also note that “ ” refers to the  object; thus,   and   are just the width and height of.

Lastly, the HTML code defines the  tag with a message in case the canvas is not displayed for some reason; for example, if the web browser does not support the canvas element.

The function  is specified as the handler of the   event; thus, it is called when the page is loaded. The background color is set to black. This background color is sometimes visible when the window of a desktop browser is being resized and during the animation of an orientation change of a mobile device. The WebKit  attributes help to avoid any default user interaction with the HTML page.

The code is rather long for a hello-world example. This is partly due to the fact that it supports multiple platforms, partly due to the definition of customized colors, and partly due to the structure of the cui2d framework, which requires a  object in order to display anything. The next section discusses how the cui2d framework actually works internally.

Implementation of the Render Loop
This section discusses how the cui2d framework renders dynamic graphics, i.e. interactively manipulated graphics and animations. This is particularly useful if you want to modify or extend the framework, or if you want to implement your own framework.

The code in starts with many global variables. Most of them will only make sense once you see how they are used. They are included here just for completeness:

These global variables are followed by the definition of the functions,  , some more user event handlers (which are discussed in a later chapter),  , and. Before reading the code, you should understand how they work together. Consider the following diagram:

As illustrated, the call  in the example starts a chain reaction that in the end calls , i.e.   in our example, which is nothing but  , i.e. the process function that we have defined for our page. Furthermore,  calls itself in an infinite loop such that it keeps calling   to repaint our page whenever necessary (for example, when the user has dragged the page). In technical terms, repainting is “necessary” whenever  has been called since the last repaint. The diagram also includes, which is responsible for the correct geometric transformation of the current page (and for the processing of events for which the process function of the page returns  ).

The definition of  mainly adds a canvas element to the body of the HTML page, adds event listeners (which will be discussed later), and then initializes global variables for various parts of the cui2d framework. In the last two lines, it calls  and.

The only event handler that we mention here is  because it is extremely simple:

I.e., it just calls :

just sets the global variable  to. This variable is checked by :

calls  to repaint the current page if   is   (and also if   is   but that is another story).

In the last line,  calls itself (after a time specified by  ) by using the HTML5 function. Since it always calls itself again, it continues in an endless loop until the web app is closed.

The next function is. However, this function makes heavy use of draggable objects, which will be discussed later. Thus, the discussion of  has to wait until then.

Benefits of a Render Loop
A render loop might appear to be a complicated way to do such a simple thing as calling a render function (i.e. the process function with argument  in cui2d). However, there are good reasons for a render loop: A render loop solves these problems by calling the render function as often as necessary but not more often.
 * The render function should not be called for every user event since there can be too many user events; for example, a new event for every movement of the mouse.
 * In animations, the render function should be called regularly (e.g., 60 frames per second) without any event triggering the rendering.