/**************************************************************************** ** ** 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 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. Note: 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.) Note: \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 TrueType (TTF) \i The scalable font technology now standard on MS-Windows and Apple Macintosh, and becoming popular on X11. \row \i Postscript Type1 (PFA/PFB) \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 Bitmap Distribution Format
fonts (BDF) \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 Qt Prerendered Font (QPF) \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 Retquirements 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 NameTM") 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.

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: 

for dpy in LinuxFb Transformed:Rot90 Transformed:Rot180 Transformed:Rot270
do
    QWS_DISPLAY=$dpy ./makeqpf "$@"
done
If programs are only ever run in one orientation on a device, only the one appropriate set of fonts is needed.

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 Ctrl+Alt+Backspace. 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 Ctrl+Alt+F1 - 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{\}\c{:}\e{\} \endquote where \e{\} is one of: \list \i MouseMan \i IntelliMouse \i Microsoft \endlist and \e{\} 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 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. */