1 files changed, 296 insertions, 0 deletions
diff --git a/doc/src/platforms/emb-qvfb.qdoc b/doc/src/platforms/emb-qvfb.qdoc
new file mode 100644
index 0000000..4674d88
--- /dev/null
+++ b/doc/src/platforms/emb-qvfb.qdoc
@@ -0,0 +1,296 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** 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 qvfb.html
+
+    \title The Virtual Framebuffer
+    \ingroup qt-embedded-linux
+
+    \l{Qt for Embedded Linux} applications write directly to the
+    framebuffer, eliminating the need for the X Window System and
+    saving memory. For development and debugging purposes, a virtual
+    framebuffer can be used, allowing \l{Qt for Embedded Linux}
+    programs to be developed on a desktop machine, without switching
+    between consoles and X11.
+
+    QVFb is an X11 application supplied with Qt for X11 that provides
+    a virtual framebuffer for Qt for Embedded Linux to use. To use it,
+    you need to \l{Installing Qt on X11 Platforms}{configure and
+    install Qt on X11 platforms} appropriately. Further requirements
+    can be found in the \l{Qt for Embedded Linux Requirements}
+    document.
+
+    \image qt-embedded-virtualframebuffer.png
+
+    The virtual framebuffer emulates a framebuffer using a shared
+    memory region and the \c qvfb tool to display the framebuffer in a
+    window. The \c qvfb tool also supports a feature known as a skin
+    which can be used to change the look and feel of the display. The
+    tool is located in Qt's \c tools/qvfb directory, and provides
+    several additional features accessible through its \gui File and
+    \gui View menus.
+
+    Please note that the virtual framebuffer is a development tool
+    only. No security issues have been considered in the virtual
+    framebuffer design. It should be avoided in a production
+    environment; i.e. do not configure production libraries with the
+    \c -qvfb option.
+
+    \tableofcontents
+
+    \section1 Displaying the Virtual Framebuffer
+
+    To run the \c qvfb tool displaying the virtual framebuffer, the
+    \l{Qt for Embedded Linux} library must be configured and compiled
+    with the \c -qvfb option:
+
+    \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 0
+
+    Ensure that you have all the
+    \l{Qt for Embedded Linux Requirements#Additional X11 Libraries for QVFb}
+    {necessary libraries} needed to build the tool, then compile and run the
+    \c qvfb tool as a normal Qt for X11 application (i.e., do \e not compile
+    it as a \l{Qt for Embedded Linux} application):
+
+    \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 1
+
+    The \c qvfb application supports the following command line
+    options:
+
+    \table
+    \header \o Option \o Description
+    \row
+    \o \c {-width <value>}
+    \o The width of the virtual framebuffer (default: 240).
+    \row
+    \o \c {-height <value>}
+    \o The height of the virtual framebuffer (default: 320).
+    \row
+    \o \c {-depth <value>}
+    \o The depth of the virtual framebuffer (1, 8 or 32; default: 8).
+    \row
+    \o \c -nocursor
+    \o Do not display the X11 cursor in the framebuffer window.
+    \row
+    \o \c {-qwsdisplay <:id>}
+    \o The \l{Qt for Embedded Linux} display ID (default: 0).
+    \row
+    \o \c {-skin <name>.skin}
+    \o The preferred skin. Note that the skin must be located in Qt's
+    \c /tools/qvfb/ directory.
+    \row
+    \o \c {-zoom <factor>}
+    \o Scales the application view with the given factor.
+
+    \endtable
+
+    \section2 Skins
+
+    A skin is a set of XML and pixmap files that tells the vitual
+    framebuffer what it should look like and how it should behave; a
+    skin can change the unrealistic default display into a display
+    that is similar to the target device. To access the \c qvfb tool's
+    menus when a skin is activated, right-click over the display.
+
+    Note that a skin can have buttons which (when clicked) send
+    signals to the Qt Extended application running inside the virtual
+    framebuffer, just as would happen on a real device.
+
+    \table 100%
+    \row
+        \o
+        \bold {Target Device Environment}
+
+        The \c qvfb tool provides various skins by default, allowing
+        the user to view their application in an environment similar
+        to their target device. The provided skins are:
+
+        \list
+            \o ClamshellPhone
+            \o pda
+            \o PDAPhone
+            \o Qt ExtendedPDA
+            \o Qt ExtendedPhone-Advanced
+            \o Qt ExtendedPhone-Simple
+            \o SmartPhone
+            \o SmartPhone2
+            \o SmartPhoneWithButtons
+            \o TouchscreenPhone
+            \o Trolltech-Keypad
+            \o Trolltech-Touchscreen
+        \endlist
+
+        In addition, it is possible to create custom skins.
+
+        \o \image qt-embedded-phone.png
+        \o \image qt-embedded-pda.png
+    \endtable
+
+    \bold {Creating Custom Skins}
+
+    The XML and pixmap files specifying a custom skin must be located
+    in subdirectory of the Qt's \c /tools/qvfb directory, called \c
+    /customskin.skin. See the ClamshellPhone skin for an example of the
+    file structure:
+
+    \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 2
+
+    The \c /ClamshellPhone.skin directory contains the following files:
+
+    \list
+        \o \c ClamshellPhone.skin
+        \o \c ClamshellPhone1-5.png
+        \o \c ClamshellPhone1-5-pressed.png
+        \o \c ClamshellPhone1-5-closed.png
+        \o \c defaultbuttons.conf (only necessary for \l Qt Extended)
+    \endlist
+
+    Note that the \c defaultbuttons.conf file is only necessary if the
+    skin is supposed to be used with \l Qt Extended (The file customizes
+    the launch screen applications, orders the soft keys and provides
+    input method hints). See the \l Qt Extended documentation for more
+    information.
+
+    \table 100%
+    \header
+    \o {3,1} The ClamshellPhone Skin
+    \row
+    \o {3,1}
+
+    \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 3
+
+    The \c ClamShellPhone.skin file quoted above, specifies three
+    pixmaps: One for the normal skin (\c Up), one for the activated
+    skin (\c Down) and one for the closed skin (\c Closed). In
+    addition, it is possible to specify a pixmap for the cursor (using
+    a \c Cursor variable).
+
+    The file also specifies the screen size (\c Screen) and the number
+    of available buttons (\c Areas). Then it describes the buttons
+    themselves; each button is specified by its name, keycode and
+    coordinates.
+
+    The coordinates are a list of at least 2 points in clockwise order
+    that define a shape for the button; a click inside this shape will
+    be treated as a click on that button. While pressed, the pixels
+    for the button are redrawn from the activated skin.
+
+    \row
+    \row
+    \o
+    \image qt-embedded-clamshellphone-closed.png The ClamshellPhone Skin (closed)
+    \o
+    \image qt-embedded-clamshellphone.png The ClamshellPhone Skin
+    \o
+    \image qt-embedded-clamshellphone-pressed.png The ClamshellPhone Skin (pressed)
+    \row
+    \o \c ClamshellPhone1-5-closed.png
+    \o \c ClamshellPhone1-5.png
+    \o \c ClamshellPhone1-5-pressed.png
+    \endtable
+
+    \section2 The File Menu
+
+    \image qt-embedded-qvfbfilemenu.png
+
+    The \gui File menu allows the user to configure the virtual
+    framebuffer display (\gui File|Configure...), save a snapshot of
+    the framebuffer contents (\gui {File|Save Image...}) and record
+    the movements in the framebuffer (\gui File|Animation...).
+
+    When choosing the \gui File|Configure menu item, the \c qvfb tool
+    provides a configuration dialog allowing the user to customize the
+    display of the virtual framebuffer. The user can modify the size
+    and depth as well as the Gamma values, and also select the
+    preferred skin (i.e. making the virtual framebuffer simulate the
+    target device environment). In addition, it is possible to emulate
+    a touch screen and a LCD screen.
+
+    Note that when configuring (except when changing the Gamma values
+    only), any applications using the virtual framebuffer will be
+    terminated.
+
+    \section2 The View Menu
+
+    \image qt-embedded-qvfbviewmenu.png
+
+    The \gui View menu allows the user to modify the target's refresh
+    rate (\gui {View|Refresh Rate...}), making \c qvfb check for
+    updated regions more or less frequently.
+
+    The regions of the display that have changed are updated
+    periodically, i.e. the virtual framebuffer is displaying discrete
+    snapshots of the framebuffer rather than each individual drawing
+    operation. For this reason drawing problems such as flickering may
+    not be apparent until the program is run using a real framebuffer.
+    If little drawing is being done, the framebuffer will not show any
+    updates between drawing events. If an application is displaying an
+    animation, the updates will be frequent, and the application and
+    \c qvfb will compete for processor time.
+
+    The \gui View menu also allows the user to zoom the view of the
+    application  (\gui {View|Zoom *}).
+
+    \section1 Running Applications Using the Virtual Framebuffer
+
+    Once the virtual framebuffer (the \c qvfb application) is running,
+    it is ready for use: Start a server application (i.e. construct a
+    QApplication object with the QApplication::GuiServer flag or use
+    the \c -qws command line parameter. See the
+    \l {Running Qt for Embedded Linux Applications}{running applications}
+    documentation for details). For example:
+
+    \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 4
+
+    Note that as long as the virtual framebuffer is running and the
+    current \l{Qt for Embedded Linux} configuration supports \c qvfb,
+    \l{Qt for Embedded Linux} will automatically detect it and use it by
+    default. Alternatively, the \c -display option can be used to
+    specify the virtual framebuffer driver. For example:
+
+    \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 5
+
+    \warning If \c qvfb is not running (or the current
+    \l{Qt for Embedded Linux} configuration doesn't support it) and the
+    driver is not explicitly specified, \l{Qt for Embedded Linux} will
+    write to the real framebuffer and the X11 display will be corrupted.
+*/