doc/src/emb-qvfb.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \page qvfb.html
  44
  45     \title The Virtual Framebuffer
  46     \ingroup qt-embedded-linux
  47
  48     \l{Qt for Embedded Linux} applications write directly to the
  49     framebuffer, eliminating the need for the X Window System and
  50     saving memory. For development and debugging purposes, a virtual
  51     framebuffer can be used, allowing \l{Qt for Embedded Linux}
  52     programs to be developed on a desktop machine, without switching
  53     between consoles and X11.
  54
  55     QVFb is an X11 application supplied with Qt for X11 that provides
  56     a virtual framebuffer for Qt for Embedded Linux to use. To use it,
  57     you need to \l{Installing Qt on X11 Platforms}{configure and
  58     install Qt on X11 platforms} appropriately. Further requirements
  59     can be found in the \l{Qt for Embedded Linux Requirements}
  60     document.
  61
  62     \image qt-embedded-virtualframebuffer.png
  63
  64     The virtual framebuffer emulates a framebuffer using a shared
  65     memory region and the \c qvfb tool to display the framebuffer in a
  66     window. The \c qvfb tool also supports a feature known as a skin
  67     which can be used to change the look and feel of the display. The
  68     tool is located in Qt's \c tools/qvfb directory, and provides
  69     several additional features accessible through its \gui File and
  70     \gui View menus.
  71
  72     Please note that the virtual framebuffer is a development tool
  73     only. No security issues have been considered in the virtual
  74     framebuffer design. It should be avoided in a production
  75     environment; i.e. do not configure production libraries with the
  76     \c -qvfb option.
  77
  78     \tableofcontents
  79
  80     \section1 Displaying the Virtual Framebuffer
  81
  82     To run the \c qvfb tool displaying the virtual framebuffer, the
  83     \l{Qt for Embedded Linux} library must be configured and compiled
  84     with the \c -qvfb option:
  85
  86     \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 0
  87
  88     Ensure that you have all the
  89     \l{Qt for Embedded Linux Requirements#Additional X11 Libraries for QVFb}
  90     {necessary libraries} needed to build the tool, then compile and run the
  91     \c qvfb tool as a normal Qt for X11 application (i.e., do \e not compile
  92     it as a \l{Qt for Embedded Linux} application):
  93
  94     \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 1
  95
  96     The \c qvfb application supports the following command line
  97     options:
  98
  99     \table
 100     \header \o Option \o Description
 101     \row
 102     \o \c {-width <value>}
 103     \o The width of the virtual framebuffer (default: 240).
 104     \row
 105     \o \c {-height <value>}
 106     \o The height of the virtual framebuffer (default: 320).
 107     \row
 108     \o \c {-depth <value>}
 109     \o The depth of the virtual framebuffer (1, 8 or 32; default: 8).
 110     \row
 111     \o \c -nocursor
 112     \o Do not display the X11 cursor in the framebuffer window.
 113     \row
 114     \o \c {-qwsdisplay <:id>}
 115     \o The \l{Qt for Embedded Linux} display ID (default: 0).
 116     \row
 117     \o \c {-skin <name>.skin}
 118     \o The preferred skin. Note that the skin must be located in Qt's
 119     \c /tools/qvfb/ directory.
 120     \row
 121     \o \c {-zoom <factor>}
 122     \o Scales the application view with the given factor.
 123
 124     \endtable
 125
 126     \section2 Skins
 127
 128     A skin is a set of XML and pixmap files that tells the vitual
 129     framebuffer what it should look like and how it should behave; a
 130     skin can change the unrealistic default display into a display
 131     that is similar to the target device. To access the \c qvfb tool's
 132     menus when a skin is activated, right-click over the display.
 133
 134     Note that a skin can have buttons which (when clicked) send
 135     signals to the Qt Extended application running inside the virtual
 136     framebuffer, just as would happen on a real device.
 137
 138     \table 100%
 139     \row
 140         \o
 141         \bold {Target Device Environment}
 142
 143         The \c qvfb tool provides various skins by default, allowing
 144         the user to view their application in an environment similar
 145         to their target device. The provided skins are:
 146
 147         \list
 148             \o ClamshellPhone
 149             \o pda
 150             \o PDAPhone
 151             \o Qt ExtendedPDA
 152             \o Qt ExtendedPhone-Advanced
 153             \o Qt ExtendedPhone-Simple
 154             \o SmartPhone
 155             \o SmartPhone2
 156             \o SmartPhoneWithButtons
 157             \o TouchscreenPhone
 158             \o Trolltech-Keypad
 159             \o Trolltech-Touchscreen
 160         \endlist
 161
 162         In addition, it is possible to create custom skins.
 163
 164         \o \image qt-embedded-phone.png
 165         \o \image qt-embedded-pda.png
 166     \endtable
 167
 168     \bold {Creating Custom Skins}
 169
 170     The XML and pixmap files specifying a custom skin must be located
 171     in subdirectory of the Qt's \c /tools/qvfb directory, called \c
 172     /customskin.skin. See the ClamshellPhone skin for an example of the
 173     file structure:
 174
 175     \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 2
 176
 177     The \c /ClamshellPhone.skin directory contains the following files:
 178
 179     \list
 180         \o \c ClamshellPhone.skin
 181         \o \c ClamshellPhone1-5.png
 182         \o \c ClamshellPhone1-5-pressed.png
 183         \o \c ClamshellPhone1-5-closed.png
 184         \o \c defaultbuttons.conf (only necessary for \l Qt Extended)
 185     \endlist
 186
 187     Note that the \c defaultbuttons.conf file is only necessary if the
 188     skin is supposed to be used with \l Qt Extended (The file customizes
 189     the launch screen applications, orders the soft keys and provides
 190     input method hints). See the \l Qt Extended documentation for more
 191     information.
 192
 193     \table 100%
 194     \header
 195     \o {3,1} The ClamshellPhone Skin
 196     \row
 197     \o {3,1}
 198
 199     \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 3
 200
 201     The \c ClamShellPhone.skin file quoted above, specifies three
 202     pixmaps: One for the normal skin (\c Up), one for the activated
 203     skin (\c Down) and one for the closed skin (\c Closed). In
 204     addition, it is possible to specify a pixmap for the cursor (using
 205     a \c Cursor variable).
 206
 207     The file also specifies the screen size (\c Screen) and the number
 208     of available buttons (\c Areas). Then it describes the buttons
 209     themselves; each button is specified by its name, keycode and
 210     coordinates.
 211
 212     The coordinates are a list of at least 2 points in clockwise order
 213     that define a shape for the button; a click inside this shape will
 214     be treated as a click on that button. While pressed, the pixels
 215     for the button are redrawn from the activated skin.
 216
 217     \row
 218     \row
 219     \o
 220     \image qt-embedded-clamshellphone-closed.png The ClamshellPhone Skin (closed)
 221     \o
 222     \image qt-embedded-clamshellphone.png The ClamshellPhone Skin
 223     \o
 224     \image qt-embedded-clamshellphone-pressed.png The ClamshellPhone Skin (pressed)
 225     \row
 226     \o \c ClamshellPhone1-5-closed.png
 227     \o \c ClamshellPhone1-5.png
 228     \o \c ClamshellPhone1-5-pressed.png
 229     \endtable
 230
 231     \section2 The File Menu
 232
 233     \image qt-embedded-qvfbfilemenu.png
 234
 235     The \gui File menu allows the user to configure the virtual
 236     framebuffer display (\gui File|Configure...), save a snapshot of
 237     the framebuffer contents (\gui {File|Save Image...}) and record
 238     the movements in the framebuffer (\gui File|Animation...).
 239
 240     When choosing the \gui File|Configure menu item, the \c qvfb tool
 241     provides a configuration dialog allowing the user to customize the
 242     display of the virtual framebuffer. The user can modify the size
 243     and depth as well as the Gamma values, and also select the
 244     preferred skin (i.e. making the virtual framebuffer simulate the
 245     target device environment). In addition, it is possible to emulate
 246     a touch screen and a LCD screen.
 247
 248     Note that when configuring (except when changing the Gamma values
 249     only), any applications using the virtual framebuffer will be
 250     terminated.
 251
 252     \section2 The View Menu
 253
 254     \image qt-embedded-qvfbviewmenu.png
 255
 256     The \gui View menu allows the user to modify the target's refresh
 257     rate (\gui {View|Refresh Rate...}), making \c qvfb check for
 258     updated regions more or less frequently.
 259
 260     The regions of the display that have changed are updated
 261     periodically, i.e. the virtual framebuffer is displaying discrete
 262     snapshots of the framebuffer rather than each individual drawing
 263     operation. For this reason drawing problems such as flickering may
 264     not be apparent until the program is run using a real framebuffer.
 265     If little drawing is being done, the framebuffer will not show any
 266     updates between drawing events. If an application is displaying an
 267     animation, the updates will be frequent, and the application and
 268     \c qvfb will compete for processor time.
 269
 270     The \gui View menu also allows the user to zoom the view of the
 271     application  (\gui {View|Zoom *}).
 272
 273     \section1 Running Applications Using the Virtual Framebuffer
 274
 275     Once the virtual framebuffer (the \c qvfb application) is running,
 276     it is ready for use: Start a server application (i.e. construct a
 277     QApplication object with the QApplication::GuiServer flag or use
 278     the \c -qws command line parameter. See the
 279     \l {Running Qt for Embedded Linux Applications}{running applications}
 280     documentation for details). For example:
 281
 282     \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 4
 283
 284     Note that as long as the virtual framebuffer is running and the
 285     current \l{Qt for Embedded Linux} configuration supports \c qvfb,
 286     \l{Qt for Embedded Linux} will automatically detect it and use it by
 287     default. Alternatively, the \c -display option can be used to
 288     specify the virtual framebuffer driver. For example:
 289
 290     \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 5
 291
 292     \warning If \c qvfb is not running (or the current
 293     \l{Qt for Embedded Linux} configuration doesn't support it) and the
 294     driver is not explicitly specified, \l{Qt for Embedded Linux} will
 295     write to the real framebuffer and the X11 display will be corrupted.
 296 */