📄 devices.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><!-- /home/edba/dist/qtopia/main-Sunday/qtopia/doc/devices.doc:1 --><html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Qtopia - Customizing Qtopia for a Device</title><style type="text/css"><!--h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }a:link { color: #004faf; text-decoration: none }a:visited { color: #672967; text-decoration: none }body { background: #ffffff; color: black; }--></style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td width="200" align="left" valign="top"><a href="index.html"><img height="27" width="472" src="dochead.png" border="0"></a><br><font face="Arial,Helvetica,Geneva,Swiss,SunSans-Regular" align="center" size=32>Qtopia</font> <a href="index.html">Home</a> - <a href="qtopiaclasses.html">Classes</a> - <a href="qtopiaannotated.html">Annotated</a> - <a href="qtopiafunctions.html">Functions</a> - <a href="qtindex.html">Qt Embedded</a></td><td align="right" valign="top"> <table border="0" cellpadding="0" cellspacing="0" width="137"> <tr> <td><a href="http://www.trolltech.com/company/about/trolls.html"><img height="100" width="100" src="face.png" border="0"></a></td> <td><img height="100" width="100" src="qtlogo.png" align="top" border="0"></td> </tr> </table></td></tr></table><h1 align=center>Qtopia - Customizing Qtopia for a Device</h1><p> <p> Contents<!-- toc --><ul><li><a href="#1"> Introduction</a><li><a href="#2"> Custom Qtopia Launcher User Interface</a><ul><li><a href="#2-1"> Launcher</a><li><a href="#2-2"> Other User Interface Components</a></ul><li><a href="#3"> Device Hardware Factors</a><ul><li><a href="#3-1"> Device-Specific Code</a></ul><li><a href="#4"> Default scan-codes for Qtopia keys</a><ul><li><a href="#4-1"> Overriding scancode mapping for Qtopia</a><li><a href="#4-2"> Overriding the keyboard handler Qtopia Keys</a><li><a href="#4-3"> Additional button mapping</a><li><a href="#4-4"> Key behavior in Qtopia</a><ul><li><a href="#4-4-1"> Keys that are always intercepted</a><li><a href="#4-4-2"> Keys that are sometimes intercepted</a></ul></ul><li><a href="#5"> Configuration of Hardware Buttons</a><ul><li><a href="#"></a><ul><li><a href="#5-1"> User Defineable Button Mappings</a></ul><li><a href="#5-2"> Phone Launcher Menu</a><li><a href="#5-3"> Phone Buttons</a><li><a href="#5-4"> Phone SoftKey Positioning</a></ul><li><a href="#6"> Non-installed Components</a><li><a href="#7"> Unsupported Components</a><li><a href="#8"> Required Plugins</a><li><a href="#9"> Power Management</a><li><a href="#10"> Removable Storage Cards</a></ul><!-- endtoc --><p> <h2> Introduction</h2><a name="1"></a><p> This document sets out the implementation requirements for specific devices and makes recommendations for the optimal installation of Qtopia on a handheld device. How you install Qtopia on a given device will be determined by the functionality of that device.<p> <h2> Custom Qtopia Launcher User Interface</h2><a name="2"></a><p> In some cases it is desireable to have a cusomized launcher interfacethat better suits the intended application of the target device. Qtopiasupports custom laucher user interfaces via the <a href="serverinterface.html">ServerInterface</a>. Thisinterface provides all of the infrastructure necessary to implement alauncher, while maintaining compatiblity with the Qtopia application anddocument models.<p> The launcher user interface is part of the Qtopia server($QPEDIR/src/server) which provides services such as syncingand filesystem management.<p> <h3> Launcher</h3><a name="2-1"></a><p> The first step when writing a user interface is to implement a classderived from ServerInterface. This interface provides the functionalitynecessary to show the available applications and documents availableon a Qtopia device.<p> The createGUI() and destroyGUI() functions must be implemented to createand show the laucnher and any other user interface components.<p> Most of the functions provided by the ServerInterface are to manage addingand removing applications and documents as necessary. The ServerInterfacedocumentation describes each one in detail.<p> The default Qtopia launcher is implemented by the Launcher class.<p> <h3> Other User Interface Components</h3><a name="2-2"></a><p> In addition to the launcher itself, it is ususally necessary to providesome system components, such as input methods and status display.<p> There are several classes in thedefault Qtopia user interface that may be reused in a custom interface.Most user interfaces will make use of some of these classes to ensure auseable system:<p> <ul><li> InputMethods - loads and displays input methods.<li> RunningAppBar - displays running application icons.<li> SysTray - loads and displays applets.<li> StartMenu - provides menus for launcher tabs and accessory plugins.</ul><p> An interface providing these components will support most of the defaultQtopia launcher functionality.<p> The Qtopia libraries also assume that QPE/Taskbar QCOP channel is availableand supports the following functions:<p> <ul><li> message(QString) - display a status message.<li> hideInputMethod() - hide any visible input method.<li> showInputMethod() - show the currently selected input method.<li> showInputMethod(QString) - show the specified input method.<li> reloadInputMethods() - release and reload the input method plugins.<li> reloadApplets() - release and reload the applets.</ul><p> The default Qtopia launcher uses the TaskBar class to encapsulate theabove functionality.<p> <h2> Device Hardware Factors</h2><a name="3"></a><p> When planning to customize and install Qtopia on a specific device, there are a number of factors that must be taken into consideration. The following is a list of typical factors:<p> <ul><li> If the device has a touch screen, Qtopia calibration must be enabled.<li> If the device runs off batteries, Qtopia may be required to call APM functions for power saving.See the Power Management section below for more details.<li> If the device has special hardware buttons, they may need to be mapped toapplications and have associated images displayed in the user interface.<li> If the device has a buzzer for alarms and other beeps, Qtopia will need to know how to use this hardwareand enable it for the associated events.<li> If the device has an LCD screen with a back or front light, Qtopia will need to know how to adjustits brightness.<li> If the device has any special LEDs to indicate status to the user, Qtopia will need to know how toset the LEDs.<li> If the device has or supports a camera, a Video4Linux kernel driverhas to be provided so that the Qtopia Camera application can use it.<li> If the device has or supports phone hardware, a serial device thatsupports <a href="gsm.html">GSM</a> AT-commands should be provided, so that Qtopia Phone can use it.<li> If the device supports sound, the sound volume should be locked to the maximum intended volume.</ul><p> Fortunately all of the changes required to add those device specific customizations are centralized in Qtopia and involve just a few files that are described below. This document should make it easy for OEMs and system integratorsto understand how to make Qtopia aware of any special hardware that a device might have.<p> <h3> Device-Specific Code</h3><a name="3-1"></a><p> During configure, the <tt>-platform</tt> option is used toselect which custom-<platform-spec>.h file will be used when compiling Qtopia.The following macros can be defined or undefined in a custom.h file tocustomize Qtopia for the specific hardware. The associated custom-<platform-spec>.cppfile will be compiled and linked to provide any custom functions that are required.<p> <ul><li> QPE_USE_MALLOC_FOR_NEW - #define this to have memory alloced using malloc() instead of the default C++ new implementation (this is faster in some cases).<li> QPE_NEED_CALIBRATION - #define this if there is a touch screen that requires calibration.<li> QPE_OWNAPM - #define this if the device has existing APM settings that must be disabled first by qtopia via ioctls to /dev/apm_bios.<li> QPE_HAVE_TOGGLELIGHT - #define this if the device has a hardware button for turning on and off an LCD backlight.<li> QPE_HAVE_MEMALERTER - #define this if the device needs Qtopia to alert the user of low memory conditions, a function called initMemalerter() must be implemented.<li> QPE_MEMALERTER_IMPL - #define this as a macro that implements any functions required to implement the MEMALERTER functionality (including initMemalerter()).<li> QPE_INITIAL_NUMLOCK_STATE - #define this as a macro that implements any device specific methods used to initialize the numlock state.<li> QPE_ARCHITECTURE - #define this with a string that contains the manufacturer and model that uniquely identifies the device, for example "SHARP/SL5500".<li> QPE_DEFAULT_TODAY_MODE - #define this as "Daily" or "Never" (including the quotes) to tell Qtopia if by default it should run the today program daily or never.<li> QPE_FONT_HEIGHT_TO_ICONSIZE(x) - #define this as a macro to provide a mapping from a font height to an icon size in pixels.<li> CUSTOM_SOUND_INIT - #define this to call a function to initialize any custom sound devices like buzzers.<li> CUSTOM_SOUND_IMPL - #define this as a macro to define any custom functions required to be used by the other CUSTOM_SOUND macros.<li> CUSTOM_SOUND_ALARM - #define this as a macro which implements the device specific code to sound an alarm (perhaps using a buzzer).<li> CUSTOM_LEDS( led, status ) - #define this as a macro which can set an LED to a given status if applicable. The first argument specifies which LED, and the status is an integer with device specific meaning.<li> CUSTOM_SOUND_TOUCH( press ) - #define this as a macro which implements a given sound to be associated with taps to the screen if applicable.<li> CUSTOM_SOUND_KEYCLICK( k, p, r ) - #define this as a macro which implements a given sound to be associated with keyboard key presses if applicable.</ul><p> In addition to the above macros and defines, the following three functions must be implemented in the custom-<platform-spec>.cpp file.<p> <ul><li> int qpe_sysBrightnessSteps(); - This function is called by qtopia to query the number of graduations the device's LCD backlight/frontlight has.<li> void qpe_setBrightness(int); - This function must be implemented with any device specifc code used to set the backlight/frontlight brightness to the specified level.<li> void PowerStatusManager::getStatus(); - This function must be implemented to query the power status. The PowerStatus class in qtopia/power.h defines the power status abstraction. See the custom-linux-generic-g++.cpp file for details of a default implementation.</ul><p> For reference implementations of the device specific code, the existing <tt>custom-*.*</tt> files found in src/libraries/qtopia/ may be of guidance.<p> <h2> Default scan-codes for Qtopia keys</h2><a name="4"></a><p> Nearly all PDA's and Phones have keys that are not found on a regular keyboard. In order for Qtopia to function correctly when installed on a device, it needs these keys to be defined. The easiest way to do this is to have the keyboard driver for the device emit the scancodes for the existing mapping for Qtopia.<p> In addition to the normal mapping for a US-101 keyboard, the following table sets out the codes that are required / available / optional:<p> <table><tr><th>scancode</th><th>Qt key code</th><th>description</th> <th>keypad mode</th><th>no keypad mode</th></tr><tr><td>65</td> <td>Key_Menu</td> <td>Application menu key</td> <td>Optional</td><td>Not Available</td></tr><tr><td>67</td> <td>Key_Back</td> <td>Accept/Close dialog key</td> <td>Required</td><td>Not Available</td></tr><tr><td>68</td> <td>Key_Yes</td> <td>... not sure ...</td> <td>Optional</td><td>Not Available</td></tr><tr><td>69</td> <td>Key_No</td> <td>... not sure ...</td> <td>Optional</td><td>Not Available</td></tr><tr><td>87</td> <td>Key_Call</td> <td>Start call, accept incoming call</td><td>Optional</td><td>Not Available</td></tr><tr><td>88</td> <td>Key_Hangup</td> <td>End call, reject incoming call</td> <td>Optional</td><td>Not Available</td></tr><tr><td>116</td> <td>Key_Select</td> <td>Select menu option, checkbox, pressbutton</td><td>Required</td><td>Not Available</td></tr><tr><td>120</td> <td>F31</td> <td>Toggle input method</td> <td>Optional</td><td>Optional</td></tr><tr><td>121</td> <td>F32</td> <td>Sync device</td> <td>Optional</td><td>Optional</td></tr><tr><td>122</td> <td>F34</td> <td>Power/Sleep</td> <td>Optional?</td><td>Required</td></tr><tr><td>123</td> <td>F35</td> <td>Toggle backlight</td> <td>Optional</td><td>Optional</td></tr><tr><td>124</td> <td>Context1</td> <td>First Context button</td> <td>Optional</td><td>Not Available</td></tr><tr><td>125</td> <td>Context2</td> <td>Second Context button</td> <td>Optional</td><td>Not Available</td></tr><tr><td>126</td> <td>Context3</td> <td>Third Context button</td> <td>Optional</td><td>Not Available</td></tr><tr><td>127</td> <td>Context4</td> <td>Forth Context button</td> <td>Optional</td><td>Not Available</td></tr></table><p> There are two additional keys that do not have default mappings, and should not be used. They are listed below only for reasons of compatibility.<p> <table><tr><th>Qt key code</th><th>description</th> <th>keypad mode</th><th>no keypad mode</th></tr><tr><td>Key_F30</td> <td>maps to space on widgets that need select</td><td>Not Applicable</td><td>Optional</td></tr><tr><td>Key_F33</td> <td>maps to enter on widgets that need ok</td><td>Not Applicable</td><td>Optional</td></tr></table><p> Qtopia is designed to be flexible in terms of the keys required. The default environment for Qtopia has the following keys:<p> <ul><li>Key_Select</li><li>Key_Context1</li><li>Key_Back</li><li>Key_Call</li><li>Key_Hangup</li><li>Key_Up</li><li>Key_Down</li><li>Key_Left</li><li>Key_Right</li></ul><p> Please note that there is no Key_Menu. Where there is no Key_Menu, but there is a Key_Context1, the Key_Context1 can be used as Key_Menu. If the device has a alternate button mapping Trolltech will provide assistance in getting Qtopia to work with alternate button mapping.<p> <h3> Overriding scancode mapping for Qtopia</h3><a name="4-1"></a><p> If for any reason it is not possible to map the device buttons' emit to the default scan codes for the Qtopia keys, then the mapping can be overridden in <tt>custom-linux-<device>-g++.*</tt>.In <tt>custom-linux-<device>-g++.h</tt> add:<p> #define QPE_OVERRIDE_KEYMAPstruct KeyOverride;extern const KeyOverride* qtopia_override_keys();<p> And in <tt>custom-linux-<device>-g++.cpp</tt> add:<p> typedef struct KeyOverride {ushort scan_code;QWSServer::KeyMap map;};<p> static const KeyOverride deviceKeys[] = {{ 0x79, { Qt::Key_F34, 0xffff, 0xffff, 0xffff } }, // power#if defined(QT_KEYPAD_MODE){ 0x7a, { Qt::Key_Call, 0xffff, 0xffff, 0xffff } },{ 0x7b, { Qt::Key_Context1, 0xffff, 0xffff, 0xffff } },{ 0x7c, { Qt::Key_Back, 0xffff, 0xffff, 0xffff } },{ 0x7d, { Qt::Key_Hangup, 0xffff, 0xffff, 0xffff } },#else{ 0x7a, { Qt::Key_F9, 0xffff, 0xffff, 0xffff } },{ 0x7b, { Qt::Key_F10, 0xffff, 0xffff, 0xffff } },{ 0x7c, { Qt::Key_F11, 0xffff, 0xffff, 0xffff } },{ 0x7d, { Qt::Key_F12, 0xffff, 0xffff, 0xffff } },#endif{ 0, { 0, 0xffff, 0xffff, 0xffff } }};<p> const KeyOverride* qtopia_override_keys(){return deviceKeys;}<p> Where deviceKeys is the mapping of scan code to the structure composing of:<p> <ul><li>The Qt Key for the scan code</li><li>The unicode character for the scan code</li><li>The unicode character for the scan code if shift is active</li><li>The unicode character for the scan code if control is active</li></ul><p> The example above is for the iPAQ h3xxx models.<p> <h3> Overriding the keyboard handler Qtopia Keys</h3><a name="4-2"></a><p> If your device does not have a keyboard driver, then it is possible to implement a special keyboard handler for the device. This is done by<p> <strong> I Have no idea how to do this, ask Martin?</strong><p> <h3> Additional button mapping</h3><a name="4-3"></a><p> Device specific mappings can also be specified in the file$QPEDIR/etc/defaultbuttons.conf.<p> // doc on default buttons? naming which system buttons are avail?<p> Buttons specified in defaultbuttons.conf will be intercepted unless an application currentlyhas a keyboard grab.See $QPEDIR/doc/devices.html for more information.<p> <h3> Key behavior in Qtopia</h3><a name="4-4"></a><p> <h4> Keys that are always intercepted⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -