Wijmo and HTML Events

HTML5 has an eventing mechanism that works for HTML elements, but cannot be used to add events to arbitrary objects, such as controls and collections.

Because of this, Wijmo defines an Event class that is used for implementing all events for all Wijmo classes. The main differences between Wijmo and HTML events are:

1. Wijmo events may be declared by any class (not just HTML elements).
2. Wijmo events are lighter than HTML events, because do not have routing (capturing and bubbling). They target only the object that declared the event.
3. You can add and remove Wijmo event handlers by calling the event's addHandler and removeHandler methods (as opposed to the addEventListener and removeEventListner methods used with HTML events).
4. Every Wijmo event handler takes two parameters: (a) the event sender, and (b) the event arguments.
5. Wijmo follows a pattern where event "XYZ" is raised by a corresponding method "onXYZ", which can be overridden by derived classes to handle the event without attaching any handlers or to customize or even suppress the event.

Wijmo events do not replace HTML events! Applications typically use both. HTML events are used to handle mouse and keyboard interactions that target a control's hostElement or elements defined in the control template. Wijmo events are used to handle control-specific events that are not directly related to the DOM. For example, valueChanged or rowAdded.

The example below shows how you can add handlers to HTML and Wijmo events on an InputNumber control using plain JavaScript:

import { InputNumber } from '@grapecity/wijmo.input';

// create the control
let ctl = new InputNumber('#inputNumber');

// attach a Wijmo event handler
ctl.valueChanged.addHandler(function (s, e) {
    console.log('the value has changed to ' + s.value);
});

// attach an HTML event handler
ctl.addEventListener(ctl.hostElement, 'keypress', function(e) {
    console.log('you pressed ' + e.charCode);
});

The example above shows the syntax using plain JavaScript. Applications that use frameworks such as Angular, React, Aurelia, or Vue have to use the syntax dictated by the framework.

For example, an Angular 1.x would attach a handler to the valueChanged Wijmo event this way:

<wj-input-number
    value-changed="myValueChangedEventHander(s, e)">...

In Angular2, you would do this instead:

<wj-input-number #theControl
    (value-changed)="myValueChangedEventHander(theControl, $event)">...