2.7 - Events¶

Web page manipulation happens because of events. The events can be some action that the browser has taken, such as downloading a file, or some action a user has taken, such as clicking on a button. We need to discuss five issues:

What events does a browser track?
How do you associate events with specific DOM elements?
What information is contained in an event?
How do you write correct event handlers?
Event hierarchies.

Browser Events¶

There are too many events to discuss in detail here. See HTML DOM Events for a full list. Below is the typical events we will use in a WebGL program to manipulate graphics in a canvas element.

Event	Description
Event	Description
onmousedown	The user presses a mouse button over an element.
onmousedown	The user presses a mouse button over an element.
onmouseup	The user releases a mouse button over an element.
onmouseup	The user releases a mouse button over an element.
onmousemove	The user moves the location of a mouse over an element.
onmousemove	The user moves the location of a mouse over an element.
onclick	The user clicks on an element.
onclick	The user clicks on an element.
onkeydown	The user is pressing a key.
onkeydown	The user is pressing a key.
onkeypress	The user pressed and released a key.
onkeypress	The user pressed and released a key.
onkeyup	The user released a key.
onkeyup	The user released a key.
ondrag	The user is dragging an element.
ondrag	The user is dragging an element.
onwheel	The user is moving the mouse wheel over an element.
onwheel	The user is moving the mouse wheel over an element.

Notice that a key aspect of events is that the mouse is over an element. The location of the user’s mouse determines whether an event “fires” or not. For example, a mouse cursor might be moving over a web page, but only when it is over a specific element will a onmousemove event be generated.

Mapping Events to DOM Elements¶

There are two ways you can associate an event with a specific DOM element.

Add an event attribute to an element’s HTML description.
- Generic example: <element onclick="myScript">
- Specific example: <div onclick="var a = 5; var b = 7; callAbc(a,b);">
Add an event handler to an element using JavaScript.
- JavaScript generic example: object.addEventListener("click", myScript);
- JavaScript specific example: my_button.addEventListener("click", button_click );
- jQuery generic example: $(selector).event(callback_function)
- jQuery specific example: $('#' + control_id).click( button_click );

Method 1 is discouraged for several reasons. It is considered bad design to mix HTML content with JavaScript functionality. And if you use an element attribute, you can only associate one event handler for the element. Method 2 is the preferred way. Not only does this separate content from functionality, you can assign multiple event handlers to a single element if you need to. Using the jQuery functions for assigning event handlers takes care of browser inconsistencies, so those are the ones we will use. See jQuery Events for a complete list of event functions. Note that assigning a callback function to an event should only be done once.

You can remove an event handler using the jQuery unbind method.

jQuery generic example: $(selector).unbind(event, callback)
jQuery specific example: $('#' + control_id).unbind("click", self.html_control_event)

Event Objects¶

An event handler is a function that receives one object as a parameter – an event object. Different types of events create different types of event objects. See HTML DOM Events for a complete list and description of HTML event objects. An event handler function is called each time it’s event occurs. The data in the event object differs between the browsers, so it is best to use jQuery event objects which provide consistent data across all browsers. See Event Objects for a complete list of event data included in jQuery event objects.

The following is a partial list of the data sent to a jQuery event handler for mouse events:

Property	Description
Property	Description
.target	The DOM element that initiated the event.
.target	The DOM element that initiated the event.
.pageX	The mouse position relative to the left edge of the document.
.pageX
.pageY	The mouse position relative to the top edge of the document.
.pageY
.clientX	The mouse position relative to the left edge of the element.
.clientX
.clientY	The mouse position relative to the top edge of the element.
.clientY	The mouse position relative to the top edge of the element.
.which	The specific key or button that was pressed.
.which	The specific key or button that was pressed.

An Example Event Handler¶

Below is an example event handler for an onmousemove event inside a canvas element. It calculates an offset from the previous location of the mouse and uses those offsets to modify angles of rotation for a scene.

/**
 * Process a mouse drag event.
 * @param event A jQuery event object
 */
Function mouse_dragged (event) {
  var delta_x, delta_y;

  if (start_of_mouse_drag) {
    delta_x = event.clientX - start_of_mouse_drag.clientX;
    delta_y = -(event.clientY - start_of_mouse_drag.clientY);

    scene.angle_x += delta_y;
    scene.angle_y -= delta_x;
    scene.render();

    start_of_mouse_drag = event;
    event.preventDefault();
  }
};

Event Hierarchies¶

Consider what happens when a user’s mouse moves across a web page. Let’s assume the mouse just moved over a button, which is inside a <div> element which is inside a <body> element. So there were several HTML elements under the mouse when it moved. Which of the three elements does the event “fire” on? It is actually a complex question and depends on which elements have registered event handlers. Let’s suppose only the button has registered a mouse motion event handler. When the mouse moves over the button its event handler will be called. However, some HTML elements have default event handlers that are built into the browser. For example, moving the mouse can scroll the entire page. A web page is a hierarchy of elements and events travel up this hierarchy when they fire. So in our hypothetical example, the mouse motion event will be passed to the default <div> event handler to be processed. Then the event will be passed to the default <body> event handler to be processed there. Passing an event up the element hierarchy is the default behaviour for events. If you would like an event to be handled by a single event handler, then you must prevent it from being passed up to its parent element by calling preventDefault() on the event object. An example is shown in the above code.

