FCL/sf/mw/qt: comparison doc/src/platforms/emb-qvfb.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** 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.
+*/