Â鶹Éç

Methods

addKeyListener

Adds an event listener for a keyboard event.

Synopsis

glow.events.addKeyListener(key, type, callback, context);

Parameters

key

Type

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

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

The function to be called when the event fires.

context

Type

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

| 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 the first matching element. If no element is matched, or the glow.dom module is not loaded, then an exception is raised.

If the parameter is a glow.dom.NodeList, then the listener is attached to the first element. If the NodeList (or NodeList resulting from a selector) is empty, then undefined is returned.

name

Type

The event name.

Listeners for DOM events should not begin with 'on' (i.e. 'click' rather than 'onclick')

callback

Type

The function to be called when the event fires.

context

Type

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

| 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

The object that the event is associated with.

name

Type

The name of the event.

Event names should not start with the word 'on'.

event

Type

Optional

Yes

The event object.

If not specified, a generic event object is created with glow.events.create. Custom event objects should be created using glow.events.create and extended.

Returns

The event object.

Example

LightBox.prototype.close = function () {
  // close the lightbox...
  var event = glow.events.fire(this, 'close');
  // listeners have been called
};

removeListener

Removes a listener created with addListener

Synopsis

glow.events.removeListener(ident);

Parameters

ident

Type

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.