Experimentation¶

In the WebGL demo below you can edit the event handlers. Experiment!

Show: Code Canvas Run Info

event_experiments_events_01.js

/**
 * learn_webgl_events_01.js, By Wayne Brown, Fall 2015
 *
 * These event handlers can modify the characteristics of a scene.
 * These will be specific to a scene's models and the models' attributes.
 */

/**
 * The MIT License (MIT)
 *
 * Copyright (c) 2015 C. Wayne Brown
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

"use strict";

//-------------------------------------------------------------------------
window.Event_experiments_events_01 = function (scene, control_id_list) {

var self = this; // Store a local reference to the new object.

//-----------------------------------------------------------------------
  self.mouse_drag_started = function (event) {

//console.log("started mouse drag event x,y = " + event.clientX + " " + event.clientY + "  " + event.which);
    start_of_mouse_drag = event;
    event.preventDefault();

if (animate_is_on) {
      scene.animate_active = false;
    }
  };

//-----------------------------------------------------------------------
  self.mouse_drag_ended = function (event) {

//console.log("ended mouse drag event x,y = " + event.clientX + " " + event.clientY + "  " + event.which);
    start_of_mouse_drag = null;

event.preventDefault();

if (animate_is_on) {
      scene.animate_active = true;
      self.animate();
    }
  };

//-----------------------------------------------------------------------
  self.mouse_dragged = function (event) {
    var delta_x, delta_y;

//console.log("drag event x,y = " + event.clientX + " " + event.clientY + "  " + event.which);
    if (start_of_mouse_drag) {
      delta_x = event.clientX - start_of_mouse_drag.clientX;
      delta_y = -(event.clientY - start_of_mouse_drag.clientY);
      //console.log("moved: " + delta_x + " " + delta_y);

scene.angle_x += delta_y;
      scene.angle_y -= delta_x;
      scene.render();

start_of_mouse_drag = event;
      event.preventDefault();
    }
  };

//-----------------------------------------------------------------------
  self.key_event = function (event) {
    var bounds, keycode;

bounds = canvas.getBoundingClientRect();
    console.log("bounds = " + bounds.left + " " + bounds.right + "  " + bounds.top + "  " + bounds.bottom);
    console.log("target = " + event.target);
    if (event.clientX >= bounds.left &&
      event.clientX <= bounds.right &&
      event.clientY >= bounds.top &&
      event.clientY <= bounds.bottom) {
      keycode = (event.keyCode ? event.keyCode : event.which);
      console.log(keycode + " keyboard event in canvas");
    }

event.preventDefault();

return false;
  };

//------------------------------------------------------------------------------
  self.html_control_event = function (event) {
    var control;

control = $(event.target);
    if (control) {
      switch (control.attr('id')) {
        case "my_pause":
          if (control.is(":checked"))  {
            animate_is_on = true;
            scene.animate_active = true;
            self.animate();
          } else {
            animate_is_on = false;
            scene.animate_active = false;
          }
      }
    }
  };

//------------------------------------------------------------------------------
  self.animate = function () {

var now, elapsed_time;

if (scene.animate_active) {

now = Date.now();
      elapsed_time = now - previous_time;

if (elapsed_time >= frame_rate) {
        scene.angle_x -= 0.5;
        scene.angle_y += 1;
        scene.render();
        previous_time = now;
      }

requestAnimationFrame(self.animate);
    }
  };

//------------------------------------------------------------------------------
  self.removeAllEventHandlers = function () {
    var j;
    for (j = 0; j < control_id_list.length; j += 1) {
      var control = $('#' + control_id_list);
      if (control) {
        control.unbind("click", self.html_control_event);
      }
    }
  };

//------------------------------------------------------------------------------
  // Constructor code for the class.

// Private variables
  var out = scene.out;    // Debugging and output goes here.
  var canvas = scene.canvas;

// Remember the current state of events
  var start_of_mouse_drag = null;
  var previous_time = Date.now();
  var animate_is_on = scene.animate_active;

// Control the rate at which animations refresh
  var frame_rate = 16; // 16 milliseconds = 1/60 sec

// Add an onclick callback to each HTML control
  var j;
  for (j = 0; j < control_id_list.length; j += 1) {
    var control = $('#' + control_id_list);
    if (control) {
      control.click( self.html_control_event );
    }
  }
}

Experiment with event handlers.

Animate

Shader errors, Shader warnings, Javascript info

Open this webgl program in a new tab or window

Glossary¶

event: something happened, e.g., the mouse moved, a key was hit, a file was downloaded, etc.
event handler: a JavaScript function that will be called when a specific event happens.
event hierarchy: an event is processed by multiple event handlers because the event happened while the mouse cursor was over multiple elements, each element on top of the other.
event object: a JavaScript object whose properties describe an event.

Next Section - 2.8 - Debugging