Events

Role#

Dana provides a high level abstraction of event management based on event buses.

• An Event can be triggered by mouse clicks, key presses on InputEventBus
• An Event can be triggered from services / managers on EventBus
• An Event can be triggered by data changes on DataEventBus

Declaration#

/**
 * @service
 */
export default $Class.declare("SearchService", {
    statics: /** @lends SearchService */ {
       /**
        * Triggered when a search has been completed
        *
        * @event SearchService#completed
        * @param {Object} results The search results
        */
       "completed": "search.completed"
    },

    methods: /** @lends SearchService.prototype */ {
       /**
        * Start a new search
        *
        * @param {SearchCriteria} The search criteria
        * @fires SearchService#completed
        */
       search: function(criteria) {
          this.dispatch(this.statics.completed, results);
       }
    }
});

Advanced Use#

Dispatch events#

Every Class can send an event on the EventBus with dispatch(eventType, data) method.

By default, the event is triggered asynchronously. The callbacks of the subscribers may not be called right after the event dispatching. Moreover, order of subscription does not guaranty the order of callback’s execution.

If you need to dispatch an event synchronously, use the dispatchSync(eventType, data) method.

Dana defines all the available events throughout statics properties (used by the services in majority).

At application level, you can also trigger your own events.

Event#

An Event is a Class passed through the bus. It is emitted by the publisher and received by the subscriber(s).

An Event have the following properties:

• type: a string containing two fields separated by a dot: <role>.<name>
• data: additional data to attach to the event (can be a Model)
• target: the publisher who emits the event Depending on the nature of the event or of the bus, the Event class may have more properties.

Currently, the following events are declared:

• Event : simple event that can contain data
• KeyEvent : input event containing information about the pressed key

Event buses#

An event bus is a mediator based on the publish–subscribe pattern. It is a singleton that manages events dispatched by publishers and notifies subscribers when a matching message is dispatched.

Dana is offering some important event buses like :

• EventBus : handles application events (from services and views)
• InputEventBus : handles user inputs events (from ‘InputEventAdapter’)
• DataEventBus : handles properties changes

EventBus#

The screens, services and views communicates through the EventBus.

Services and Views are publishers : they dispatch events to the bus.

Screens are subscribers : they listen events from the bus.

Listen to events#

Every Class can listen to events. They should listen events only when necessary : when not active, they should stop listening to the bus.

‘InputEventBus’#

The user inputs are not dispatched by the view but by the InputEventBus.

The dispatcher propagates InputEvent to the active screen. Then, the screen can handle it directly, propagate it to one or more of its children or do a mix of those actions.

It is the responsibility of the Screen to manage the events and route them to the right destination.

Dana captures the native user input events (keys, mouse, …), encapsulate them into an InputEvent and dispatch them to the InputEventBus.

It supports the keyboard event the KeyEvent. Only screens should listen input events.

To listen an input event, you need to add the event into the inputs keyword in the screen declaration. Please refer to the screens.

Keys#

There are three types used for KeyEvent:

• keypress,
• keyup,
• keydown

The KeyEventAdapter makes sure the sequence of key events is as follows :

• When I press a key: keydown-keypress-keyup
• When I maintain a key pressed and release it: ‘keydown’-‘keypress’-…-‘keypress’[isLong=true]-…-‘keypress’[isLong=true]-‘keyup’ The data transported by the event is a Key. It has, among other properties, the keyName and the isLong flag indicating. When isLong flag is set to true, application starts beeing considered in long key press mode.

You can choose to listen all keys by using key.up, key.press or key.down. You can also listen to a specific key by using keyup.{KEY_NAME}, keypress.{KEY_NAME} or keydown.{KEY_NAME} where {KEY_NAME} in the name coming from KeyConst.

DataEventBus#

DataEventBus handles the properties changes and is used by the binding system of the properties.