Input Device: Managing Input Keys in the Application

This tutorial demonstrates how you can manage input device keys and perform custom actions when they are pressed.

The Input Device API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

Warm-up

Become familiar with the Input Device API basics by learning about:

• Getting a List of All Supported Keys

  Get a list of all supported keys and perform actions for the list.

• Gathering Key Information

  Gather the key code based on the key name.

• Registering and Unregistering Keys

  Register keys to handle DOM events for them.

Getting a List of All Supported Keys

To manage input device keys, you must learn to gather a list of all supported keys:

1. To get a supported key list, use the getSupportedKeys() method of the InputDeviceManager interface (in mobile and wearable applications):

   var keyCodes = {};
   var supportedKeys = tizen.inputdevice.getSupportedKeys();
   
   console.log("Supported keys list");
   for (var i = 0; i < supportedKeys.length; ++i) 
   {
      keyCodes[supportedKeys[i].name] = supportedKeys[i].code;
      console.log(i + " : " + supportedKeys[i].name + " - " + supportedKeys[i].code);
   }
   

2. Use the gathered list to handle keydown and keyup events.

Gathering Key Information

To manage input device keys, you must learn to gather key information.

1. Create a list of keys for which you want the information.

   If you do not want to gather information about all supported keys, create a separate list of keys for information gathering. If you want information about all supported keys, use the list retrieved in the previous use case.

   var keys = ["VolumeUp", "VolumeDown"];
   var keyCodes = {};
   

2. Check each key separately using the getKey() method of the InputDeviceManager interface (in mobile and wearable applications).

   If the result of the getKey() method is not null, you can access the key information. If the result is null, the key is not supported.

   for (var i = 0; i < keys.length; i++) 
   {
      try 
      {
         var key = tizen.inputdevice.getKey(keys[i]);
         if (key == null) 
         {
            console.log("key: " + keys[i] + " is not supported");
         } 
         else 
         {
            keyCodes[key.name] = key.code;
            console.log("key: " + key.name + " has code: " + key.code);
         }
      } 
      catch(e) 
      {
         console.log("error: " + e.name + ":" + e.message + ", when getting key with name " + keys[i]);
      }
   }
   

Registering and Unregistering Keys

To manage input device keys, you must learn to change the action of a supported key:

1. To gather the keys, get a list of all supported keys.

2. To register all supported keys for handling keydown and keyup events:

   var codeNamesMap = {};
   var supportedKeys = tizen.inputdevice.getSupportedKeys();
   
   for (var i = 0; i < supportedKeys.length; ++i) 
   {
      try 
      {
         tizen.inputdevice.registerKey(supportedKeys[i].name);
         codeNamesMap[supportedKeys[i].code] = supportedKeys[i].name;
         console.log("key: " + supportedKeys[i].name + " was registered for event handling");
      } 
      catch(error) 
      {
         console.log("failed to register " + supportedKeys[i].name + ": " + error);
      }
   }
   

   If you know the exact list of keys you want to register, the registration can also be done with the asynchronous registerKeyBatch() method:

   var keys = ["VolumeUp", "VolumeDown"];
   
   function errorCB(err) 
   {
      console.log('The following error occurred: ' +  err.name);
   }
   
   function successCB() 
   {
      console.log('All keys registered successfully');
   }
   
   tizen.inputdevice.registerKeyBatch(keys, successCB, errorCB);
   

3. To handle events for registered keys:

   window.addEventListener("keydown", function(keyEvent) 
   {
      if (codeNamesMap.hasOwnProperty(keyEvent.keyCode)) 
      {
         console.log("Registered key was pressed");
         /* Define some custom action */
      } 
      else 
      {
         console.log("Some other key was pressed");
      }
   });
   
   window.addEventListener("keyup", function(keyEvent) 
   {
      if (codeNamesMap.hasOwnProperty(keyEvent.keyCode)) 
      {
         console.log("Registered key was released");
         /* Define some custom action */
      } 
      else 
      {
         console.log("Some other key was released");
      }
   });
   

4. When custom actions are no longer needed, unregister the keys:

   for (var i = 0; i < supportedKeys.length; ++i) 
   {
      tizen.inputdevice.unregisterKey(supportedKeys[i].name);
      console.log("key: " + supportedKeys[i].name + " was unregistered for event handling");
   }
   

   The unregistration can also be done with the unregisterKeyBatch() method:

   var keys = ["VolumeUp", "VolumeDown"];
   
   function errorCB(err) 
   {
      console.log('The following error occurred: ' +  err.name);
   }
   
   function successCB() 
   {
      console.log('Unregistered successfully');
   }
   
   tizen.inputdevice.unregisterKeyBatch(keys, successCB, errorCB);
   

   After unregistration, the keydown and keyup events are no longer triggered for the keys.