Development/Tutorials/Plasma4/JavaScript/API-Events

From KDE TechBase

Events

Starting in API v2, it is possible register functions as event handlers. To register an event handler, use:

  • addEventListener(String event, Function listener)

The event parameter is the name of the event (see list at end of section for known events) and the handler parameter is the function that will be called whenever the event occurs. Event names are not case sensitive. An event object will be passed into the handler, and the type and behavior of that object is event specific.

Any number of event handlers may be added to a given event, and one handler may be registered to any number of events. The order of execution of event handlers is not guaranteed.

To remove an event handler, use:

  • removeEventListener(String event, Function listener)

The function passed in will no longer be called as a result of the event occurring. Any currently pending calls to the listener are still made, however.

If an event handler is registered using addEventListener, then any callback in the global plasmoid object that may be related to the same event will be suppressed. For instance, if an event handler is registered using addEventListener for the paintInterface event, then plasmoid.paintInterface will not be called.

Input Events (API v2)

Following are the input events which are recognized on the Plasmoid along with the type of event object passed in to registered event listeners:

  • HoverEnter: HoverEvent Object
  • HoverLeave: HoverEvent Object
  • HoverMove: HoverEvent Object
  • KeyPress: KeyEvent Object
  • KeyRelease: KeyEvent Object
  • MouseDoubleClick: MouseEvent Object
  • MouseMove: MouseEvent Object
  • MousePress: MouseEvent Object
  • MouseRelease: MouseEvent Object
  • Wheel: WheelEvent Object

Example:

// anonymous function as a listener on KeyPress
plasmoid.addEventListener('KeyPress', function(a) { print(a.key) })

function output()
{
    print('Hover Event!')
}

function hovered(event)
{
    plasmoid.busy = true
    plasmoid.removeEventListener('HoverEnter', output)
}

function unhovered(event)
{
    plasmoid.busy = false
}

plasmoid.addEventListener('HoverEnter', hovered)
plasmoid.addEventListener('HoverLeave', unhovered)
plasmoid.addEventListener('HoverEnter', output)
plasmoid.addEventListener('HoverLeave', output)

HoverEvent (API v2)

KeyEvent (API v2)

MouseEvent (API v2)

WheelEvent (API v2)

Addon Events (API v3)

The following two events are used in conjuction with Addons. See the Addons documentation for more information on Addons.

  • addonCreated: Object addOn
  • newAddonsAvailable