InputDevice API

The Input Device API provides functions to subscribe key events of the input device.

The Tizen Device may provide depending on a particular input device. An application can handle device dependent key events after registration.

For more information on the Input Device features, see Input Device Guide.

Since: 2.4

Table of Contents


Summary of Interfaces and Methods

Interface Method
InputDeviceManagerObject
InputDeviceKey
InputDeviceManager
void registerKeyBatch (InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void unregisterKeyBatch (InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)

1. Type Definitions

1.1. InputDeviceKeyName

Name which identifies the key
  typedef DOMString InputDeviceKeyName;

Since: 2.4

Name of the key may be, for example:

  • VolumeUp
  • VolumeDown

The actual list of supported keys depends on the platform.

2. Interfaces

2.1. InputDeviceManagerObject

The InputDeviceManager interface defines what is instantiated in the tizen object.
  [NoInterfaceObject] interface InputDeviceManagerObject {
    readonly attribute InputDeviceManager inputdevice;
  };
  Tizen implements InputDeviceManagerObject;

Since: 2.4

There is a tizen.inputdevice object that allows accessing the functionality of the Input Device API.

Attributes

  • readonly InputDeviceManager inputdevice
    Object representing a input device manager.

    Since: 2.4

2.2. InputDeviceKey

The InputDeviceKey interface stores information about the key.
  [NoInterfaceObject] interface InputDeviceKey {
    readonly attribute InputDeviceKeyName name;
    readonly attribute long code;
  };

Since: 2.4

Attributes

  • readonly InputDeviceKeyName name
    The name of the key, for example "VolumeUp" or "VolumeDown".

    If the key is listed in the DOM Level 3 KeyboardEvent key Values specification, the name attribute is equal to the key value specified there. (The Media Controller Keys section is the most relevant to the Input Device API)

    If the "DOM Level 3 KeyboardEvent key Value" does not contain appropriate entry for the key, then the Input Device provides a device specific name.

    Since: 2.4

  • readonly long code
    The numeric code of the key, like 37 or 13.

    This is the keyCode attribute value of the Key Event generated by the key.

    Since: 2.4

2.3. InputDeviceManager

The InputDeviceManager interface provides the features to check for availability and register for input device events.
  [NoInterfaceObject] interface InputDeviceManager {
    InputDeviceKey[] getSupportedKeys() raises(WebAPIException);
    InputDeviceKey? getKey(InputDeviceKeyName keyName) raises(WebAPIException);
    void registerKey(InputDeviceKeyName keyName) raises(WebAPIException);
    void unregisterKey(InputDeviceKeyName keyName) raises(WebAPIException);
    void registerKeyBatch(InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback,
                          optional ErrorCallback? errorCallback) raises(WebAPIException);
    void unregisterKeyBatch(InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

Since: 2.4

Methods

getSupportedKeys
Retrieves the list of keys can be registered with the registerKey() method.
InputDeviceKey[] getSupportedKeys();

Since: 2.4

Mandatory keys will not be retrieved by this method.

Return value:

    InputDeviceKey[]: List of supported keys.

Exceptions:

  • WebAPIException
    • with error type UnknownError in case of any error.

Code example:

var i, keyCode = {}, supportedKeys;
supportedKeys = tizen.inputdevice.getSupportedKeys();
for (i = 0; i < supportedKeys.length; i++)
{
  keyCode[supportedKeys[i].name] = supportedKeys[i].code;
}
if (keyCode.hasOwnProperty("VolumeUp"))
{
  tizen.inputdevice.registerKey("VolumeUp");
}
window.addEventListener("keydown", function(keyEvent)
{
  /* Identify the key by the numeric code from the keyEvent. */
  if (keyEvent.keyCode === keyCode.VolumeUp)
  {
    console.log("The VOLUME UP was pressed");
  }
});
getKey
Returns information about the key which has the given name.

Since: 2.4

Parameters:

  • keyName: The name of the key to retrieve.

Return value:

    InputDeviceKey [nullable]: InputDeviceKey object for the given key name or null if the key is not supported.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError if the given keyName is invalid (e.g. name is empty string)

    • with error type UnknownError in any other error case.

registerKey
Registers an input device key to receive DOM keyboard event when it is pressed or released
void registerKey(InputDeviceKeyName keyName);

Since: 2.4

When an application wants to react to the Input Device keys being pressed, it should register this key.

An application can not register the mandatory keys (ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Enter, Back).

Parameters:

  • keyName: The name of the key which should generate DOM key events when pressed.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the given keyName is invalid or not supported (e.g. name is empty string).

    • with error type UnknownError in any other error case.

Code example:

var keys = ["VolumeUp", "VolumeDown"], i;
for (i = 0; i < keys.length; i++)
{
  try
  {
    tizen.inputdevice.registerKey(keys[i]);
  }
  catch (error)
  {
    console.log("Failed to register " + keys[i] + ": " + error);
  }
}
unregisterKey
Unregisters an input device key
void unregisterKey(InputDeviceKeyName keyName);

Since: 2.4

Parameters:

  • keyName: The name of the key which should not be monitored any longer.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if the given keyName is invalid or not supported (e.g. name is empty string).

    • with error type UnknownError in any error case.

Code example:

tizen.inputdevice.unregisterKey("VolumeDown");
registerKeyBatch
Registers a batch of input device keys to receive DOM keyboard event when any of them is pressed or released
void registerKeyBatch(InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback,
                      optional ErrorCallback? errorCallback);

Since: 2.4

The errorCallback is launched with this error type:

  • InvalidValuesError: If any of the given keyNames is invalid or not supported
  • UnknownError: In case of any other error

When an application wants to react to the input device keys being pressed, it should register those keys.

An application can not register the mandatory keys (ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Enter, Back).

Parameters:

  • keyNames: The array with key names of keys which should generate DOM key events when pressed.
  • successCallback [optional] [nullable]: Callback method to be invoked when keys are registered.
  • errorCallback [optional] [nullable]: Callback method to be invoked when an error has occurred.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the given keyNames is invalid or not supported (e.g. name is empty string).

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError in any other error case.

Code example:

function errorCB(err)
{
  console.log("The following error occurred: " + err.name);
}

function successCB()
{
  console.log("Registered successfully");
}

var keys = ["VolumeUp", "VolumeDown"];
tizen.inputdevice.registerKeyBatch(keys, successCB, errorCB);
unregisterKeyBatch
Unregisters a batch of input device keys
void unregisterKeyBatch(InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback,
                        optional ErrorCallback? errorCallback);

Since: 2.4

The errorCallback is launched with this error type:

  • InvalidValuesError: If any of the given keyNames is invalid or not supported
  • UnknownError: In case of any other error

Parameters:

  • keyNames: The array containing names of keys which should not be monitored any longer.
  • successCallback [optional] [nullable]: Callback method to be invoked when keys are unregistered.
  • errorCallback [optional] [nullable]: Callback method to be invoked when an error has occurred.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the given keyNames is invalid or not supported (e.g. name is empty string).

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError in any error case.

Code example:

function errorCB(err)
{
  console.log("The following error occurred: " + err.name);
}

function successCB()
{
  console.log("Unregistered successfully");
}

var keys = ["VolumeUp", "VolumeDown"];
tizen.inputdevice.unregisterKeyBatch(keys, successCB, errorCB);

3. Full WebIDL

module InputDevice {
  typedef DOMString InputDeviceKeyName;
  Tizen implements InputDeviceManagerObject;
  [NoInterfaceObject] interface InputDeviceManagerObject {
    readonly attribute InputDeviceManager inputdevice;
  };
  [NoInterfaceObject] interface InputDeviceKey {
    readonly attribute InputDeviceKeyName name;
    readonly attribute long code;
  };
  [NoInterfaceObject] interface InputDeviceManager {
    InputDeviceKey[] getSupportedKeys() raises(WebAPIException);
    InputDeviceKey? getKey(InputDeviceKeyName keyName) raises(WebAPIException);
    void registerKey(InputDeviceKeyName keyName) raises(WebAPIException);
    void unregisterKey(InputDeviceKeyName keyName) raises(WebAPIException);
    void registerKeyBatch(InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback,
                          optional ErrorCallback? errorCallback) raises(WebAPIException);
    void unregisterKeyBatch(InputDeviceKeyName[] keyNames, optional SuccessCallback? successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };
};