/****************************************************************************+
−
**+
−
** 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 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.+
−
*/+
−