Canvas event handling

Canvas - the FlightGear 2D drawing API
Canvas - Main Page Canvas News - for the latest developments Shiva Alternatives - ongoing work for Core Profile support Canvas Efforts - projects using the Canvas system Canvas FAQs - frequently asked questions Canvas - Getting started Canvas Development (core) Canvas Troubleshooting (core) Canvas Sandbox (core) PUI2Canvas (PUI/XML Parser) Canvas GUI Canvas Widgets Canvas Maps Canvas Snippets
RFC
Canvas Instancing Howto:New Canvas Execution Model Canvas SVG Canvas Popout Windows Canvas Scenery Overlays
Frameworks
Canvas Map API (soon deprecated!) Canvas MapStructure Canvas MapStructure Layers MapStructure Snippets Canvas Radar Canvas Animation Framework (WIP) Canvas Plotting Framework (WIP) Canvas MFD Framework Canvas ND Framework Canvas PFD Framework Canvas MCDU Framework Canvas EFB Framework Canvas Wrappers Canvas Glass Cockpit Efforts
Tutorials
Howto:Getting started with Canvas Howto: Canvas Troubleshooting Howto:Adding a canvas to a GUI dialog (PUI!) Howto:Creating a Canvas GUI dialog file (New) Howto:Dynamic Liveries via Canvas (new) Howto:Creating a Canvas GUI Widget Howto:Add a 2D canvas instrument to your aircraft Howto:Parsing 2D Instruments using the Canvas Howto:Creating fullscreen Canvas applications Howto:Use SVG inside a Canvas Howto:Extend the Canvas SVG module Howto:Serializing a Canvas to SVG Howto:Canvas applications as Nasal submodules Howto:Using raster images and nested canvases Canvas HUD Howto:Project 3D to 2D coordinates on desktop canvas
Reference
Canvas Element Group Image Map Path Text Canvas Nasal API MessageBox Layout System Canvas GUI API Canvas draw library Event Handling
Related
Canvas Properties Unifying the 2D rendering backend via canvas Howto:Use a Camera View in an Instrument Howto:Extending Canvas to support rendering 3D models Howto:Extending Canvas to support MathGL
To be ported
Navigation display Map FGCanvas Canvas Nasal/JavaScript Subset
Deprecated by Canvas
Complex Glass Cockpit Avionics
(click on headings to toggle)

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

The Canvas event handling system is heavily inspired by the DOM Event Model. If you have already worked with events in HTML and JavaScript most concepts of the Canvas event system should be already familiar to you.

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 classes

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

  # Target element [read-only]
  target: <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>
};

Event types

Type	Description	DOM equivalent event	Bubbles
mousedown	Mouse button pressed	mousedown
mouseup	Mouse button released	mouseup
click	mousedown + mouseup have been triggered for this element without moving more than a certain maximum distance	click
dblclick	Two click events have been triggered for this element without moving more than a certain maximum distance and time limit	dblclick
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
wheel	Mouse wheel rotated (see deltaY for direction)	wheel
mousemove	Mouse has moved while beeing inside the area of the target element.	mousemove
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
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
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
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

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());
  });
});
})();