source: trunk/doc/src/platforms/emb-architecture.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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