diff options
Diffstat (limited to 'doc/qws.doc')
| -rw-r--r-- | doc/qws.doc | 670 |
1 files changed, 0 insertions, 670 deletions
diff --git a/doc/qws.doc b/doc/qws.doc deleted file mode 100644 index 3c68a04f..00000000 --- a/doc/qws.doc +++ /dev/null @@ -1,670 +0,0 @@ -/**************************************************************************** -** -** Qt/Embedded (Qt on QWS) documentation -** -** Copyright (C) 2000-2008 Trolltech ASA. All rights reserved. -** -** This file is part of the TQt 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 TQt 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 TQTDIR=~/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 $TQTDIR/include/ntqconfig.h and change the definition of -\c TQ_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-tqvfb.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>TQt 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 maketqpf.html tools/maketqpf\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 $TQTDIR/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 ./maketqpf "$@" -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-tqvfb.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 $TQTDIR is set to the directory where you -installed Qt/Embedded and add the $TQTDIR/lib directory to -$LD_LIBRARY_PATH, e.g.: -\code -export TQTDIR=$HOME/qt-VERSION -export LD_LIBRARY_PATH=$TQTDIR/lib:$LD_LIBRARY_PATH -\endcode - -Run the application with the \e{-qws} option: - -\code -cd $TQTDIR/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 TQt 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 TQt 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 TQ_WS_X11 -\row \i Qt/Windows \i TQ_WS_WIN -\row \i Qt/Embedded \i TQ_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 TQWidget::hide() and - TQWidget::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 -libtqte.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 libtqt.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 TQt 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 TQIconView). -\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 TQt 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-tqvfb.html TQt 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. - -*/ |