Version 1.3 glow.events
API Quick Reference
JavaScript is required to use the quick reference
Native browser and custom events
Methods
- addKeyListener
Adds an event listener for a keyboard event.
Synopsis
glow.events.addKeyListener(key, type, callback, context);Parameters
- key
- Type
- String
The key or key combination to listen to.
This parameter starts with modifier keys 'CTRL', 'ALT' and 'SHIFT'. Modifiers can appear in any combination and order and are separated by a '+'.
Following any modifiers is the key character. To specify a character code, use the appropriate escape sequence (e.g. "CTRL+\u0065" = CTRL+e").
To specify a special key, the key character should be replaced with a key identifier, see description below (e.g. "RIGHT" specifies the right arrow key).
- type
- Type
- String
The type of key press to listen to.
Possible values for this parameter are:
- press
- the key is pressed (comparable to a mouse click)
- down
- the key is pushed down
- up
- the key is released
- callback
- Type
- Function
The function to be called when the event fires.
- context
- Type
- Object
- Optional
- Yes
The execution scope of the callback.
If this parameter is not passed then the attachTo object will be the context of the callback.
Returns
A unique identifier for the event suitable for passing to glow.events.removeListener.
Description
Notes for Opera
It is currently impossible to differentiate certain key events in Opera (for example the RIGHT (the right arrow key) and the apostrope (') result in the same code). For this reason pressing either of these keys will result in key listeners specified as "RIGHT" and/or "'" to be fired.
Key Identifiers
The key param uses the following strings to refer to special keys, i.e. non alpha-numeric keys.
- CAPSLOCK
- NUMLOCK
- SCROLLLOCK
- BREAK
- BACKTICK
- BACKSPACE
- PRINTSCREEN
- MENU
- SPACE
- ESC
- TAB
- META
- RIGHTMETA
- ENTER
- F1
- F2
- F3
- F4
- F5
- F6
- F7
- F8
- F9
- F10
- F11
- F12
- INS
- HOME
- PAGEUP
- DEL
- END
- PAGEDOWN
- LEFT
- UP
- RIGHT
- DOWN
Example
glow.events.addKeyListener("CTRL+ALT+a", "press", function () { alert("CTRL+ALT+a pressed"); } ); glow.events.addKeyListener("SHIFT+\u00A9", "down", function () { alert("SHIFT+� pushed") } );- addListener
Adds an event listener to an object (e.g. a DOM Element or Glow widget).
Synopsis
glow.events.addListener(attachTo, name, callback, context);Parameters
- attachTo
- Type
- String | NodeList
The object to attach the event listener to.
If the parameter is a string, then it is treated as a CSS selector and the listener is attached to all matching elements.
If the parameter is a glow.dom.NodeList, then the listener is attached to all elements in the NodeList.
- name
- Type
- String
The event name.
Listeners for DOM events should not begin with 'on' (i.e. 'click' rather than 'onclick')
- callback
- Type
- Function
The function to be called when the event fires.
- context
- Type
- Object
- Optional
- Yes
The execution scope of the callback.
If this parameter is not passed then the attachTo object will be the scope of the callback.
Returns
Number | Undefined
A unique identifier for the event suitable for passing to glow.events.removeListener. If an empty NodeList or CSS selector that returns no elements is passed, then undefined is returned.
Example
glow.events.addListener( '#nav', 'click', function () { alert('nav clicked'); } ); glow.events.addListener( myLightBox, 'close', this.showSurvey, this );- fire
Fires an event on an object.
Synopsis
glow.events.fire(attachedTo, name, event);Parameters
- attachedTo
- Type
- Object
The object that the event is associated with.
- name
- Type
- String
The name of the event.
Event names should not start with the word 'on'.
- event
- Type
- Object | glow.events.Event
- Optional
- Yes
An event object or properties to add to a default event object
If not specified, a generic event object is created. If you provide a simple object, a default Event will be created with the properties from the provided object.
Returns
The event object.
Example
// firing a custom event Ball.prototype.move = function () { // move the ball... // check its position if (this._height == 0) { var event = glow.events.fire(this, 'bounce', { bounceCount: this._bounceCount }); // handle what to do if a listener returned false if ( event.defaultPrevented() ) { this.stopMoving(); } } };// listening to a custom event var myBall = new Ball(); glow.events.addListener(myBall, "bounce", function(event) { if (event.bounceCount == 3) { // stop bouncing after 3 bounces return false; } });- removeListener
Removes a listener created with addListener
Synopsis
glow.events.removeListener(ident);Parameters
- ident
- Type
- Number
An identifier returned from glow.events.addListener.
Returns
Example
var listener = glow.events.addListener(...); glow.events.removeListener(listener);
Classes
- Event
Prototype for event objects passed to listeners.
