/****************************************************************************
** $Id:  qt/qws.doc   3.0.3   edited Jan 23 19:03 $
**
** Qt/Embedded (Qt on QWS) documentation
**
** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be distributed under the terms of the Q Public License
** as defined by Trolltech AS of Norway and appearing in the file
** LICENSE.QPL included in the packaging of this file.
**
** This file may be distributed and/or modified under the terms of the
** GNU General Public License version 2 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.
**
** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
** 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
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
**   information about Qt Commercial License Agreements.
** See http://www.trolltech.com/qpl/ for QPL licensing information.
** See http://www.trolltech.com/gpl/ for GPL licensing information.
**
** Contact info@trolltech.com if any conditions of this licensing are
** not clear to you.
**
**********************************************************************/
/*! \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-VERSION-commercial.tar.gz    # uncompress the archive
    tar xf qt-embedded-VERSION-commercial.tar       # unpack it
\endcode
Replace VERSION with the Qt/Embedded version number throughout.

This document assumes that the archive is installed as \c{~/qt-VERSION}. 
\i Compile the Qt/Embedded library and examples.

\code
    cd ~/qt-VERSION
    export QTDIR=~/qt-VERSION
    ./configure
    make
\endcode

The configuration system is designed to allow platform-specific options
to be added, but in general all Linux system which have framebuffer
support can use the "linux-generic-g++" platform.
The configuration system also supports cross-compilers:
to build \e on Linux/x86 \e for the Linux/MIPSEL target, you would use:
\code
    ./configure -platform linux-x86-g++ -xplatform linux-mips-g++
\endcode

Only a small number of configurations are predefined, all much the same.
Configurations files are found in \c configs/.

\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 HOWTO-Framebuffer 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:

\code
    cd ~/qt-VERSION/
    ./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.

  Some example programs may not compile with GCC 2.95.

  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; sometimes it may need to be deleted
  (eg. if you run Qt/Embedded as root 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.

\endlist

*/

/*! \page emb-fonts.html

\title Fonts in Qt/Embedded

\section1 Supported Formats

Qt/Embedded supports four font formats:

\list
 \i <b>TrueType (TTF)</b> - the scalable font technology now standard
	    on MS-Windows and Apple Macintosh, and becoming popular on X11.
 \i <b>Postscript Type1 (PFA/PFB)</b> - 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.
 \i <b>Bitmap Distribution Format fonts (BDF)</b> - 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.
 \i <b>Qt Prerendered Font (QPF)</b> - a light-weight non-scalable font
	    format specific to Qt/Embedded.
\endlist

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, thus
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 as Qt uses
when 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

In Qt/Embedded 2.2.1, smooth fonts use 8 times as much memory as non-smooth
fonts. This multiplier will be reduced to a configurable
2 or 4 (ie. 4-level and 16-level shading rather than the current excessive
256-level shading).

\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 pointsize times 10 (e.g., \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 pointsize times 10 (e.g., \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 (eg. 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 2.2.1.

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 running the application 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 widgets example appear.  If your mouse doesn't work
correctly you need to 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 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

At the time of writing Qt/Embedded supports MouseMan (default), Microsoft,
IntelliMouse and some other devices specific to certain hardware (e.g. Vr
touch panel).  To specify the mouse to use set the $QWS_MOUSE_PROTO environment
variable, e.g.:
\code
export QWS_MOUSE_PROTO=IntelliMouse
\endcode

\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

*/


/*! \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

Qt/Embedded normally 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 QAutoMouseSubHandler or
QMouseHandler can be written in \c kernel/qwsmouse_qws.cpp.

\section1 Touch Panels

Qt/Embedded ships with support for the NEC Vr41XX touchpanel
and the iPAQ touchpanel.
These are subclasses of QCalibratedMouseHandler which is in turn
a subclass of QMouseHandler in \c kernel/qwsmouse_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
	(only create the Find dialog the first time the user invokes it).
\endlist

\target static
\section1 Static vs. Dynamic linking

Much 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 (eg. a QIconView). The
\link http://www.trolltech.com/products/qt/embedded/qpe.html QPE
\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 -vnc option,
and ensure you also enable 16-bit display support. Run your application via:
\code
    application -display VNC:0
\endcode
then, run a VNC client pointed 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.

*/