diff options
Diffstat (limited to 'doc/src/platforms/emb-qvfb.qdoc')
| -rw-r--r-- | doc/src/platforms/emb-qvfb.qdoc | 296 |
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..48e0d35 --- /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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. +*/ |