1 files changed, 338 insertions, 0 deletions
diff --git a/doc/src/platforms/emb-architecture.qdoc b/doc/src/platforms/emb-architecture.qdoc
new file mode 100644
index 000000000..94f8384ff
--- /dev/null
+++ b/doc/src/platforms/emb-architecture.qdoc
@@ -0,0 +1,338 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qt-embedded-architecture.html
+
+    \title Qt for Embedded Linux Architecture
+    \ingroup qt-embedded-linux
+
+    A \l{Qt for Embedded Linux} application requires a server
+    application to be running, or to be the server application itself.
+    Any \l{Qt for Embedded Linux} application can act as the server.
+    When more than one application is running, the subsequent
+    applications connect to the existing server application as clients.
+
+    The server and client processes have different responsibilities:
+    The server process manages pointer handling, character input, and
+    screen output. In addition, the server controls the appearance of
+    the screen cursor and the screen saver. The client process
+    performs all application specific operations.
+
+    The server application is represented by an instance of the
+    QWSServer class, while the client applications are represented by
+    instances of the QWSClient class. On each side, there are several
+    classes performing the various operations.
+
+    \image qt-embedded-architecture2.png
+
+    All system generated events, including keyboard and mouse events,
+    are passed to the server application which then propagates the
+    event to the appropriate client.
+
+    When rendering, the default behavior is for each client to render
+    its widgets into memory while the server is responsible for
+    putting the contents of the memory onto the screen. But when the
+    hardware is known and well defined, as is often the case with
+    software for embedded devices, it may be useful for the clients to
+    manipulate and control the underlying hardware directly.
+    \l{Qt for Embedded Linux} provides two different approaches to
+    achieve this behavior, see the graphics rendering section below for
+    details.
+
+    \tableofcontents
+
+    \section1 Client/Server Communication
+
+    The running applications continuously alter the appearance of the
+    screen by adding and removing widgets. The server maintains
+    information about each top-level window in a corresponding
+    QWSWindow object.
+
+    Whenever the server receives an event, it queries its stack of
+    top-level windows to find the window containing the event's
+    position. Each window can identify the client application that
+    created it, and returns its ID to the server upon
+    request. Finally, the server forwards the event, encapsulated by
+    an instance of the QWSEvent class, to the appropriate client.
+
+    \image qt-embedded-clientservercommunication.png
+
+    If an input method is installed, it is used as a filter between
+    the server and the client application. Derive from the
+    QWSInputMethod class to implement custom input methods, and use
+    the server's \l {QWSServer::}{setCurrentInputMethod()} function to
+    install it. In addition, it is possible to implement global,
+    low-level filters on key events using the
+    QWSServer::KeyboardFilter class; this can be used to implement
+    things like advanced power management suspended from a button
+    without having to filter for it in all applications.
+
+    \table 100%
+    \header \o UNIX Domain Socket
+    \row
+    \o
+
+    \image qt-embedded-client.png
+
+    The server communicates with the client applications over the UNIX
+    domain socket. You can retrieve direct access to all the events a
+    client receives from the server, by reimplementing QApplication's
+    \l {QApplication::}{qwsEventFilter()} function.
+
+    \endtable
+
+    The clients (and the server) communicate with each other using the
+    QCopChannel class. QCOP is a many-to-many communication protocol
+    for transferring messages on various channels. A channel is
+    identified by a name, and anyone who wants to can listen to
+    it. The QCOP protocol allows clients to communicate both within
+    the same address space and between different processes.
+
+    \section1 Pointer Handling Layer
+
+    \list
+        \o QWSMouseHandler
+        \o QMouseDriverPlugin
+        \o QMouseDriverFactory
+    \endlist
+
+    The mouse driver (represented by an instance of the
+    QWSMouseHandler class) is loaded by the server application when it
+    starts running, using Qt's \l {How to Create Qt Plugins}{plugin
+    system}.
+
+    \image qt-embedded-pointerhandlinglayer.png
+
+    A mouse driver receives mouse events from the device and
+    encapsulates each event with an instance of the QWSEvent class
+    which it then passes to the server.
+
+    \l{Qt for Embedded Linux} provides ready-made drivers for several mouse
+    protocols, see the \l{Qt for Embedded Linux Pointer Handling}{pointer
+    handling} documentation for details. Custom mouse drivers can be
+    implemented by subclassing the QWSMouseHandler class and creating
+    a mouse driver plugin. The default implementation of the
+    QMouseDriverFactory class will automatically detect the plugin,
+    loading the driver into the server application at runtime.
+
+    In addition to the generic mouse handler, \l{Qt for Embedded Linux}
+    provides a calibrated mouse handler. Use the
+    QWSCalibratedMouseHandler class as the base class when the system
+    device does not have a fixed mapping between device and screen
+    coordinates and/or produces noisy events, e.g. a touchscreen.
+
+    See also: \l{Qt for Embedded Linux Pointer Handling} and
+    \l{How to Create Qt Plugins}.
+
+    \section1 Character Input Layer
+
+    \list
+        \o QWSKeyboardHandler
+        \o QKbdDriverPlugin
+        \o QKbdDriverFactory
+    \endlist
+
+    The keyboard driver (represented by an instance of the
+    QWSKeyboardHandler class) is loaded by the server application when
+    it starts running, using Qt's \l {How to Create Qt Plugins}{plugin
+    system}.
+
+    \image qt-embedded-characterinputlayer.png
+
+    A keyboard driver receives keyboard events from the device and
+    encapsulates each event with an instance of the QWSEvent class
+    which it then passes to the server.
+
+    \l{Qt for Embedded Linux} provides ready-made drivers for several keyboard
+    protocols, see the \l {Qt for Embedded Linux Character Input}{character
+    input} documentation for details. Custom keyboard drivers can be
+    implemented by subclassing the QWSKeyboardHandler class and
+    creating a keyboard driver plugin. The default implementation of the
+    QKbdDriverFactory class will automatically detect the plugin, loading the
+    driver into the server application at run-time.
+
+    See also: \l{Qt for Embedded Linux Character Input} and \l {How to Create
+    Qt Plugins}.
+
+    \section1  Graphics Rendering
+
+    \list
+        \o QApplication
+        \o QDecoration
+        \o QDecorationPlugin
+        \o QDecorationFactory
+    \endlist
+
+    The default behavior is for each client to render its widgets as well
+    as its decorations into memory, while the server copies the memory content
+    to the device's framebuffer.
+
+    Whenever a client receives an event that alters any of its
+    widgets, the application updates the relevant parts of its memory
+    buffer:
+
+    \image qt-embedded-clientrendering.png
+
+    The decoration is loaded by the client application when it starts
+    running (using Qt's \l {How to Create Qt Plugins}{plugin system}),
+    and can be customized by deriving from the QDecoration class and
+    creating a decoration plugin. The default implementation of
+    the QDecorationFactory class will automatically detect the plugin,
+    loading the decoration into the application at runtime. Call the
+    QApplication::qwsSetDecoration() function to actually apply the
+    given decoration to an application.
+
+    \table 100%
+    \header \o Direct Painting \target Direct Painting
+    \row
+    \o
+
+    It is possible for the clients to manipulate and control the
+    underlying hardware directly. There are two ways of achieving
+    this: The first approach is to set the Qt::WA_PaintOnScreen window
+    attribute for each widget, the other is to use the QDirectPainter
+    class to reserve a region of the framebuffer.
+
+    \image qt-embedded-setwindowattribute.png
+
+    By setting the Qt::WA_PaintOnScreen attribute, the application
+    renders the widget directly onto the screen and the affected
+    region will not be modified by the screen driver \e unless another
+    window with a higher focus requests (parts of) the same
+    region. Note that if you want to render all of an application's
+    widgets directly on screen, it might be easier to set the
+    QT_ONSCREEN_PAINT environment variable.
+
+    \image qt-embedded-reserveregion.png
+
+    Using QDirectPainter, on the other hand, provides a complete
+    control over the reserved region, i.e., the screen driver will
+    never modify the given region.
+
+    To draw on a region reserved by a QDirectPainter instance, the
+    application must get hold of a pointer to the framebuffer. In
+    general, a pointer to the framebuffer can be retrieved using the
+    QDirectPainter::frameBuffer() function. But note that if the
+    current screen has subscreens, you must query the screen driver
+    instead to identify the correct subscreen. A pointer to the
+    current screen driver can always be retrieved using the static
+    QScreen::instance() function. Then use QScreen's \l
+    {QScreen::}{subScreenIndexAt()} and \l {QScreen::}{subScreens()}
+    functions to access the correct subscreen, and the subscreen's \l
+    {QScreen::}{base()} function to retrieve a pointer to the
+    framebuffer.
+
+    Note that \l{Qt for Embedded Linux} also provides the QWSEmbedWidget class,
+    making it possible to embed the reserved region (i.e., the
+    QDirectPainter object) in a regular widget.
+
+    \endtable
+
+    \section1 Drawing on Screen
+
+    \list
+        \o QScreen
+        \o QScreenDriverPlugin
+        \o QScreenDriverFactory
+    \endlist
+
+    When a screen update is required, the server runs through all the
+    top-level windows that intersect with the region that is about to
+    be updated, and ensures that the associated clients have updated
+    their memory buffer. Then the server uses the screen driver
+    (represented by an instance of the QScreen class) to copy the
+    content of the memory to the screen.
+
+    The screen driver is loaded by the server application when it
+    starts running, using Qt's plugin system. \l{Qt for Embedded Linux}
+    provides ready-made drivers for several screen protocols, see the
+    \l{Qt for Embedded Linux Display Management}{display management}
+    documentation for details. Custom screen drivers can be
+    implemented by subclassing the QScreen class and creating a screen
+    driver plugin. The default implementation of the QScreenDriverFactory
+    class will automatically detect the plugin, loading the driver into
+    the server application at run-time.
+
+    \image qt-embedded-drawingonscreen.png
+
+    To locate the relevant parts of memory, the driver is provided
+    with the list of top-level windows that intersect with the given
+    region. Associated with each of the top-level windows there is an
+    instance of the QWSWindowSurface class representing the drawing
+    area of the window. The driver uses these objects to retrieve
+    pointers to the various memory blocks. Finally, the screen driver
+    composes the surface images before copying the updated region to
+    the framebuffer.
+
+    \table 100%
+    \header \o Accelerated Graphics
+    \row
+    \o
+
+    In \l{Qt for Embedded Linux}, painting is a pure software implementation,
+    but (starting with Qt 4.2) it is possible to add an accelerated
+    graphics driver to take advantage of available hardware resources.
+
+    \image qt-embedded-accelerateddriver.png
+
+    The clients render each window onto a corresponding window surface
+    object using Qt's paint system, and then store the surface in
+    memory. The screen driver accesses the memory and composes the
+    surface images before it copies them to the screen as explained
+    above.
+
+    To add an accelerated graphics driver you must create a custom
+    screen and implement a custom raster paint engine
+    (\l{Qt for Embedded Linux} uses a raster-based paint engine to
+    implement the painting operations). Then you must create a custom
+    paint device that is aware of your paint engine, a custom window
+    surface that knows about your paint device, and make your screen
+    able to recognize your window surface.
+
+    See the \l{Adding an Accelerated Graphics Driver to Qt for Embedded Linux}
+    {accelerated graphics driver} documentation for details.
+
+    \endtable
+
+    See also: \l{Qt for Embedded Linux Display Management} and
+    \l{How to Create Qt Plugins}.
+*/