/****************************************************************************
**
** Copyright (C) 2010 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}.
*/