Home · All Classes · Annotated · Functions

Tutorial: Implementing a Device Plug-in

• Keypad
• Implementation Steps
• Touchscreen/Mouse
• Implementation Steps

This document describes the process required to implement a plug-in for a new device. All directory references are relative to the example provided in the <qtopia-root-dir>/devices/example directory.

Qtopia also provides Device Configuration Profiles to simplify the task of configuring Qtopia for a device and providing the plug-ins required.

The following directories are of particular interest:

This tutorial assumes that debugging using qLog() is enabled. To activate debugging:

• edit image/opt/Qtopia/etc/Trolltech/log.conf and enable Input
• restart Qtopia to implement the change and qLog() messages will be displayed.

This functionality is available in both debug and release builds.

The steps taken to implement a new plug-in depend on whether you are implementing a keypad plug-in or a touchscreen/mouse plug-in. The following tutorial provides the steps for both.

The initial steps for either type of plug-in are:

1. Copy the directory named example to <device-name>.
2. Rename all sub-directories called example to <device-name>.
3. Replace all occurrences of Example with <device-name>.
4. Replace all occurrences of example with <device-name>.
5. Replace all occurrences of EXAMPLE with <DEVICE-NAME>.

Note:The value chosen for <device-name> must only contain alpha-numeric characters.

Keypad

The functionality required to implement a keypad device plug-in is found in the source file: /src/<device-name>kbdhandler.cpp, which implements a class to handle keypad input inheriting QWSKeyboardhandler. Then the constructor/destructor readKbdData() functions are overloaded to match your device.

Implementation Steps

1. Set environment variable: QWS_KEYBOARD=examplekbdhandler
2. Implement qLog() to output the data being read to standard output.
3. Edit the keyboard plug-in code to suit your device as follows:
   • Identify the device node and update <device-name>kbdhandler.cpp to open the correct data node.
   • Identify the data format(for example, 4-byte packets) and update <device-name>kbdhandler.cpp to read the correct number of bytes.
   • Update the structure <device-name>Input in <device-name>kbdhandler.cpp with the correct data format for the device.
4. Build Qtopia using: ./configure -device <device-name>.
5. Run Qtopia.
6. To determine the correct key mappings, use the keypad to input strokes and then identify the byte-values displayed by qLog().
7. In <device-name>kbdhandler.cpp update the switch statement in function readKbdData() with the correct key mappings.

Touchscreen/Mouse

The functionality required to implement a touchscreen/mouse device plug-in is found in the source file: /src/<device-name>mousehandler.cpp which implements a class to handle mouse input inheriting QWSCalibratedMousehandler. Then the constructor/destructor readMouseData() and calibrate() functions are overloaded to match your device.

Implementation Steps

1. Set environment variable: QWS_MOUSE_PROTO=<examplemousehandler>
2. Implement qLog() to output the data being read to standard output.
3. Edit the mouse plug-in code to suit your device as follows:
   • Identify the device node and update <device-name>mousehandler.cpp to open the correct data node.
   • Identify the data format(for example, 4-byte packets) and update <device-name>mousehandler.cpp to read the correct number of bytes.
4. Build Qtopia using: ./configure -device <device-name>.
5. Run Qtopia.
6. To determine the correct Y-coord, Y-coord and pressure (press or release) move the mouse, click the mouse buttons and then identify the values displayed by qLog().
7. Update the structure ts_packet in <device-name>mousehandler.cpp with the correct data format for the device.
8. Update the switch statement in function readMouseData() in <device-name>mousehandler.cpp with the correct X-coord, Y-coord, and pressure value from the qLog() output.

Note: When creating a plug-in it is not necessary to rebuild all of Qtopia to enable it. Simply rebuild the plug-in and copy the files to the image/opt/Qtopia directory and restart Qtopia.