qt3/doc/qws.doc

/****************************************************************************
**
** 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.

*/