keyboard

This module provides global keyboard shortcut functionality for the Total Control environment.
It allows users to bind physical key combinations (e.g., Ctrl+Alt+V) to functions executed on specific Android devices.

Key Features:

• Register global keyboard shortcuts with custom handler functions.
• Conditional execution based on foreground app and bound device.
• Support for retrieving, triggering, logging, and unregistering shortcuts.
• Automatically manages key uniqueness using app and device identifiers.

Shortcut Format:

• Format: "Modifiers|Key" (e.g., "CA|V" means Ctrl+Alt+V)
  • Modifiers: C for Ctrl, A for Alt, S for Shift (case-insensitive)
  • Key: A-Z, 0-9, or F1–F12
  • |, ? are reserved characters and cannot be used in shortcuts

Basic Usage:

1. Create a shortcut that sends HOME key to the main device:

   var { Keyboard } = require("sigma/Keyboard");
   var key = new Keyboard("CA|V", function(device) {
       device.send(tcConst.KEY_HOME);
   });
   

2. Create a shortcut bound to a specific app and device with extra data:

   var key = new Keyboard("CA|U", function(device, data) {
       print(data.message);
   }, {
       app: "com.example.app",
       device: Device.getMain(),
       data: { message: "Hello!" }
   });
   

3. Retrieve or unregister a shortcut:

   var existing = Keyboard.searchObject("CA|V");
   existing.unregister();
   

This module attaches methods to Keyboard instances and exposes Keyboard, unregister() via module exports.

Functions

// Example: Register and retrieve a keyboard shortcut
var { Keyboard } = require("sigma/Keyboard");

// Define a function that handles both simple and object-style data.
function trytrytry(device, x) {
    if (x === 1) {
        print("data is 1");
    } else {
        print("x.device: " + x.device);
        print("x.field1: " + x.field1);
        print("x.field2: " + x.field2);
        x.device.send(tcConst.KEY_HOME);
    }
}

// Register a keyboard shortcut (Ctrl+Alt+V), which is always valid (no specific device or app).
var h = new Keyboard("CA|V", trytrytry, {
    app: null,
    device: null,
    data: 1
});

// Retrieve the same shortcut object using only the key.
var getkey1 = Keyboard.searchObject("CA|V");

if (getkey1 != null) {
    print(getkey1.log());
}

// Example: Unregister a global shortcut
var { Keyboard } = require("sigma/Keyboard");

// Define a function bound to Ctrl+Alt+V
function trytrytry(device, x) {
    if (x === 1) {
        print("data is 1");
    } else {
        print("x.device: " + x.device);
        print("x.field1: " + x.field1);
        print("x.field2: " + x.field2);
        x.device.send(tcConst.KEY_HOME);
    }
}

// Register the keyboard shortcut
var key1 = new Keyboard("CA|V", trytrytry, {
    app: null,
    device: null,
    data: 1
});

// Cancel the shortcuts that have been set
Keyboard.unregister("CA|V");