diff options
Diffstat (limited to 'doc/qws.doc')
| -rw-r--r-- | doc/qws.doc | 670 |
1 files changed, 670 insertions, 0 deletions
diff --git a/doc/qws.doc b/doc/qws.doc new file mode 100644 index 0000000..746baa9 --- /dev/null +++ b/doc/qws.doc @@ -0,0 +1,670 @@ +/**************************************************************************** +** +** Qt/Embedded (Qt on QWS) documentation +** +** Copyright (C) 2000-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing requirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + +/*! +\page emb-install.html + +\title Installing Qt/Embedded + +This installation procedure is written for Linux. It may need +to be modified for other platforms. + +\list 1 +\i Unpack the archive if you have not done so already + +\code + cd <anywhere> + gunzip qt-embedded-commercial-VERSION.tar.gz # uncompress the archive + tar xf qt-embedded-commercial-VERSION.tar # unpack it +\endcode +Replace \c VERSION with the Qt/Embedded version number throughout. + +This document assumes that the archive is installed as \c{~/qt-embedded-commercial-VERSION}. +\i Compile the Qt/Embedded library and examples. + +\code + cd ~/qt-embedded-commercial-VERSION + export QTDIR=~/qt-embedded-commercial-VERSION + ./configure + make +\endcode + +The configuration system is designed to allow platform-specific options +to be added, but in general all Linux systems which have framebuffer +support can use the "linux-generic-g++" platform. +The configuration system also supports cross-compilers: +to build on Linux/x86 for the Linux/MIPSEL target, you would use: +\code + ./configure -embedded mips +\endcode + +Only a small number of configurations are predefined. +You can create your own custom configuration by adding new files + to the \c mkspecs/qws/ directory. Use existing similar configurations + as a starting point. + +<b>Note</b>: Due to a bug in the configure script, cross-compiling on +a little-endian machine (e.g. x86) for a big-endian processor +(e.g. PowerPC) will use the host's endianness instead of the +target's. Workaround: after running configure, and before running +make, edit \c $QTDIR/include/qconfig.h and change the definition of +\c Q_BYTE_ORDER. + +\i Enable framebuffer support. + + You may need to recompile your kernel to enable the framebuffer. + This document does not describe how to do this; the + \link emb-framebuffer-howto.html Framebuffer HOWTO page \endlink + contains a short description. (You should see + a penguin logo at boot time when the frame buffer is enabled.) + + For Matrox G100/G200/G400 use the matrox frame buffer driver. + + For NVidia TNT cards use the nvidia frame buffer driver. + + For Mach64 and most other cards, use the vesafb driver. + + Note that some cards are only supported in VGA16 mode, this will + not work with the current version of Qt/Embedded, since VGA/16 is + not yet supported. You may need to upgrade your kernel, or even + switch to an experimental kernel. + + The frame buffer must also be enabled with a boot parameter. See + \c /usr/src/linux/Documentation/fb for details. + + The \c fbset program, which should be included in Linux distributions, + may be used to switch video modes without rebooting the system. The + video mode active when the server is started will be used. (8-bit + modes are still experimental.) <b>Note</b>: \c fbset does not work + with the vesafb driver. + +\i Change permissions. + + To run Qt/Embedded, you need write access to the framebuffer device + \c /dev/fb0. + + You also need read access to the mouse device. (Note that + \c /dev/mouse is normally a symbolic link; the actual mouse device + must be readable.) + +\i How to run the demonstration program. + + Log into a virtual console and do this: + +\code + cd ~/qt-embedded-commercial-VERSION/examples/launcher + ./start-demo +\endcode + + +\i Miscellaneous troubleshooting and known bugs. + + To kill gpm, run the following command as root: + +\code + gpm -k +\endcode + + In some cases, if the server does not work, it will work when run as root. + + Show processes using the framebuffer: + +\code + fuser -v /dev/fb0 +\endcode + + Kill such processes: +\code + fuser -vk /dev/fb0 +\endcode + or harsher: +\code + fuser -k -KILL /dev/fb0 +\endcode + + Show existing semaphores: +\code + ipcs +\endcode + + Remove semaphores: +\code + ipcrm +\endcode + + The communication between client and server is done through the + named pipe \c /tmp/qtembedded-username/QtEmbedded-0; sometimes it may need to be deleted + (e.g. if you run Qt/Embedded with root privileges then later as an unprivileged user). + +\i Customization. + + The Qt/Embedded library can be reduced in size by + \link emb-features.html removing unnecessary features \endlink. + +\i This document shows how to use Qt/Embedded with the Linux framebuffer. For +development and debugging purposes it is often easier to use the \link +emb-qvfb.html Qt/Embedded virtual framebuffer\endlink instead. + + +\endlist + +*/ + +/*! \page emb-fonts.html + +\title Fonts in Qt/Embedded + +\section1 Supported Formats + +Qt/Embedded supports four font formats: + +\table +\row +\i <b>TrueType (TTF)</b> +\i The scalable font technology now standard on MS-Windows and Apple +Macintosh, and becoming popular on X11. +\row +\i <b>Postscript Type1 (PFA/PFB)</b> +\i Scalable fonts often used by printers, also popular on X11. These +are similar in functionality to TTF fonts and are not discussed +further in this document. +\row +\i <b>Bitmap Distribution Format<br>fonts (BDF)</b> +\i A standard format for non-scalable fonts. A large number of BDF +fonts are supplied as part of standard X11 distributions - most of +these can be used with Qt/Embedded. You should \e not use these in a +production system: they are very slow to load and take up a \e lot of +storage space. Instead, render the BDF to a QPF. +\row +\i <b>Qt Prerendered Font (QPF)</b> +\i A light-weight non-scalable font format specific to Qt/Embedded. +\endtable + +Support for each of these font formats (except QPF which is always +enabled) can be enabled or disabled independently by using the \link +emb-features.html Qt/Embedded Features Definition\endlink. There is +support in Qt/Embedded for writing a QPF font file from any font, so +you can initially enable TTF and BDF formats, save QPF files for the +fonts and sizes you need, then remove TTF and BDF support. + +See \link makeqpf.html tools/makeqpf\endlink for a tool that helps +produce QPF files from the TTF and BDF, or just run your application +with the \c -savefonts option. + +\section1 Memory Requirements + +With TTF fonts, each character in the font at a given point size is +only rendered when first used in a drawing or metrics operation. With +BDF fonts all characters are rendered when the font is used. +With QPF fonts, the characters are stored in the same format that Qt +uses for drawing. + +For example, a 10-point Times font containing the ASCII characters uses +around 1300 bytes when stored in QPF format. + +Taking advantage of the way the QPF format is structured, Qt/Embedded +memory-maps the data rather than reading and parsing it. +This reduces RAM consumption even further. + +Scalable fonts use a larger amount of memory per font, but +these fonts provide a memory saving if many different sizes of each +font are needed. + +\section1 Smooth Fonts + +TTF, PFA, and QPF fonts can be rendered as \e{smooth} anti-aliased +fonts to give superior readability, especially on low-resolution +devices. The difference between smooth and non-smooth fonts is +illustrated below (you may need to change your display to low +resolution to see the difference): + +\img unsmooth.png unsmooth + +\img smooth.png smooth + +\section1 Unicode + +All fonts used by Qt/Embedded use the Unicode character encoding. +Most fonts available today use this encoding, but they usually don't +contain all the Unicode characters. A \e complete 16-point Unicode +font uses over 1 MB of memory. + +\section1 The font definition file + +When Qt/Embedded applications run, they look for a file called +\c $QTDIR/lib/fonts/fontdir or +\c /usr/local/qt-embedded/lib/fonts/fontdir. This file defines the +fonts available to the application. It has the following format: +\quote + \e name \e file \e renderer \e italic \e weight \e size \e flags +\endquote +where + +\table +\header \i Field \i Value +\row \i \e name \i \c Helvetica, \c Times, etc. +\row \i \e file \i \c helvR0810.bdf, \c verdana.ttf, etc. +\row \i \e renderer \i \c BDF or \c FT +\row \i \e italic \i \c y or \c n +\row \i \e weight \i \c 50 is normal, \c 75 is bold, etc. +\row \i \e size \i \c 0 for scalable or point size * 10 (i.e. \c 120 + for 12pt) +\row \i \e flags \i \list + \i \c s: smooth (anti-aliased) + \i \c u: Unicode range when saving (default is Latin-1) + \i \c a: ASCII range when saving (default is Latin-1) + \endlist +\endtable + +The font definition file does not specify QPF fonts; these are loaded +directly from the directory containing the \c fontdir file, and must +be named \e {name}_\e {size}_\e {weight}\e {italicflag}.qpf, where + +\table +\header \i Field \i Value +\row \i \e name \i \c helvetica, \c times, etc. (in lowercase) +\row \i \e size \i point size * 10 (i.e. \c 120 for 12pt) +\row \i \e italicflag \i \c i for italic, otherwise nothing. +\row \i \e weight \i \c 50 is normal, \c 75 is bold, etc. +\endtable + +If an application is run with the \c -savefonts command-line option, +then whenever a font other than a QPF font is used, a corresponding QPF file +is saved. This allows you to easily find the font usage of your applications +and to generate QPF files so that you can eventually reduce the memory +usage of your applications by disabling TTF and BDF support from Qt/Embedded, +or by modifying the initialization of \c qws_savefonts in +\c kernel/qapplication_qws.cpp of the Qt/Embedded library source code. +In extreme cases of memory-saving, it is possible to save partially-rendered +fonts (i.e. only the characters in "Product Name<sup>TM</sup>") if you are +certain that these are the only characters you will need from the font. +See QMemoryManager::savePrerenderedFont() for this functionality. + +\section1 Notes + +The font definition file, naming conventions for font files, and the format +of QPF files may change in versions of Qt/Embedded after 3. +<p> +To generate QPF files of different rotations, the program must be re-run with +an orientation that matches the desired rotation of the QPF output. An example to +generate all 4 rotations of fonts would be to run the following at a real framebuffer: +<pre> +for dpy in LinuxFb Transformed:Rot90 Transformed:Rot180 Transformed:Rot270 +do + QWS_DISPLAY=$dpy ./makeqpf "$@" +done +</pre> +If programs are only ever run in one orientation on a device, only the one +appropriate set of fonts is needed. +<p> +When enabled, Qt/Embedded uses the powerful FreeType2 library to implement +TrueType and Type1 support. + +*/ + +/*! \page emb-running.html + +\title Running Qt/Embedded applications + +A Qt/Embedded application requires a master application to be running +or to be a master application itself. The master application is +primarily responsible for managing top-level window regions, and +pointer and keyboard input. + +Any Qt/Embedded application can be a master application by +constructing the QApplication object with the +\e{QApplication::GuiServer} type, or by being run with the \e{-qws} +command line option. + +This document assumes you have the Linux framebuffer configured correctly +and no master process is running. If you do not have a working Linux +framebuffer you can use the +\link emb-qvfb.html Qt/Embedded virtual framebuffer\endlink, or you can +run Qt/Embedded as a \link emb-vnc.html VNC server\endlink. + +Change to a Linux console and select an example to run, e.g. \c +examples/widgets. Make sure $QTDIR is set to the directory where you +installed Qt/Embedded and add the $QTDIR/lib directory to +$LD_LIBRARY_PATH, e.g.: +\code +export QTDIR=$HOME/qt-VERSION +export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH +\endcode + +Run the application with the \e{-qws} option: + +\code +cd $QTDIR/examples/widgets +./widgets -qws +\endcode + +You should see the \c widgets example appear. If your mouse doesn't +work correctly you must specify the type of mouse to use. You can +exit the master application at any time using +<b>Ctrl+Alt+Backspace</b>. + +If you wish to run additional applications you should run them as clients +i.e. without the \e{-qws} option. + +\section1 Displays + +Qt/Embedded allows multiple displays to be used simultaneously by running +multiple Qt/Embedded master processes. This is achieved using the -display +command line parameter or the $QWS_DISPLAY environment variable. + +The -display parameter's syntax is: +\code + [gfx driver][:driver specific options][:display number] +\endcode +For example, if you want to use the mach64 driver on fb1 as display 2: +\code + $ ./launcher -display Mach64:/dev/fb1:2 +\endcode + +To try this functionality you can do the following: +\list 1 +\i Change to VC 1 (virtual console one) and run the launcher: + +\code + $ cd examples/launcher + $ ./launcher +\endcode + +\i Switch to VC 2 and run another one: + +\code + $ cd examples/launcher + $ ./launcher -display :1 +\endcode + +Another launcher will be started. Start an application in this launcher. + +\i Press <b>Ctrl+Alt+F1</b> - back to display 0. You can also start +additional applications on a particular display by specifying the +display id. Change to VC 3: + +\code + $ cd examples/widgets + $ ./widgets -display :1 +\endcode + +will display the widgets example on dislpay :1 (VC 2). +\endlist + +Only the master process needs to specify the driver/device part +explicitly. The clients get the information they need from the master +when they connect. So once you have a master server running using a +particular driver, you can just use "client -display :n" to use +display n. + +\section1 Mouse Input + +Qt/Embedded attempts to autodetect a mouse by default. The supported +protocols are MouseMan, Microsoft, IntelliMouse and +some other devices specific to certain hardware (e.g. Vr touch panel). +To specify the mouse to use set the \c $QWS_MOUSE_PROTO environment +variable, e.g.: +\code +export QWS_MOUSE_PROTO=IntelliMouse +\endcode + +The mouse autodetection opens the serial devices and psaux which +may cause conflicts with other programs using those devices. If +this is the case then specify the mouse driver protocol and device +explicitly. + +\sa \link emb-pointer.html Qt/Embedded Pointer Handling \endlink + +*/ + +/*! \page emb-porting.html + +\title Porting your applications to Qt/Embedded + +Existing Qt applications should require no porting provided there is no +platform dependent code. Platform dependent code includes system calls, +calls to the underlying window system (Windows or X11), and Qt platform +specific methods such as QApplication::x11EventFilter(). + +For cases where it is necessary to use platform dependent code there are +macros defined that can be used to enable/disable code for each platform +using \c #ifdef directives: + +\table +\header \i Platform \i Macro +\row \i Qt/X11 \i Q_WS_X11 +\row \i Qt/Windows \i Q_WS_WIN +\row \i Qt/Embedded \i Q_WS_QWS +\endtable + +Qt/Embedded also requires the following flags to be defined when compiling +applications: +\code +-DQWS -fno-exceptions -fno-rtti +\endcode + +Exceptions and RTTI are disabled in Qt/Embedded because they incur a large +overhead in both size and speed. +*/ + + +/*! \page emb-pointer.html +\title Qt/Embedded Pointer Handling + +Pointer handling in Qt/Embedded works for any mouse or mouse-like +device such as touchpanels and trackballs. + +Usually only one pointer device is supported in an embedded device, +but for demonstration purposes, Qt/Embedded includes a large number of +supported devices. + +\section1 Mouse Protocols + +Mouse drivers can be enabled/disabled via the configure script. Running +./configure -help lists the available mouse drivers. Only the +"pc" mouse driver is enabled in the default configuration. + +Provided the "pc" mouse driver is enabled, Qt/Embedded auto-detects the +mouse type and device if it is one of +the supported types on \c /dev/psaux or one of the \c /dev/ttyS? +serial lines. If multiple mice are detected, all may be used simultaneously. + +Alternatively, you may set the environment variable \c QWS_MOUSE_PROTO +to determine which mouse to use. This environment variable may be set +to: +\quote + \e{\<protocol\>}\c{:}\e{\<device\>} +\endquote +where \e{\<protocol\>} is one of: +\list + \i MouseMan + \i IntelliMouse + \i Microsoft +\endlist +and \e{\<device\>} is the mouse device, often \c /dev/mouse. If no +such variable is specified, the built-in default is \c Auto, which +enables auto-detection of the mouse protocol and device. + +To add another protocol, new subclasses of QWSMouseHandler and +QMouseDriverPlugin can be written and installed as plugins. + +\section1 Touch Panels + +Qt/Embedded ships with support for the NEC Vr41XX touchpanel and the +emerging linux touchpanel standard used by the iPAQ and Zaurus. These +are subclasses of QWSCalibratedMouseHandler which is in turn a subclass +of QWSMouseHandler in \c embedded/qmouse_qws.cpp. +*/ + + +/*! \page emb-performance.html +\title Qt/Embedded Performance Tuning + +When building embedded applications on low-powered devices, a number +of options are available that would not be considered in a desktop +application environment. These options reduce the memory and/or CPU +requirements at the cost of other factors. + +\list +\i \link emb-features.html <b>Tuning the functionality of Qt\endlink +\i \link #general General programming style\endlink +\i \link #static Static vs. Dynamic linking\endlink +\i \link #alloc Alternative memory allocation\endlink +\endlist + +\target general +\section1 General programming style + +The following guidelines will improve CPU performance: +\list + \i Create dialogs and widgets once, then QWidget::hide() and + QWidget::show() them, rather than creating them and deleting + them every time they are needed. + This will use a little more memory, but will be much faster. + Try to create them the first time "lazily" to avoid slow + startup (e.g. only create a Find dialog the first time the + user invokes it). +\endlist + +\target static +\section1 Static vs. Dynamic linking + +A lot of CPU and memory is used by the ELF linking process. You can +make significant savings by using a static build of your application +suite. This means that rather than having a dynamic library (\c +libqte.so) and a collection of executables which link dynamically to +that library, you build all the applications into a single executable +and statically link that with a static library (\c libqt.a). This +improves start-up time, and reduces memory usage, at the expense of +flexibility (to add a new application, you must recompile the single +executable) and robustness (if one application has a bug, it might +harm other applications). If you need to install end-user +applications, this may not be an option, but if you are building a +single application suite for a device with limited CPU power and +memory, this option could be very beneficial. + +To compile Qt as a static library, add the \c -static options when +you run configure. + +To build your application suite as an all-in-one application, design each +application as a stand-alone widget or set of widgets, with only minimal +code in the main() function. Then, write an application that gives +some way to switch between the applications (e.g. a QIconView). +\link http://www.trolltech.com/products/qtopia/index.html Qtopia +\endlink is an example of this. It can be built either as a set of +dynamically linked executables, or as a single static application. + +Note that you should generally still link dynamically against the +standard C library and any other libraries which might be used by +other applications on your device. + +\target alloc +\section1 Alternative memory allocation + +We have found that the libraries shipped with some C++ compilers on +some platforms have poor performance in the built-in "new" and "delete" +operators. You might gain performance by re-implementing these +functions. For example, you can switch to the plain C allocators +by adding the following to your code: + +\code + void* operator new[]( size_t size ) + { + return malloc( size ); + } + + void* operator new( size_t size ) + { + return malloc( size ); + } + + void operator delete[]( void *p ) + { + free( p ); + } + + void operator delete[]( void *p, size_t size ) + { + free( p ); + } + + void operator delete( void *p ) + { + free( p ); + } + + void operator delete( void *p, size_t size ) + { + free( p ); + } +\endcode +*/ + +/*! \page emb-vnc.html + +\title Qt/Embedded as a VNC Server + +The \link http://www.uk.research.att.com/vnc/ VNC \endlink protocol +allows you to view and interact with the computer's display from +anywhere on the network. + +To use Qt/Embedded in this way, \c configure Qt with the \c -qt-gfx-vnc +option, and ensure that you also enable 16-bit display support. Run +your application via: +\code + application -display VNC:0 +\endcode +then, run a VNC client pointing at the machine that is running your +application. For example, using the X11 VNC client to view the +application from the same machine: +\code + vncviewer localhost:0 +\endcode + +By default, Qt/Embedded will create a 640 by 480 pixel display. You +can change this by setting the \c QWS_SIZE environment variable to +another size, e.g. \c QWS_SIZE=240x320. + +VNC clients are available for a vast array of display systems: X11, +Windows, Amiga, DOS, VMS, and dozens of others. + +The \link emb-qvfb.html Qt Virtual Framebuffer \endlink is an alternative +technique. It uses shared memory and thus is much faster and smoother, but +it does not operate over a network. + +*/ |