Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

1 files changed, 670 insertions, 0 deletions

diff --git a/doc/qws.doc b/doc/qws.doc
new file mode 100644
index 000000000..1e49621b1
--- /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 retquirements 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 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 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 retquires 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 retquire 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 retquires 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
+retquirements 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.
+
+*/