PERGOLA LOGO

pergola.Key

pergola.Key is not subclassed to pergola.Class.

This class manages keyboard input in SVG, and produces equal results in all major implementations. For extensive information about this class read the SVG magazine Keyboard Class article.

Features: pass events to default handlers or to custom handlers for each type of event independently, or to a unique handler; end input on <ENTER> and/or pointer events; prevent certain type of actions in the interface from ending input; instance self-destruction, if specified. Learn more in the KEY CLASS section of the Tutorial.

class

PROPERTIES

active

References the current typing process, which can be terminated from other contexts like this:

pergola.Key.active.release();

METHODS

keydown(evt)

Default keydown handler. Invoked as method of this handle. Scans the following key codes:

  • 8 (BACKSPACE) : default prevented; deletes last character (this must have a value property and a setValue() method)
  • 46 (DELETE) : no action (needs cursor position handling)
  • 9 (TAB) : default prevented;
  • 13 (ENTER) : ends input
  • 112–123 (function keys F1–F12) : default prevented;
Note: this function does what the “keydown” event was designed for: key codes scan.

keypress(evt)

Default keypress handler for pergola.Key. Invoked as method of this handle. Filters character codes 32–65535. Use for regular typing. Note: this function does what the “keypress” event was designed for: character codes scan.

keyup(evt)

Default keyup handler for pergola.Key. Invoked as method of this handle. No action. Override if needed.

keypressNum(evt)

Assign this method to the keypress property of the callback object to override the default keypress handler. Invoked as method of this handle. Filters digits. Note: this function does what the “keypress” event was designed for: character codes scan.

keypressInt(evt)

Assign this method to the keypress property of the callback object to override the default keypress handler. Invoked as method of this handle. Filters integers. Note: this function does what the “keypress” event was designed for: character codes scan.

keypressPos(evt)

Assign this method to the keypress property of the callback object to override the default keypress handler. Invoked as method of this handle. Filters positive numbers. Note: this function does what the “keypress” event was designed for: character codes scan.

keypressPosInt(evt)

Assign this method to the keypress property of the callback object to override the default keypress handler. Invoked as method of this handle. Filters positive integers. Note: this function does what the “keypress” event was designed for: character codes scan.

keypressHex(evt)

Assign this method to the keypress property of the callback object to override the default keypress handler. Invoked as method of this handle. Filters hexadecimal digits. Note: this function does what the “keypress” event was designed for: character codes scan.

prototype

PROPERTIES

None

METHODS

register(object)

The method expects an initialization object whose properties are inherited by this instance. Adds “keydown”, “keypress”, and “keyup” event listeners with this; adds “mouseup” event listener with this.release(). If any or all of the callback functions are not specified the instance will use the default keydown(), keypress(), and keyup() class methods, accordingly.

Instantiation/initialization can look like this:

  myObject.key = pergola.Key()
  .register({
    handle : object,
    callback: {
      keydown : function,
      keypress : function,
      keyup : function,
    },
    cursor : boolean,
    warn : boolean,
    stop : boolean,
    destroy : "key"
  });

See the instance properties defined in object:

release()

This method is invoked when the user clicks anywhere in the document. It may also be explicitly invoked from another scope, like this:

 if (Key.active) Key.active.release([params]);

Ends the current input process if stop was not programmatically set to false (on any particular action on the interface); removes the event listeners; if cursor was specified, removes the input cursor; if handle defines a endInput() method, or if its constructor's prototype defines a endInput() method, handle.endInput() is invoked with the optional arguments passed by the call from another scope (in this case, the presence of arguments signals to the endInput() function that input was ended by means other than those predefined for the Key instance, letting you take the appropriate actions).

mousedown(evt)

Handler for the "mousedown" event registered on document.documentElement at instantiation/registration. Invokes the release method.

handleEvent(evt)

Dispatches "keydown"/"keypress"/"keyup" event to respective callback.

instance

handle

Object. Required. Typically, but not necessarily, a reference to the object that instantiates the class. It may not reference the Key instance itself.

callback

Function or Object. If specified, it can be an object defining any or all the default handlers to override, or can be a function that will be the unique handler for the three event types. Note that if handle has instance or prototype methods named keydown, keypress and keyup (any, or all), you don't actually need to specify them in the callback object, as they will automatically override the default keydown(), keypress(), and keyup() class methods.

cursor

Boolean. If not specified, an instance of InputCursor is assigned to this handle by default. To override this behavior this property must be specified and set to false.

warn

Boolean. If specified pergola.Input instances will display out of range messages.

stop

Boolean. If specified (and set to false) it will prevent some actions in the interface from forcing end of input, where this behavior is not sought. In practice there's no need to specify this property during instantiation; instead, it is set statically in the event handlers of those objects (scrollbars for example) that should not interfere with the input, or can be set dynamically on certain conditions, and in those cases, after the interfering action has ended it must be set back to true, otherwise input will never end.

destroy

String. If specified, it gets the name of the property to which the Key instance was assigned. The object ceases to exist if there aren't any other references to it.