Canvas event handling

From FlightGear wiki
Revision as of 17:16, 4 March 2014 by TheTom (talk | contribs) (button/modifier state)
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.


Note: This feature is only available in FlightGear versions >= 2.11 !

The Canvas event handling system closely follows the W3C DOM Event Model. If you have already used events in JavaScript and HTML most concepts of the Canvas event system should be already familiar to you. The most notable difference is the missing capture phase, but it is usually not used anyhow.

Listeners - simple Nasal functions - can be attached to every element inside the Canvas and the Canvas itself. Once a certain action - like moving the mouse or pressing a button - occurs the associated listeners are called. We can use this for example to detect whether the mouse has moved over an element or if a certain element has been clicked.

Listen for events

To receive events callback function can be added to elements on a Canvas as well as to the Canvas itself:

canvas.addEventListener("<type>", <func>);
canvas_element.addEventListener("<type>", <func>);

For each placement of a Canvas handling events can be enabled or disabled. A Canvas placed in a PUI widget or as standalone GUI window receives events by default, whereas Canvases placed onto the aircraft model or in the scenery do not receive any events by default.

For standalone GUI windows setting capture-events to 0 or 1 enables or disables handling of events respectively. For a Canvas placed onto a 3d model, setting capture-events inside the placement can be used to activate event handling:

var dlg = canvas.Window.new([152,74]);

# Disable event handling for this window. Events will pass through
# and can reach any window or also object covered by the window.
dlg.setBool("capture-events", 0);

# Place the canvas onto the PFD and enable receiving events
my_canvas.addPlacement({"node": "PFD-Screen", "capture-events": 1});

Event flow

Events always are targeted at a specific element inside the Canvas. Before any event handler is called the propagation path for the event is determined. It consists of the event target itself and all its ancestor elements (Groups) up to and including the Canvas. Afterwards - during the Target Phase - all listeners registered on the event target are called. Finally - during the Bubbling Phase - the event bubbles up the tree, following the propagation path determined in the first step, and all listeners attached to the according elements are called.

Event flow of Canvas Events similar to W3C DOM Event flow [1].

Event classes

var Event = {
  # Name of event type [read-only]
  type: <typename>,

  # Target element [read-only]
  target: <target-element>,

  # Element the currently called listener is attached to [read-only]
  currentTarget: <target-element>,

  # Stop further propagation of event (stop
  # bubbling up to its parents)
  stopPropagation: func()
};

var MouseEvent = {
  parents: [Event],

  # Position in screen coordinates [read-only]
  screenX: <screen-x>,
  screenY: <screen-y>,

  # Position in window/canvas coordinates [read-only]
  clientX: <client-x>,
  clientY: <client-y>,

  # Distance to position of previous event [read-only]
  deltaX: <delta-x>,
  deltaY: <delta-y>,

  # Current click count (number of clicks within a certain
  # time limit. max. 3) [read-only]
  click_count: <click-count>,


  # Buttons/modifiers require FlightGear >= 3.1.0

  # Button which triggered this event [read-only]
  #
  #  0: primary button (usually the left button)
  #  1: auxiliary button (usually the middle button/mouse wheel)
  #  2: secondary button (usually the right button)
  button: <button>,

  # State of all mouse buttons at the time the event has been
  # triggered [read-only]
  buttons: <active-button-mask>,

  # State of all keyboard modifiers at the time the event has
  # been triggered [read-only]
  modifiers: <modifier-mask>,

  # [read-only]
  ctrlKey: <was-ctrl-down>,

  # [read-only]
  shiftKey: <was-shift-down>,

  # [read-only]
  altKey: <was-alt-down>,

  # [read-only]
  metaKey: <was-meta-down>
};

Event types

Type Description DOM equivalent event Bubbles [1]
mousedown Mouse button pressed mousedown Tick icon
mouseup Mouse button released mouseup Tick icon
click mousedown + mouseup have been triggered for this element without moving more than a certain maximum distance click Tick icon
dblclick Two click events have been triggered for this element without moving more than a certain maximum distance and time limit dblclick Tick icon
drag The mouse has been moved with a button down. After dragging has started above an element, all consecutive drag events are sent to this element even if the mouse leaves its area Tick icon
wheel Mouse wheel rotated (see deltaY for direction) wheel Tick icon
mousemove Mouse has moved while beeing inside the area of the target element. mousemove Tick icon
mouseover Mouse has entered a child or the element itself. mouseover is also triggered if the mouse moves from one child element to another. mouseover Tick icon
mouseout Mouse has left a child or the element itself. mouseout is also triggered if the mouse moves from one child element to another. mouseout Tick icon
mouseenter Mouse has entered a child or the element itself. In contrary to mouseover, mouseenter is not triggered if the mouse moves from one child element to another, but only the first time the element or one of its children is entered. mouseenter Cross icon
mouseleave Mouse has left the element and all of its children. In contrary to mouseout, mouseleave is not triggered if the mouse moves from one child element to another, but only if the mouse moves outside the element and all its children. mouseleave Cross icon

Example Code

For the latest examples, please refer to Tom's canvas-gui-demo branch on gitorious. This is also where you can find the following code in $FG_ROOT/Nasal/canvas/gui.nas (note that this example makes use of advanced Nasal concepts, such as anonymous functions, method chaining and lots of embedded/inline code):

# Canvas GUI demo
#
#  Shows an icon in the top-right corner which upon click opens a simple window
#
(func {
var init_gui = setlistener("/nasal/std/loaded", func() {
  removelistener(init_gui);
  var dlg = canvas.Window.new([32,32]);
  dlg.setInt("tf/t[1]", 4)
     .setInt("right", 4);
  var my_canvas = dlg.createCanvas()
                     .setColorBackground(0,0,0,0);
  var root = my_canvas.createGroup();
  canvas.parsesvg(root, "gui/dialogs/images/icon-aircraft.svg");

  my_canvas.addEventListener("click", func
  {
    var dlg = canvas.Window.new([400,300], "dialog");
    var my_canvas = dlg.createCanvas()
                       .set("background", "#f2f1f0");
    var root = my_canvas.createGroup();
    root.addEventListener("click", func(e) { printf("click: screen(%.1f|%.1f) client(%.1f|%.1f) click count = %d", e.screenX, e.screenY, e.clientX, e.clientY, e.click_count); });
    root.addEventListener("dblclick", func(e) { printf("dblclick: screen(%.1f|%.1f) client(%.1f|%.1f)", e.screenX, e.screenY, e.clientX, e.clientY); });
    root.addEventListener("wheel", func(e) { printf("wheel: screen(%.1f|%.1f) client(%.1f|%.1f) %.1f", e.screenX, e.screenY, e.clientX, e.clientY, e.deltaY); });
    var text =
      root.createChild("text")
          .setText("This could be used for building an 'Aircraft Help' dialog.\nYou can also #use it to play around with the new Canvas system :). β")
          .setTranslation(10, 30)
          .setAlignment("left-top")
          .setFontSize(14)
          .setFont("LiberationFonts/LiberationSans-Regular.ttf")
          .set("max-width", 380)
          .setColor(0,0,0);
    var text_move =
      root.createChild("text")
          .setText("Mouse moved over text...")
          .set("character-size", 15)
          .set("font", "LiberationFonts/LiberationSans-Bold.ttf")
          .set("alignment", "left-center")
          .setTranslation(20, 200)
          .set("fill", "#ff0000")
          .hide();
    var visible_count = 0;
    text.addEventListener("mouseover", func text_move.show());
    text.addEventListener("mouseout", func text_move.hide());
  });
});
})();