diff options
Diffstat (limited to 'doc/src/platforms')
35 files changed, 6146 insertions, 0 deletions
diff --git a/doc/src/platforms/atomic-operations.qdoc b/doc/src/platforms/atomic-operations.qdoc new file mode 100644 index 0000000..4867c4a --- /dev/null +++ b/doc/src/platforms/atomic-operations.qdoc @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** 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 atomic-operations.html + \title Implementing Atomic Operations + \brief A guide to implementing atomic operations on new architectures. + + \ingroup best-practices + \ingroup qt-embedded-linux + + Qt uses an optimization called \l {Implicitly Shared + Classes}{implicit sharing} for many of its value classes. + + Starting with Qt 4, all of Qt's implicitly shared classes can + safely be copied across threads like any other value classes, + i.e., they are fully \l {Reentrancy and Thread-Safety}{reentrant}. + This is accomplished by implementing reference counting + operations using atomic hardware instructions on all the + different platforms supported by Qt. + + To support a new architecture, it is important to ensure that + these platform-specific atomic operations are implemented in a + corresponding header file (\c qatomic_ARCH.h), and that this file + is located in Qt's \c src/corelib/arch directory. For example, the + Intel 80386 implementation is located in \c + src/corelib/arch/qatomic_i386.h. + + Currently, Qt provides two classes providing several atomic + operations, QAtomicInt and QAtomicPointer. These classes inherit + from QBasicAtomicInt and QBasicAtomicPointer, respectively. + + When porting Qt to a new architecture, the QBasicAtomicInt and + QBasicAtomicPointer classes must be implemented, \e not QAtomicInt + and QAtomicPointer. The former classes do not have constructors, + which makes them POD (plain-old-data). Both classes only have a + single member variable called \c _q_value, which stores the + value. This is the value that all of the atomic operations read + and modify. + + All of the member functions mentioned in the QAtomicInt and + QAtomicPointer API documentation must be implemented. Note that + these the implementations of the atomic operations in these + classes must be atomic with respect to both interrupts and + multiple processors. + + \warning The QBasicAtomicInt and QBasicAtomicPointer classes + mentioned in this document are used internally by Qt and are not + part of the public API. They may change in future versions of + Qt. The purpose of this document is to aid people interested in + porting Qt to a new architecture. +*/ diff --git a/doc/src/platforms/compiler-notes.qdoc b/doc/src/platforms/compiler-notes.qdoc new file mode 100644 index 0000000..f4e9805 --- /dev/null +++ b/doc/src/platforms/compiler-notes.qdoc @@ -0,0 +1,278 @@ +/**************************************************************************** +** +** 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 compiler-notes.html + \ingroup platform-specific + \title Compiler Notes + \brief Information about the C++ compilers and tools used to build Qt. + + This page contains information about the C++ compilers and tools used + to build Qt on various platforms. + + \tableofcontents + + Please refer to the \l{Platform Notes} for information on the platforms + Qt is currently known to run on, and see the \l{Supported Platforms} + page for information about the status of each platform. + + If you have anything to add to this list or any of the platform or + compiler-specific pages, please submit it via the \l{Bug Report Form} + or through the \l{Public Qt Repository}. + + \section1 Supported Features + + Not all compilers used to build Qt are able to compile all modules. The following table + shows the compiler support for five modules that are not uniformly available for all + platforms and compilers. + + \table + \header \o Compiler \o{5,1} Features + \header \o \o Concurrent \o XmlPatterns \o WebKit \o CLucene \o Phonon + \row \o g++ 3.3 \o \o \bold{X} \o \o \bold{X} \o \bold{X} + \row \o g++ 3.4 and up \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \row + \row \o SunCC 5.5 \o \o \o \o \bold{X} \o \bold{X} + \row + \row \o aCC series 3 \o \o \o \o \bold{X} \o \bold{X} + \row \o aCC series 6 \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \row \o xlC 6 \o \o \o \o \bold{X} \o \bold{X} + \row \o Intel CC 10 \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \row + \row \o MSVC 2003 \o \bold{X} \o \bold{X} \o \o \bold{X} \o \bold{X} + \row \o MSVC 2005 and up \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \endtable + + \target GCC + \section1 GCC + + \section2 GCC on Windows (MinGW) + + We have tested Qt with this compiler on Windows XP. + The minimal version of MinGW supported is: + + \list + \o GCC 3.4.2 + \o MinGW runtime 3.7 + \o win32api 3.2 + \o binutils 2.15.91 + \o mingw32-make 3.80.0-3 + \endlist + + \section2 GCC 4.0.0 + + The released package of the compiler has some bugs that lead to miscompilations. + We recommend using GCC 4.0.1 or later, or to use a recent CVS snapshot of the + GCC 4.0 branch. The version of GCC 4.0.0 that is shipped with Mac OS X 10.4 + "Tiger" is known to work with Qt for Mac OS X. + + \section2 HP-UX + + The hpux-g++ platform is tested with GCC 3.4.4. + + \section2 Solaris + + Please use GCC 3.4.2 or later. + + \section2 Mac OS X + + Please use the latest GCC 3.3 from Apple or a later version of GCC 3. + The gcc 3.3 that is provided with Xcode 1.5 is known to generate bad code. + Use the November 2004 GCC 3.3 updater \l{http://connect.apple.com}{available from Apple}. + + \section2 GCC 3.4.6 (Debian 3.4.6-5) on AMD64 (x86_64) + + This compiler is known to miscompile some parts of Qt when doing a + release build. There are several workarounds: + + \list 1 + \o Use a debug build instead. + \o For each miscompilation encountered, recompile the file, removing the -O2 option. + \o Add -fno-gcse to the QMAKE_CXXFLAGS_RELEASE. + \endlist + + \section1 HP ANSI C++ (aCC) + + The hpux-acc-32 and hpux-acc-64 platforms are tested with aCC A.03.57. The + hpuxi-acc-32 and hpuxi-acc-64 platforms are tested with aCC A.06.10. + + \section1 Intel C++ Compiler + + Qt supports the Intel C++ compiler on both Windows and Linux. + However, there are a few issues on Linux (see the following + section). + + \section2 Intel C++ Compiler for Linux + + Nokia currently tests the following compilers: + + \list + + \o Intel(R) C++ Compiler for applications running on IA-32, + Version 10.1 Build 20080602 Package ID: l_cc_p_10.1.017 + + \o Intel(R) C++ Compiler for applications running on Intel(R) 64, + Version 10.1 Build 20080602 Package ID: l_cc_p_10.1.017 + + \endlist + + We do not currently test the IA-64 (Itanium) compiler. + + \section2 Known Issues with Intel C++ Compiler for Linux + + \list + + \o Precompiled header support does not work in version 10.0.025 + and older. For these compilers, you should configure Qt with + -no-pch. Precompiled header support works properly in version + 10.0.026 and later. + \o Version 10.0.026 for Intel 64 is known to miscompile qmake when + building in release mode. For now, configure Qt with + -debug. Version 10.1.008 and later can compile qmake in release + mode. + \o Versions 10.1.008 to 10.1.015 for both IA-32 and Intel 64 are + known crash with "(0): internal error: 0_47021" when compiling + QtXmlPatterns, QtWebKit, and Designer in release mode. Version + 10.1.017 compiles these modules correctly in release mode. + \endlist + + \section2 Intel C++ Compiler (Windows, Altix) + + Qt 4 has been tested successfully with: + + \list + \o Windows - Intel(R) C++ Compiler for 32-bit applications, + Version 8.1 Build 20050309Z Package ID: W_CC_PC_8.1.026 + \o Altix - Intel(R) C++ Itanium(R) Compiler for Itanium(R)-based + applications Version 8.1 Build 20050406 Package ID: l_cc_pc_8.1.030 + \endlist + + We currently only test the Intel compiler on 32-bit Windows versions. + + \section1 MIPSpro (IRIX) + + \bold{IRIX is an unsupported platform. See the \l{Supported Platforms} page + and Qt's Software's online \l{Platform Support Policy} page for details.} + + Qt 4.4.x requires MIPSpro version 7.4.2m. + + Note that MIPSpro version 7.4.4m is currently not supported, since it has + introduced a number of problems that have not yet been resolved. + We recommend using 7.4.2m for Qt development. However, please note the + unsupported status of this platform. + + \target Sun Studio + \section1 Forte Developer / Sun Studio (Solaris) + + \section2 Sun Studio + + Qt is tested using Sun Studio 8 (Sun CC 5.5). Go to + \l{Sun Studio Patches} page on Sun's Web site to download + the latest patches for your Sun compiler. + + \section2 Sun WorkShop 5.0 + + Sun WorkShop 5.0 is not supported with Qt 4. + + \section1 Visual Studio (Windows) + + We do most of our Windows development on Windows XP, using Microsoft + Visual Studio .NET 2005 and Visual Studio 2008 (both the 32- and 64-bit + versions). + + Qt works with the Standard Edition, the Professional Edition and Team + System Edition of Visual Studio 2005. + + We also test Qt 4 on Windows XP with Visual Studio .NET and Visual Studio 2003. + + In order to use Qt with the Visual Studio 2005/2008 Express Edition you need + to download and install the platform SDK. Due to limitations in the + Express Edition it is not possible for us to install the Qt Visual + Studio Integration. You will need to use our command line tools to + build Qt applications with this edition. + + The Visual C++ Linker doesn't understand filenames with spaces (as in + \c{C:\Program files\Qt\}) so you will have to move it to another place, + or explicitly set the path yourself; for example: + + \snippet doc/src/snippets/code/doc_src_compiler-notes.qdoc 0 + + If you are experiencing strange problems with using special flags that + modify the alignment of structure and union members (such as \c{/Zp2}) + then you will need to recompile Qt with the flags set for the + application as well. + + If you're using Visual Studio .NET (2002) Standard Edition, you should be + using the Qt binary package provided, and not the source package. + As the Standard Edition does not optimize compiled code, your compiled + version of Qt would perform suboptimally with respect to speed. + + With Visual Studio 2005 Service Pack 1 a bug was introduced which + causes Qt not to compile, this has been fixed with a hotfix available + from Microsoft. See this + \l{http://qt.nokia.com/developer/faqs/faq.2006-12-18.3281869860}{Knowledge Base entry} + for more information. + + \section1 IBM xlC (AIX) + + The makeC++SharedLib utility must be in your PATH and be up to date to + build shared libraries. From IBM's + \l{http://www.redbooks.ibm.com/abstracts/sg245674.html}{C and C++ Application Development on AIX} + Redbook: + + \list + \o "The second step is to use the makeC++SharedLib command to create the + shared object. The command has many optional arguments, but in its + simplest form, can be used as follows:" + \snippet doc/src/snippets/code/doc_src_compiler-notes.qdoc 1 + \o "The full path name to the command is not required; however, to avoid + this, you will have to add the directory in which it is located to + your PATH environment variable. The command is located in the + /usr/vacpp/bin directory with the VisualAge C++ Professional for AIX, + Version 5 compiler." + \endlist + + \section2 VisualAge C++ for AIX, Version 6.0 + + Make sure you have the + \l{http://www-1.ibm.com/support/search.wss?rs=32&tc=SSEP5D&dc=D400}{latest upgrades} + installed. +*/ diff --git a/doc/src/platforms/emb-accel.qdoc b/doc/src/platforms/emb-accel.qdoc new file mode 100644 index 0000000..b2d676c --- /dev/null +++ b/doc/src/platforms/emb-accel.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** 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 qt-embedded-accel.html + + \target add your graphics driver to Qt for Embedded Linux + + \title Adding an Accelerated Graphics Driver to Qt for Embedded Linux + \ingroup qt-embedded-linux + + In \l{Qt for Embedded Linux}, painting is a pure software implementation + normally performed in two steps. First, each window is rendered + onto a QWSWindowSurface using QPaintEngine. Second, the server + composes the surface images and copies the composition to the + screen (see \l{Qt for Embedded Linux Architecture} for details). + \l{Qt for Embedded Linux} uses QRasterPaintEngine (a raster-based implementation of + QPaintEngine) to implement painting operations, and uses QScreen + to implement window composition. + + It is possible to add an accelerated graphics driver to take + advantage of available hardware resources. This is described in + detail in the \l {Accelerated Graphics Driver Example} which uses + the following approach: + + \tableofcontents + + \warning This feature is under development and is subject to + change. + + \section1 Step 1: Create a Custom Screen + + Create a custom screen by deriving from the QScreen class. + + The \l {QScreen::}{connect()}, \l {QScreen::}{disconnect()}, \l + {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()} + functions are declared as pure virtual functions in QScreen and + must be implemented. These functions are used to configure the + hardware, or query its configuration. The \l + {QScreen::}{connect()} and \l {QScreen::}{disconnect()} are called + by both the server and client processes, while the \l + {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()} + functions are only called by the server process. + + You might want to accelerate the final copying to the screen by + reimplementing the \l {QScreen::}{blit()} and \l + {QScreen::}{solidFill()} functions. + + \section1 Step 2: Implement a Custom Raster Paint Engine + + Implement the painting operations by subclassing the + QRasterPaintEngine class. + + To accelerate a graphics primitive, simply reimplement the + corresponding function in your custom paint engine. If there is + functionality you do not want to reimplement (such as certain + pens, brushes, modes, etc.), you can just call the corresponding + base class implementation. + + \section1 Step 3: Make the Paint Device Aware of Your Paint Engine + + To activate your paint engine you must create a subclass of the + QCustomRasterPaintDevice class and reimplement its \l + {QCustomRasterPaintDevice::}{paintEngine()} function. Let this + function return a pointer to your paint engine. In addition, the + QCustomRasterPaintDevice::memory() function must be reimplemented + to return a pointer to the buffer where the painting should be + done. + + \table + \header \o Acceleration Without a Memory Buffer + \row + \o + + By default the QRasterPaintEngine draws into a memory buffer (this can + be local memory, shared memory or graphics memory mapped into + application memory). + In some cases you might want to avoid using a memory buffer directly, + e.g if you want to use an accelerated graphic controller to handle all + the buffer manipulation. This can be implemented by reimplementing + the QCustomRasterPaintDevice::memory() function to return 0 (meaning + no buffer available). Then, whenever a color or image buffer normally + would be written into paint engine buffer, the paint engine will call the + QRasterPaintEngine::drawColorSpans() and + QRasterPaintEngine::drawBufferSpan() functions instead. + + Note that the default implementations of these functions only + calls qFatal() with an error message; reimplement the functions + and let them do the appropriate communication with the accelerated + graphics controller. + + \endtable + + \section1 Step 4: Make the Window Surface Aware of Your Paint Device + + Derive from the QWSWindowSurface class and reimplement its \l + {QWSWindowSurface::}{paintDevice()} function. Make this function + return a pointer to your custom raster paint device. + + \section1 Step 5: Enable Creation of an Instance of Your Window Surface + + Finally, reimplement QScreen's \l {QScreen::}{createSurface()} + function and make this function able to create an instance of your + QWSWindowSurface subclass. +*/ diff --git a/doc/src/platforms/emb-architecture.qdoc b/doc/src/platforms/emb-architecture.qdoc new file mode 100644 index 0000000..d7e385b --- /dev/null +++ b/doc/src/platforms/emb-architecture.qdoc @@ -0,0 +1,338 @@ +/**************************************************************************** +** +** 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 qt-embedded-architecture.html + + \title Qt for Embedded Linux Architecture + \ingroup qt-embedded-linux + + A \l{Qt for Embedded Linux} application requires a server + application to be running, or to be the server application itself. + Any \l{Qt for Embedded Linux} application can act as the server. + When more than one application is running, the subsequent + applications connect to the existing server application as clients. + + The server and client processes have different responsibilities: + The server process manages pointer handling, character input, and + screen output. In addition, the server controls the appearance of + the screen cursor and the screen saver. The client process + performs all application specific operations. + + The server application is represented by an instance of the + QWSServer class, while the client applications are represented by + instances of the QWSClient class. On each side, there are several + classes performing the various operations. + + \image qt-embedded-architecture2.png + + All system generated events, including keyboard and mouse events, + are passed to the server application which then propagates the + event to the appropriate client. + + When rendering, the default behavior is for each client to render + its widgets into memory while the server is responsible for + putting the contents of the memory onto the screen. But when the + hardware is known and well defined, as is often the case with + software for embedded devices, it may be useful for the clients to + manipulate and control the underlying hardware directly. + \l{Qt for Embedded Linux} provides two different approaches to + achieve this behavior, see the graphics rendering section below for + details. + + \tableofcontents + + \section1 Client/Server Communication + + The running applications continuously alter the appearance of the + screen by adding and removing widgets. The server maintains + information about each top-level window in a corresponding + QWSWindow object. + + Whenever the server receives an event, it queries its stack of + top-level windows to find the window containing the event's + position. Each window can identify the client application that + created it, and returns its ID to the server upon + request. Finally, the server forwards the event, encapsulated by + an instance of the QWSEvent class, to the appropriate client. + + \image qt-embedded-clientservercommunication.png + + If an input method is installed, it is used as a filter between + the server and the client application. Derive from the + QWSInputMethod class to implement custom input methods, and use + the server's \l {QWSServer::}{setCurrentInputMethod()} function to + install it. In addition, it is possible to implement global, + low-level filters on key events using the + QWSServer::KeyboardFilter class; this can be used to implement + things like advanced power management suspended from a button + without having to filter for it in all applications. + + \table 100% + \header \o UNIX Domain Socket + \row + \o + + \image qt-embedded-client.png + + The server communicates with the client applications over the UNIX + domain socket. You can retrieve direct access to all the events a + client receives from the server, by reimplementing QApplication's + \l {QApplication::}{qwsEventFilter()} function. + + \endtable + + The clients (and the server) communicate with each other using the + QCopChannel class. QCOP is a many-to-many communication protocol + for transferring messages on various channels. A channel is + identified by a name, and anyone who wants to can listen to + it. The QCOP protocol allows clients to communicate both within + the same address space and between different processes. + + \section1 Pointer Handling Layer + + \list + \o QWSMouseHandler + \o QMouseDriverPlugin + \o QMouseDriverFactory + \endlist + + The mouse driver (represented by an instance of the + QWSMouseHandler class) is loaded by the server application when it + starts running, using Qt's \l {How to Create Qt Plugins}{plugin + system}. + + \image qt-embedded-pointerhandlinglayer.png + + A mouse driver receives mouse events from the device and + encapsulates each event with an instance of the QWSEvent class + which it then passes to the server. + + \l{Qt for Embedded Linux} provides ready-made drivers for several mouse + protocols, see the \l{Qt for Embedded Linux Pointer Handling}{pointer + handling} documentation for details. Custom mouse drivers can be + implemented by subclassing the QWSMouseHandler class and creating + a mouse driver plugin. The default implementation of the + QMouseDriverFactory class will automatically detect the plugin, + loading the driver into the server application at runtime. + + In addition to the generic mouse handler, \l{Qt for Embedded Linux} + provides a calibrated mouse handler. Use the + QWSCalibratedMouseHandler class as the base class when the system + device does not have a fixed mapping between device and screen + coordinates and/or produces noisy events, e.g. a touchscreen. + + See also: \l{Qt for Embedded Linux Pointer Handling} and + \l{How to Create Qt Plugins}. + + \section1 Character Input Layer + + \list + \o QWSKeyboardHandler + \o QKbdDriverPlugin + \o QKbdDriverFactory + \endlist + + The keyboard driver (represented by an instance of the + QWSKeyboardHandler class) is loaded by the server application when + it starts running, using Qt's \l {How to Create Qt Plugins}{plugin + system}. + + \image qt-embedded-characterinputlayer.png + + A keyboard driver receives keyboard events from the device and + encapsulates each event with an instance of the QWSEvent class + which it then passes to the server. + + \l{Qt for Embedded Linux} provides ready-made drivers for several keyboard + protocols, see the \l {Qt for Embedded Linux Character Input}{character + input} documentation for details. Custom keyboard drivers can be + implemented by subclassing the QWSKeyboardHandler class and + creating a keyboard driver plugin. The default implementation of the + QKbdDriverFactory class will automatically detect the plugin, loading the + driver into the server application at run-time. + + See also: \l{Qt for Embedded Linux Character Input} and \l {How to Create + Qt Plugins}. + + \section1 Graphics Rendering + + \list + \o QApplication + \o QDecoration + \o QDecorationPlugin + \o QDecorationFactory + \endlist + + The default behavior is for each client to render its widgets as well + as its decorations into memory, while the server copies the memory content + to the device's framebuffer. + + Whenever a client receives an event that alters any of its + widgets, the application updates the relevant parts of its memory + buffer: + + \image qt-embedded-clientrendering.png + + The decoration is loaded by the client application when it starts + running (using Qt's \l {How to Create Qt Plugins}{plugin system}), + and can be customized by deriving from the QDecoration class and + creating a decoration plugin. The default implementation of + the QDecorationFactory class will automatically detect the plugin, + loading the decoration into the application at runtime. Call the + QApplication::qwsSetDecoration() function to actually apply the + given decoration to an application. + + \table 100% + \header \o Direct Painting \target Direct Painting + \row + \o + + It is possible for the clients to manipulate and control the + underlying hardware directly. There are two ways of achieving + this: The first approach is to set the Qt::WA_PaintOnScreen window + attribute for each widget, the other is to use the QDirectPainter + class to reserve a region of the framebuffer. + + \image qt-embedded-setwindowattribute.png + + By setting the Qt::WA_PaintOnScreen attribute, the application + renders the widget directly onto the screen and the affected + region will not be modified by the screen driver \e unless another + window with a higher focus requests (parts of) the same + region. Note that if you want to render all of an application's + widgets directly on screen, it might be easier to set the + QT_ONSCREEN_PAINT environment variable. + + \image qt-embedded-reserveregion.png + + Using QDirectPainter, on the other hand, provides a complete + control over the reserved region, i.e., the screen driver will + never modify the given region. + + To draw on a region reserved by a QDirectPainter instance, the + application must get hold of a pointer to the framebuffer. In + general, a pointer to the framebuffer can be retrieved using the + QDirectPainter::frameBuffer() function. But note that if the + current screen has subscreens, you must query the screen driver + instead to identify the correct subscreen. A pointer to the + current screen driver can always be retrieved using the static + QScreen::instance() function. Then use QScreen's \l + {QScreen::}{subScreenIndexAt()} and \l {QScreen::}{subScreens()} + functions to access the correct subscreen, and the subscreen's \l + {QScreen::}{base()} function to retrieve a pointer to the + framebuffer. + + Note that \l{Qt for Embedded Linux} also provides the QWSEmbedWidget class, + making it possible to embed the reserved region (i.e., the + QDirectPainter object) in a regular widget. + + \endtable + + \section1 Drawing on Screen + + \list + \o QScreen + \o QScreenDriverPlugin + \o QScreenDriverFactory + \endlist + + When a screen update is required, the server runs through all the + top-level windows that intersect with the region that is about to + be updated, and ensures that the associated clients have updated + their memory buffer. Then the server uses the screen driver + (represented by an instance of the QScreen class) to copy the + content of the memory to the screen. + + The screen driver is loaded by the server application when it + starts running, using Qt's plugin system. \l{Qt for Embedded Linux} + provides ready-made drivers for several screen protocols, see the + \l{Qt for Embedded Linux Display Management}{display management} + documentation for details. Custom screen drivers can be + implemented by subclassing the QScreen class and creating a screen + driver plugin. The default implementation of the QScreenDriverFactory + class will automatically detect the plugin, loading the driver into + the server application at run-time. + + \image qt-embedded-drawingonscreen.png + + To locate the relevant parts of memory, the driver is provided + with the list of top-level windows that intersect with the given + region. Associated with each of the top-level windows there is an + instance of the QWSWindowSurface class representing the drawing + area of the window. The driver uses these objects to retrieve + pointers to the various memory blocks. Finally, the screen driver + composes the surface images before copying the updated region to + the framebuffer. + + \table 100% + \header \o Accelerated Graphics + \row + \o + + In \l{Qt for Embedded Linux}, painting is a pure software implementation, + but (starting with Qt 4.2) it is possible to add an accelerated + graphics driver to take advantage of available hardware resources. + + \image qt-embedded-accelerateddriver.png + + The clients render each window onto a corresponding window surface + object using Qt's paint system, and then store the surface in + memory. The screen driver accesses the memory and composes the + surface images before it copies them to the screen as explained + above. + + To add an accelerated graphics driver you must create a custom + screen and implement a custom raster paint engine + (\l{Qt for Embedded Linux} uses a raster-based paint engine to + implement the painting operations). Then you must create a custom + paint device that is aware of your paint engine, a custom window + surface that knows about your paint device, and make your screen + able to recognize your window surface. + + See the \l{Adding an Accelerated Graphics Driver to Qt for Embedded Linux} + {accelerated graphics driver} documentation for details. + + \endtable + + See also: \l{Qt for Embedded Linux Display Management} and + \l{How to Create Qt Plugins}. +*/ diff --git a/doc/src/platforms/emb-charinput.qdoc b/doc/src/platforms/emb-charinput.qdoc new file mode 100644 index 0000000..3d6555d --- /dev/null +++ b/doc/src/platforms/emb-charinput.qdoc @@ -0,0 +1,164 @@ +/**************************************************************************** +** +** 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 qt-embedded-charinput.html + + \title Qt for Embedded Linux Character Input + \ingroup qt-embedded-linux + + When running a \l {Qt for Embedded Linux} application, it either runs as a + server or connects to an existing server. The keyboard driver is + loaded by the server application when it starts running, using + Qt's \l {How to Create Qt Plugins}{plugin system}. + + Internally in the client/server protocol, all system generated + events, including key events, are passed to the server application + which then propagates the event to the appropriate client. Note + that key events do not always come from a keyboard device, they + can can also be generated by the server process using input + widgets. + + \table + \header \o Input Widgets + \row + \o + + The server process may call the static QWSServer::sendKeyEvent() + function at any time. Typically, this is done by popping up a + widget that enables the user specify characters with the pointer + device. + + Note that the key input widget should not take focus since the + server would then just send the key events back to the input + widget. One way to make sure that the input widget never takes + focus is to set the Qt::Tool widget flag in the QWidget + constructor. + + The \l{Qt Extended} environment contains various input widgets such as + Handwriting Recognition and Virtual Keyboard. + + \endtable + + \tableofcontents + + \section1 Available Keyboard Drivers + + \l {Qt for Embedded Linux} provides ready-made drivers for the console + (TTY) and the standard Linux Input Subsystem (USB, PS/2, ...). Run the + \c configure script to list the available drivers: + + \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 0 + + Note that only the console (TTY) keyboard driver handles console + switching (\bold{Ctrl+Alt+F1}, ..., \bold{Ctrl+Alt+F10}) and + termination (\bold{Ctrl+Alt+Backspace}). + + In the default Qt configuration, only the "TTY" driver is + enabled. The various drivers can be enabled and disabled using the + \c configure script. For example: + + \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 1 + + Custom keyboard drivers can be implemented by subclassing the + QWSKeyboardHandler class and creating a keyboard driver plugin + (derived from the QKbdDriverPlugin class). The default + implementation of the QKbdDriverFactory class will automatically + detect the plugin, loading the driver into the server application + at run-time. + + \section1 Keymaps + + Starting with 4.6, \l {Qt for Embedded Linux} has gained support for + user defined keymaps. Keymap handling is supported by the built-in + keyboard drivers \c TTY and \c LinuxInput. Custom keyboard drivers can + use the existing keymap handling code via + QWSKeyboardHandler::processKeycode(). + + By default Qt will use an internal, compiled-in US keymap. + See the options below for how to load a different keymap. + + \section1 Specifying a Keyboard Driver + + To specify which driver to use, set the QWS_KEYBOARD environment + variable. For example (if the current shell is bash, ksh, zsh or + sh): + + \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 2 + + The \c <driver> arguments are \c TTY, \c LinuxInput and \l + {QKbdDriverPlugin::keys()}{keys} identifying custom drivers, and the + driver specific options are typically a device, e.g., \c /dev/tty0. + + Multiple keyboard drivers can be specified in one go: + + \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 3 + + Input will be read from all specified drivers. + + Currently the following options are supported by both the \c TTY and \c + LinuxInput driver: + + \table + \header \o Option \o Description + \row \o \c /dev/xxx \o + Open the specified device, instead of the driver's default device. + \row \o \c repeat-delay=<d> \o + Time (in milliseconds) until auto-repeat kicks in. + \row \o \c repeat-rate=<r> \o + Time (in milliseconds) specifying the interval between auto-repeats. + \row \o \c keymap=xx.qmap \o + File name of a keymap file in Qt's \c qmap format. See \l {kmap2qmap} + for instructions on how to create thoes files.\br Note that the file + name can of course also be the name of a QResource. + \row \o \c disable-zap \o + Disable the QWS server "Zap" shortcut \bold{Ctrl+Alt+Backspace} + \row \o \c enable-compose \o + Activate Latin-1 composing features in the built-in US keymap. You can + use the right \c AltGr or right \c Alt is used as a dead key modifier, + while \c AltGr+. is the compose key. For example: + \list + \o \c AltGr + \c " + \c u = \uuml (u with diaeresis / umlaut u) + \o \c AltGr + \c . + \c / + \c o = \oslash (slashed o) + \endlist + \endtable + +*/ diff --git a/doc/src/platforms/emb-crosscompiling.qdoc b/doc/src/platforms/emb-crosscompiling.qdoc new file mode 100644 index 0000000..20919e3 --- /dev/null +++ b/doc/src/platforms/emb-crosscompiling.qdoc @@ -0,0 +1,185 @@ +/**************************************************************************** +** +** 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 qt-embedded-crosscompiling.html + + \title Cross-Compiling Qt for Embedded Linux Applications + \ingroup qt-embedded-linux + + Cross-compiling is the process of compiling an application on one + machine, producing executable code for a different machine or + device. To cross-compile a \l{Qt for Embedded Linux} application, + use the following approach: + + \tableofcontents + + \note The cross-compiling procedure has the configuration + process in common with the installation procedure; i.e., you might + not necessarily have to perform all the mentioned actions + depending on your current configuration. + + \section1 Step 1: Set the Cross-Compiler's Path + + Specify which cross-compiler to use by setting the \c PATH + environment variable. For example, if the current shell is bash, + ksh, zsh or sh: + + \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 0 + + \section1 Step 2: Create a Target Specific qmake Specification + + The qmake tool requires a platform and compiler specific \c + qmake.conf file describing the various default values, to generate + the appropriate Makefiles. The standard \l{Qt for Embedded Linux} + distribution provides such files for several combinations of + platforms and compilers. These files are located in the + distribution's \c mkspecs/qws subdirectory. + + Each platform has a default specification. \l{Qt for Embedded Linux} will + use the default specification for the current platform unless told + otherwise. To override this behavior, you can use the \c configure + script's \c -platform option to change the specification for the host + platform (where compilation will take place). + + The \c configure script's \c -xplatform option is used to provide a + specification for the target architecture (where the library will be + deployed). + + For example, to cross-compile an application to run on a device with + an ARM architecture, using the GCC toolchain, run the configure + script at the command line in the following way: + + \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 1 + + If neither of the provided specifications fits your target device, + you can create your own. To create a custom \c qmake.conf file, + just copy and customize an already existing file. For example: + + \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 2 + + \note When defining a mkspec for a Linux target, the directory must + be prefixed with "linux-". We recommend that you copy the entire + directory. + + Note also that when providing you own qmake specifcation, you must + use the \c configure script's \c -xplatform option to make + \l{Qt for Embedded Linux} aware of the custom \c qmake.conf file. + + \section1 Step 3: Provide Architecture Specific Files + + Starting with Qt 4, all of Qt's implicitly shared classes can + safely be copied across threads like any other value classes, + i.e., they are fully reentrant. This is accomplished by + implementing reference counting operations using atomic hardware + instructions on all the different platforms supported by Qt. + + To support a new architecture, it is important to ensure that + these platform-specific atomic operations are implemented in a + corresponding header file (\c qatomic_ARCH.h), and that this file + is located in Qt's \c src/corelib/arch directory. For example, the + Intel 80386 implementation is located in \c + src/corelib/arch/qatomic_i386.h. + + See the \l {Implementing Atomic Operations} documentation for + details. + + \section1 Step 4: Provide Hardware Drivers + + Without the proper mouse and keyboard drivers, you will not be + able to give any input to your application when it is installed on + the target device. You must also ensure that the appropriate + screen driver is present to make the server process able to put + the application's widgets on screen. + + \l{Qt for Embedded Linux} provides several ready-made mouse, keyboard and + screen drivers, see the \l{Qt for Embedded Linux Pointer Handling}{pointer + handling}, \l{Qt for Embedded Linux Character Input}{character input} and + \l{Qt for Embedded Linux Display Management}{display management} + documentation for details. + + In addition, custom drivers can be added by deriving from the + QWSMouseHandler, QWSKeyboardHandler and QScreen classes + respectively, and by creating corresponding plugins to make use of + Qt's plugin mechanism (dynamically loading the drivers into the + server application at runtime). Note that the plugins must be + located in a location where Qt will look for plugins, e.g., the + standard \c plugin directory. + + See the \l {How to Create Qt Plugins} documentation and the \l + {tools/plugandpaint}{Plug & Paint} example for details. + + \section1 Step 5: Build the Target Specific Executable + + Before building the executable, you must specify the target + architecture as well as the target specific hardware drivers by + running the \c configure script: + + \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 3 + + It is also important to make sure that all the third party + libraries that the application and the Qt libraries require, are + present in the tool chain. In particular, if the zlib and jpeg + libraries are not available, they must be included by running the + \c configure script with the \c -L and \c -I options. For example: + + \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 4 + + The JPEG source can be downloaded from \l http://www.ijg.org/. The + \l{Qt for Embedded Linux} distribution includes a version of the zlib source + that can be compiled into the Qt for Embedded Linux library. If integrators + wish to use a later version of the zlib library, it can be + downloaded from the \l http://www.gzip.org/zlib/ website. + + Then build the executable: + + \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 5 + + That's all. Your target specific executable is ready for deployment. + + \table 100% + \row + \o \bold {See also:} + + \l{Qt for Embedded Linux Architecture} and \l{Deploying Qt for Embedded Linux + Applications}. + \endtable +*/ diff --git a/doc/src/platforms/emb-deployment.qdoc b/doc/src/platforms/emb-deployment.qdoc new file mode 100644 index 0000000..a6fb978 --- /dev/null +++ b/doc/src/platforms/emb-deployment.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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 qt-embedded-deployment.html + + \title Deploying Qt for Embedded Linux Applications + \ingroup qt-embedded-linux + + The procedure of deploying an Qt application on \l{Qt for Embedded Linux} + is essentially the same as the deployment procedure on X11 platforms + which is described in detail in the \l {Deploying an Application + on X11 Platforms} documentation. See also the \l {Deploying Qt + applications}{general remarks} about deploying Qt applications. + + In addition, there is a couple of Qt for Embedded Linux specific issues to + keep in mind: + + \tableofcontents + + \section1 Fonts + + When Qt for Embedded Linux applications run, they look for a file called + \c fontdir in Qt's \c /lib/fonts/ directory defining the + fonts that are available to the application (i.e. the fonts + located in the mentioned directory). + + For that reason, the preferred fonts must be copied to the \c + /lib/fonts/ directory, and the \c fontdir file must be customized + accordingly. See the \l {Qt for Embedded Linux Fonts}{fonts} documentation + for more details about the supported font formats. + + Note that the application will look for the \c /lib/fonts/ + directory relative to the path set using the \c -prefix parameter + when running the \c configure script; ensure that this is a + sensible path in the target device environment. See the \l + {Installing Qt for Embedded Linux#Step 3: Building the + Library}{installation} documentation for more details. + + \section1 Environment Variables + + In general, any variable value that differs from the provided + default values must be set explicitly in the target device + environment. Typically, these include the QWS_MOUSE_PROTO, + QWS_KEYBOARD and QWS_DISPLAY variables specifying the drivers for + pointer handling, character input and display management, + respectively. + + For example, without the proper mouse and keyboard drivers, there + is no way to give any input to the application when it is + installed on the target device. By running the \c configure script + using the \c -qt-kbd-<keyboarddriver> and \c + -qt-mouse-<mousedriver> options, the drivers are enabled, but in + addition the drivers and the preferred devices must be specified + as the ones to use in the target environment, by setting the + environment variables. + + See the \l{Qt for Embedded Linux Pointer Handling}{pointer handling}, + \l{Qt for Embedded Linux Character Input}{character input} and + \l{Qt for Embedded Linux Display Management}{display management} + documentation for more information. + + \section1 Framebuffer Support + + No particular actions are required to enable the framebuffer on + target devices: The Linux framebuffer is enabled by default on all + modern Linux distributions. For information on older versions, see + \l http://en.tldp.org/HOWTO/Framebuffer-HOWTO.html. + + To test that the Linux framebuffer is set up correctly, and that + the device permissions are correct, use the program provided by + the \l {Testing the Linux Framebuffer} document. +*/ diff --git a/doc/src/platforms/emb-differences.qdoc b/doc/src/platforms/emb-differences.qdoc new file mode 100644 index 0000000..cf3ab75 --- /dev/null +++ b/doc/src/platforms/emb-differences.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** 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 qt-embedded-differences.html + + \title Porting Qt Applications to Qt for Embedded Linux + \ingroup porting + \ingroup qt-embedded-linux + + Existing Qt applications should require no porting provided there is no + platform dependent code. + + \table 100% + \header \o Platform Dependent Code + + \row + \o + Platform dependent code includes system calls, calls to the + underlying window system (Windows or X11), and Qt platform + specific methods such as QApplication::x11EventFilter(). + + For cases where it is necessary to use platform dependent code + there are macros defined that can be used to enable and disable + code for each platform using \c #ifdef directives: + + \list + \o Qt for Embedded Linux: Q_WS_QWS + \o Qt for Mac OS X: Q_WS_MAC + \o Qt for Windows: Q_WS_WIN + \o Qt for X11: Q_WS_X11 + \endlist + \endtable +*/ diff --git a/doc/src/platforms/emb-displaymanagement.qdoc b/doc/src/platforms/emb-displaymanagement.qdoc new file mode 100644 index 0000000..09ea7c2 --- /dev/null +++ b/doc/src/platforms/emb-displaymanagement.qdoc @@ -0,0 +1,205 @@ +/**************************************************************************** +** +** 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 qt-embedded-displaymanagement.html + + \title Qt for Embedded Linux Display Management + \ingroup qt-embedded-linux + + When rendering, the default behavior for each Qt for Embedded Linux + client is to render its widgets into memory, while the server is + responsible for putting the contents of the memory onto the + screen. The server uses the screen driver to copy the content of + the memory to the display. + + The screen driver is loaded by the server application when it + starts running, using Qt's \l {How to Create Qt Plugins}{plugin + system}. + + Contents: + + \tableofcontents + + \section1 Available Drivers + + \l{Qt for Embedded Linux} provides drivers for the Linux framebuffer, the + virtual framebuffer, transformed screens, VNC servers and multi + screens. Run the \c configure script to list the available + drivers: + + \if defined(QTOPIA_DOCS) + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 0 + \else + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 1 + \endif + + \if defined(QTOPIA_DOCS) + In the default Qt Extended configuration, only an unaccelerated Linux + framebuffer driver (\c /dev/fb0) is enabled. The various drivers + can be enabled and disabled using the \c configure script. For + example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 2 + \else + In the default Qt configuration, only an unaccelerated Linux + framebuffer driver (\c /dev/fb0) is enabled. The various drivers + can be enabled and disabled using the \c configure script. For + example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 3 + \endif + + Custom screen drivers can be implemented by subclassing the + QScreen class and creating a screen driver plugin (derived from + the QScreenDriverPlugin class). The default implementation + of the QScreenDriverFactory class will automatically detect the + plugin, loading the driver into the server application at run-time. + + \section1 Specifying a Driver + + To specify which driver to use, set the QWS_DISPLAY environment + variable. For example (if the current shell is bash, ksh, zsh or + sh): + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 4 + + The valid values for the \c <driver> argument are \c LinuxFb, \c + QVFb, \c VNC, \c Transformed, \c Multi and \l + {QScreenDriverPlugin::keys()}{keys} identifying custom drivers, + and the \c {<display num>} argument is used to separate screens + that are using the same screen driver and to enable multiple + displays (see the \l {Running Qt for Embedded Linux Applications} + documentation for more details). The driver specific options are + described in the table below. + + \table + \header + \o Driver Specific Option \o Available For \o Description + \row + \o \c tty=<device> + \o LinuxFb + \o Passes the device file to the console the application is + running on. + \row + \o \c nographicsmodeswitch + \o LinuxFb + \o Ensures that the application is not in graphics mode. + \row + \o \c littleendian + \o LinuxFb + \o Tells the driver it must handle a little-endian frame + buffer in a big-endian system. + \row + \o \c mmWidth=<value> \target mmWidth + \o LinuxFb, QVFb + \o The screen's physical width (used to calculate DPI). + \row + \o \c mmHeight=<value> \target mmHeight + \o LinuxFb, QVFb + \o The screen's physical height (used to calculate DPI). + \row + \o \c <device> + \o LinuxFb + \o + \row + \o \c <subdriver> + \o VNC, Transformed, Multi + \o Specifies a subdriver. + \row + \o \c <RotX> + \o Transformed + \o Specifies the rotation of the screen. The valid values of + \c X are 90, 180 and 270. + \row + \o \c offset=<x,y> + \o Multi + \o Specifies the coordinates of a subscreen's top-left corner + (by default 0,0). + + \endtable + + The QWS_DISPLAY environment variable can also be set using the \c + -display option when running an application. For example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 5 + + \section1 Subdrivers and Multiple Drivers + + The VNC, Transformed and Multi screen drivers depend on + subdrivers. The general syntax for specifying a driver is as + follows: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 6 + + In the case of subdrivers, it is important to add a space between + each subdriver and before the display number to separate the + various drivers and displays. Note that \c Multi screen drivers + can have several subdrivers. For example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 7 + + Note also that the VNC screen driver defaults to a virtual screen + driver if no subdriver is specified. In this case the VNC driver accepts a + few additional (optional) arguments specifying the size and depth + of the default virtual screen: + + \list + \o \c {size=<width x height>} + \o \c {depth=<value>} + \o \c {mmHeight=<physical height in millimeters>} + \o \c {mmWidth=<physical width in millimeters>} + \endlist + + Example running the VNC screen driver with a virtual screen of size + 720x480 with 32 bits per pixel: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 8 + + Example running the VNC screen driver on top of the Linux framebuffer + driver: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 9 + + In this last example, Qt is using two screen drivers simultaneously, + displaying output on both the device's screen and across a network on + VNC client displays. +*/ diff --git a/doc/src/platforms/emb-envvars.qdoc b/doc/src/platforms/emb-envvars.qdoc new file mode 100644 index 0000000..693875f --- /dev/null +++ b/doc/src/platforms/emb-envvars.qdoc @@ -0,0 +1,168 @@ +/**************************************************************************** +** +** 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 qt-embedded-envvars.html + + \title Qt for Embedded Linux Environment Variables + \ingroup qt-embedded-linux + + These environment variables are relevant to \l{Qt for Embedded Linux} + users. + + \table + \header \o Variable \o Description + + \row + \o \bold POINTERCAL_FILE \target POINTERCAL_FILE + + \o Specifies the file containing the data used to calibrate the + pointer device. + + See also QWSCalibratedMouseHandler and \l{Qt for Embedded Linux Pointer + Handling}. + + \row + \o \bold QT_ONSCREEN_PAINT \target QT_ONSCREEN_PAINT + + \o If defined, the application will render its widgets directly on + screen. The affected regions of the screen will not be modified by + the screen driver unless another window with a higher focus + requests (parts of) the same region. + + Setting this environment variable is equivalent to setting the + Qt::WA_PaintOnScreen attribute for all the widgets in the + application. + + See also the Qt for Embedded Linux \l{Qt for Embedded Linux Architecture#Graphics + Rendering}{graphics rendering} documentation. + + \row + \o \bold QWS_SW_CURSOR \target QWS_SW_CURSOR + \o If defined, the software mouse cursor is always used (even when using an + accelerated driver that supports a hardware cursor). + + \row + \o \bold QWS_DISPLAY \target QWS_DISPLAY + \o + + Specifies the display type and framebuffer. For example, if the + current shell is bash, ksh, zsh or sh: + + \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 0 + + The valid values for the \c <driver> argument are \c LinuxFb, \c + QVFb, \c VNC, \c Transformed, \c Multi and \l + {QScreenDriverPlugin::keys()}{keys} identifying custom drivers, + and the \c {<display num>} argument is used to separate screens + that are using the same screen driver and to enable multiple + displays (see the \l {Running Qt for Embedded Linux Applications} + documentation for more details). + + The driver specific options are described in the \l{Qt for Embedded Linux + Display Management}{display management} documentation. + + \row + \o \bold QWS_SIZE \target QWS_SIZE + \o + + Specifies the size of the \l{Qt for Embedded Linux} window which is centered + within the screen. For example, if the current shell is bash, ksh, + zsh or sh: + + \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 1 + + \row + \o \bold QWS_MOUSE_PROTO \target QWS_MOUSE_PROTO + \o + + Specifies the driver for pointer handling. For example, if the + current shell is bash, ksh, zsh or sh: + + \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 2 + + The valid values for the \c <driver> argument are \c MouseMan, \c + IntelliMouse, \c Microsoft, \c VR41xx, \c LinuxTP, \c Yopy. \c + Tslib and \l {QMouseDriverPlugin::keys()}{keys} identifying + custom drivers, and the driver specific options are typically a + device, e.g., \c /dev/mouse for mouse devices and \c /dev/ts for + touch panels. + + Multiple keyboard drivers can be specified in one go: + + \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 3 + + Input will be read from all specified drivers. + Note that the \c Vr41xx driver also accepts two optional + arguments: \c press=<value> defining a mouseclick (the default + value is 750) and \c filter=<value> specifying the length of the + filter used to eliminate noise (the default length is 3). For + example: + + \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 4 + + See also \l {Qt for Embedded Linux Pointer Handling}. + + \row + \o \bold QWS_KEYBOARD \target QWS_KEYBOARD + \o + + Specifies the driver and device for character input. For example, if the + current shell is bash, ksh, zsh or sh: + + \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 5 + + The valid values for the \c <driver> argument are \c SL5000, \c + Yopy, \c VR41xx, \c TTY, \c USB and \l + {QKbdDriverPlugin::keys()}{keys} identifying custom drivers, + and the driver specific options are typically a device, e.g., \c + /dev/tty0. + + Multiple keyboard drivers can be specified in one go: + + \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 6 + + Input will be read from all specified drivers. + + See also \l {Qt for Embedded Linux Character Input}. + + \endtable +*/ diff --git a/doc/src/platforms/emb-features.qdoc b/doc/src/platforms/emb-features.qdoc new file mode 100644 index 0000000..0894079 --- /dev/null +++ b/doc/src/platforms/emb-features.qdoc @@ -0,0 +1,147 @@ +/**************************************************************************** +** +** 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 fine-tuning-features.html + \title Fine-Tuning Features in Qt + \ingroup qtce + \ingroup qt-embedded-linux + \brief Describes how to reduce the size of Qt libraries by selecting only + the features that are needed. + + In many cases, only a fixed set of applications are deployed on an + embedded device, making it possible to save resources by minimizing + the size of the associated libraries. The Qt installation can easily + be optimized by avoiding to compile in the features that are not + required. + + \tableofcontents + + A wide range of features are defined, covering classes and technologies + provided by several of Qt's modules. + You can look up the different feature definitions in the + \c{src/corelib/global/qfeatures.txt} file within the Qt source + distribution. + + \section1 Simple Customization + + \section2 Embedded Linux + + To disable a particular feature, just run the \c configure script + for Qt for Embedded Linux with the \c -no-feature-<feature> option. + For example: + + \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 1 + + The feature can easily be enabled again by running \c configure + with the \c -feature-<feature> option. + + See also \l{Qt Performance Tuning}. + + \section2 Windows CE + + To disable a particular feature, just run the \c configure script + with the set of required \c -D<feature> options. For example, + you can use the \c -D option to define \c{QT_NO_THREAD}: + + \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 0 + + The \c -D option only creates a Qt internal define. If you get linker + errors you have to define \c QT_NO_THREAD also for your project. + You can do this by adding \c DEFINES += \c QT_NO_THREAD to your + \c .pro file. + + See also \l{Qt Performance Tuning}. + + \section1 Managing Large Numbers of Features + + If you want to disable a lot of features, it is more comfortable + to use the \c qconfig tool. + You can disable a \e set of features by creating a custom + configuration file that defines the preferred subset of Qt's + functionality. Such a file uses macros to disable the unwanted + features, and can be created manually or by using the \c qconfig + tool located in the \c{tools/qconfig} directory of the Qt source + distribution. + + \note The \c qconfig tool is intended to be built against Qt on + desktop platforms. + + \bold{Windows CE:} The Qt for Windows CE package contains a \c qconfig + executable that you can run on a Windows desktop to configure the build. + + \image qt-embedded-qconfigtool.png + + The \c qconfig tool's interface displays all of Qt's + functionality, and allows the user to both disable and enable + features. The user can open and edit any custom configuration file + located in the \c{src/corelib/global} directory. When creating a + custom configuration file manually, a description of the currently + available Qt features can be found in the + \c{src/corelib/global/qfeatures.txt} file. + + Note that some features depend on others; disabling any feature + will automatically disable all features depending on it. The + feature dependencies can be explored using the \c qconfig tool, + but they are also described in the \c{src/corelib/global/qfeatures.h} + file. + + To be able to apply the custom configuration, it must be saved in + a file called \c qconfig-myfile.h in the \c{src/corelib/global} + directory. Then use the \c configure tool's \c -qconfig option + and pass the configuration's file name without the \c qconfig- + prefix and \c .h extension, as argument. + The following examples show how this is invoked on each of the + embedded platforms for a file called \c{qconfig-myfile.h}: + + \bold{Embedded Linux:} + + \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 3 + + \bold{Windows CE:} + + \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 2 + + Qt provides several ready-made custom configuration files, + defining minimal, small, medium and large installations, + respectively. These files are located in the + \c{/src/corelib/global} directory in the Qt source distribution. +*/ diff --git a/doc/src/platforms/emb-fonts.qdoc b/doc/src/platforms/emb-fonts.qdoc new file mode 100644 index 0000000..fbc430f --- /dev/null +++ b/doc/src/platforms/emb-fonts.qdoc @@ -0,0 +1,201 @@ +/**************************************************************************** +** +** 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 qt-embedded-fonts.html + + \title Qt for Embedded Linux Fonts + \ingroup qt-embedded-linux + + \l {Qt for Embedded Linux} uses the + \l{http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2} + font engine to produce font output. The formats supported depends on + the locally installed version of the FreeType library. In addition, + \l{Qt for Embedded Linux} supports the Qt Prerendered Font formats (\l QPF and \l QPF2): + light-weight non-scalable font formats specific to \l {Qt for Embedded Linux}. + QPF2 is the native format of \l{Qt for Embedded Linux}. QPF is the legacy + format used by Qt/Embedded 2.x and 3.x. Several of the formats may be rendered + using anti-aliasing for improved readability. + + When \l{Qt for Embedded Linux} applications run, they look for fonts in + Qt's \c lib/fonts/ directory. \l {Qt for Embedded Linux} will automatically detect + prerendered fonts and TrueType fonts. For compatibility, it will also read the + legacy \c lib/fonts/fontdir file. + + Support for other font formats can be added, contact + \l{mailto:qt-info@nokia.com}{qt-info@nokia.com} for more + information. + + \tableofcontents + + \table 100% + \row + \o + \bold {Optimization} + + The \l FreeType, \l QPF2 and \l QPF formats are features that can be + disabled using the + \l{Fine-Tuning Features in Qt}{feature definition system}, + reducing the size of Qt and saving resources. + + Note that at least one font format must be defined. + + See the \l {Fine-Tuning Features in Qt} documentation for + details. + + \o + \inlineimage qt-embedded-fontfeatures.png + \endtable + + All supported fonts use the Unicode character encoding. Most fonts + available today do, but they usually don't contain \e all the + Unicode characters. A complete 16-point Unicode font uses over 1 + MB of memory. + + \target FreeType + \section1 FreeType Formats + + The \l {http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2} + library (and therefore \l{Qt for Embedded Linux}) can support the following font formats: + + \list + \o TrueType (TTF) + \o PostScript Type1 (PFA/PFB) + \o Bitmap Distribution Format (BDF) + \o CID-keyed Type1 + \o Compact Font Format (CFF) + \o OpenType fonts + \o SFNT-based bitmap fonts + \o Portable Compiled Format (PCF) + \o Microsoft Windows Font File Format (Windows FNT) + \o Portable Font Resource (PFR) + \o Type 42 (limited support) + \endlist + + It is possible to add modules to the \l + {http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2} + font engine to support other types of font files. For more + information, see the font engine's own website: \l + http://freetype.sourceforge.net/freetype2/index.html. + + Glyphs rendered using FreeType are shared efficiently between applications, + reducing memory requirements and speeding up text rendering. + + \omit + \l {Qt for Embedded Linux} will by default use the system FreeType library if it exists. + Otherwise it will use a copy of the FreeType library in Qt, which by default only + supports TrueType fonts to reduce footprint. + \endomit + + \target QPF2 + \section1 Qt Prerendered Font (QPF2) + + The Qt Prerendered Font (QPF2) is an architecture-independent, + light-weight and non-scalable font format specific to \l{Qt for Embedded Linux}. + + Nokia provides the cross-platform \l makeqpf tool, included in the + \c tools directory of both \l {Qt} and \l{Qt for Embedded Linux}, which allows + generation of QPF2 files from system fonts. + + QPF2 supports anti-aliasing and complex writing systems, using information + from the corresponding TrueType font, if present on the system. The format + is designed to be mapped directly to memory. The same format is used to + share glyphs from non-prerendered fonts between applications. + + \target QPF + \section1 Legacy Qt Prerendered Font (QPF) + + Nokia provides support for the legacy QPF format for compatibility + reasons. QPF is based on the internal font engine data structure of Qt/Embedded + versions 2 and 3. + + Note that the file name describes the font, for example \c helvetica_120_50.qpf + is 12 point Helvetica while \c helvetica_120_50i.qpf is 12 point Helvetica \e italic. + + \omit + \section1 Memory Requirements + + Taking advantage of the way the QPF format is structured, Qt for + Embedded Linux memory-maps the data rather than reading and parsing it. + This reduces RAM consumption even further. + + Scalable fonts use a larger amount of memory per font, but + these fonts provide a memory saving if many different sizes of each + font are needed. + \endomit + + \section1 The Legacy \c fontdir File + + For compatibility reasons \l{Qt for Embedded Linux} supports the \c fontdir + file, if present. The file defines additional fonts available to the + application, and has the following format: + + \snippet doc/src/snippets/code/doc_src_emb-fonts.qdoc 0 + + \table 100% + \header \o Field \o Description + \row \o \bold name + \o The name of the font format, e.g.,\c Helvetica, \c Times, etc. + \row \o \bold file + \o The name of the file containing the font, e.g., \c + helvR0810.bdf, \c verdana.ttf, etc. + \row \o \bold renderer + \o Specifies the font engine that should be used to render the + font, currently only the FreeType font engine (\c FT) is + supported. + \row \o \bold italic + \o Specifies whether the font is italic or not; the accepted + values are \c y or \c n. + \row \o \bold weight + \o Specifies the font's weight: \c 50 is normal, \c 75 is bold, + etc. + \row \o \bold size + \o Specifies the font size, i.e., point size * 10. For example, a + value of 120 means 12pt. A value of 0 means that the font is + scalable. + \row \o \bold flags + \o The following flag is supported: + \list + \o \c s: smooth (anti-aliased) + \endlist + All other flags are ignored. + \endtable +*/ diff --git a/doc/src/platforms/emb-framebuffer-howto.qdoc b/doc/src/platforms/emb-framebuffer-howto.qdoc new file mode 100644 index 0000000..14400c2 --- /dev/null +++ b/doc/src/platforms/emb-framebuffer-howto.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** 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 qt-embedded-testingframebuffer.html + + \title Testing the Linux Framebuffer + \subtitle for Qt for Embedded Linux + \ingroup qt-embedded-linux + + To test that the Linux framebuffer is set up correctly, and that + the device permissions are correct, use the program found in + \c examples/qws/framebuffer which opens the frame buffer and draws + three squares of different colors. +*/ diff --git a/doc/src/platforms/emb-install.qdoc b/doc/src/platforms/emb-install.qdoc new file mode 100644 index 0000000..73dd4e0 --- /dev/null +++ b/doc/src/platforms/emb-install.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** 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 qt-embedded-install.html + + \title Installing Qt on Embedded Linux + \ingroup qt-embedded-linux + \ingroup installation + \brief How to install Qt on Embedded Linux. + + This document describes how to install \l{Qt for Embedded Linux} in your + development environment: + + \tableofcontents + + Please see the \l{Cross-Compiling Qt for Embedded Linux Applications}{cross + compiling} and \l{Deploying Qt for Embedded Linux Applications}{deployment} + documentation for details on how to install \l{Qt for Embedded Linux} on + your target device. + + Note also that this installation procedure is written for Linux, + and that it may need to be modified for other platforms. + + \section1 Step 1: Installing the License File (commercial editions only) + + If you have the commercial edition of \l{Qt for Embedded Linux}, the first step + is to install your license file as \c $HOME/.qt-license. + + For the open source version you do not need a license file. + + \section1 Step 2: Unpacking the Archive + + First uncompress the archive in the preferred location, then + unpack it: + + \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 0 + + This document assumes that the archive is unpacked in the + following directory: + + \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 1 + + \section1 Step 3: Building the Library + + Before building the \l{Qt for Embedded Linux} library, run the \c + ./configure script to configure the library for your development + architecture. You can list all of the configuration system's + options by typing \c {./configure -help}. + + Note that by default, \l{Qt for Embedded Linux} is configured for + installation in the \c{/usr/local/Trolltech/QtEmbedded-%VERSION%} + directory, but this can be changed by using the \c{-prefix} + option. Alternatively, the \c{-prefix-install} option can be used + to specify a "local" installation within the source directory. + + The configuration system is also designed to allow you to specify + your platform architecture: + + \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 2 + + In general, all Linux systems which have framebuffer support can + use the \c generic architecture. Other typical architectures are + \c x86, \c arm and \c mips. + + \note If you want to build Qt for Embedded Linux for use with a virtual + framebuffer, pass the \c{-qvfb} option to the \c configure + script. + + To create the library and compile all the demos, examples, tools, + and tutorials, type: + + \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 3 + + On some systems the \c make utility is named differently, e.g. \c + gmake. The \c configure script tells you which \c make utility to + use. + + If you did not configure \l{Qt for Embedded Linux} using the \c{-prefix-install} + option, you need to install the library, demos, examples, tools, + and tutorials in the appropriate place. To do this, type: + + \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 4 + + and enter the root password. + + \note You can use the \c INSTALL_ROOT environment variable to specify + the location of the installed files when invoking \c{make install}. + + \section1 Step 4: Adjusting the Environment Variables + + In order to use \l{Qt for Embedded Linux}, the \c PATH variable must be extended + to locate \c qmake, \c moc and other \l{Qt for Embedded Linux} tools, and the \c + LD_LIBRARY_PATH must be extended for compilers that do not support + \c rpath. + + To set the \c PATH variable, add the following lines to your \c + .profile file if your shell is bash, ksh, zsh or sh: + + \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 5 + + In case your shell is csh or tcsh, add the following line to the + \c .login file instead: + + \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 6 + + If you use a different shell, please modify your environment + variables accordingly. + + For compilers that do not support \c rpath you must also extend + the \c LD_LIBRARY_PATH environment variable to include + \c /usr/local/Trolltech/QtEmbedded-%VERSION%/lib. Note that on Linux + with GCC, this step is not needed. + + \section1 Step 5: Building the Virtual Framebuffer + + For development and debugging, \l{Qt for Embedded Linux} provides a virtual + framebuffer as well as the option of running \l{Qt for Embedded Linux} as a VNC + server. For a description of how to install the virtual + framebuffer and how to use the VNC protocol, please consult the + documentation at: + + \list + \o \l {The Virtual Framebuffer} + \o \l {The VNC Protocol and Qt for Embedded Linux} + \endlist + + Note that the virtual framebuffer requires a Qt for X11 + installation. See \l {Installing Qt on X11 Platforms} for details. + + The Linux framebuffer, on the other hand, is enabled by default on + all modern Linux distributions. For information on older versions, + see \l http://en.tldp.org/HOWTO/Framebuffer-HOWTO.html. To test + that the Linux framebuffer is set up correctly, use the program + provided by the \l {Testing the Linux Framebuffer} document. + + That's all. \l{Qt for Embedded Linux} is now installed. + + \table 100% + \row + \o + \bold {Customizing the Qt for Embedded Linux Library} + + When building embedded applications on low-powered devices, + reducing the memory and CPU requirements is important. + + A number of options tuning the library's performance are + available. But the most direct way of saving resources is to + fine-tune the set of Qt features that is compiled. It is also + possible to make use of accelerated graphics hardware. + + \list + \o \l {Fine-Tuning Features in Qt} + \o \l {Qt Performance Tuning} + \o \l {Adding an Accelerated Graphics Driver to Qt for Embedded Linux} + \endlist + + \endtable +*/ diff --git a/doc/src/platforms/emb-kmap2qmap.qdoc b/doc/src/platforms/emb-kmap2qmap.qdoc new file mode 100644 index 0000000..291a553 --- /dev/null +++ b/doc/src/platforms/emb-kmap2qmap.qdoc @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** 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 qt-embedded-kmap2qmap.html + \title kmap2qmap + \ingroup qt-embedded-linux + + \c kmap2qmap is a tool to generate keymaps for use on Embedded Linux. + The source files have to be in standard Linux \c kmap format that is + e.g. understood by the kernel's \c loadkeys command. This means you + can use the following sources to generate \c qmap files: + + \list + \o The \l {http://lct.sourceforge.net/}{Linux Console Tools (LCT)} project. + \o \l {http://www.x.org/}{Xorg} X11 keymaps can be converted to the \c + kmap format with the \c ckbcomp utility. + \o Since \c kmap files are plain text files, they can also be hand crafted. + \endlist + + The generated \c qmap files are size optimized binary files. + + \c kmap2qmap is a command line program, that needs at least 2 files as + parameters. The last one will be the generated \c .qmap file, while all + the others will be parsed as input \c .kmap files. For example: + + \code + kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap + \endcode + + \c kmap2qmap does not support all the (pseudo) symbols that the Linux + kernel supports. If you are converting a standard keymap you will get a + lot of warnings for things like \c Show_Registers, \c Hex_A, etc.: you + can safely ignore those. + + It also doesn't support numeric symbols (e.g. \c{keycode 1 = 4242}, + instead of \c{keycode 1 = colon}), since these are deprecated and can + change from one kernel version to the other. + + On the other hand, \c kmap2qmap supports one additional, Qt specific, + symbol: \c QtZap. The built-in US keymap has that symbol mapped tp + \c{Ctrl+Alt+Backspace} and it serves as a shortcut to kill your QWS + server (similiar to the X11 server). + + See also \l {Qt for Embedded Linux Character Input} +*/ diff --git a/doc/src/platforms/emb-makeqpf.qdoc b/doc/src/platforms/emb-makeqpf.qdoc new file mode 100644 index 0000000..9b3b180 --- /dev/null +++ b/doc/src/platforms/emb-makeqpf.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** 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 qt-embedded-makeqpf.html + \title makeqpf + \ingroup qt-embedded-linux + + \c makeqpf is a tool to generate pre-rendered fonts in QPF2 format for use on Embedded Linux. + + Qt 4 can read files in QPF2 format in addition to QPF files generated by older versions of + \c makeqpf from Qt 2 or 3. + + \sa {Qt for Embedded Linux Fonts} +*/ diff --git a/doc/src/platforms/emb-opengl.qdoc b/doc/src/platforms/emb-opengl.qdoc new file mode 100644 index 0000000..a01fe04 --- /dev/null +++ b/doc/src/platforms/emb-opengl.qdoc @@ -0,0 +1,227 @@ +/**************************************************************************** +** +** 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 qt-embedded-opengl.html + +\title Qt for Embedded Linux and OpenGL +\ingroup qt-embedded-linux + +\section1 Introduction + +\l {http://www.opengl.org}{OpenGL} is an industry standard API for +2D/3D graphics. It provides a powerful, low-level interface between +software and acceleration hardware, and it is operating system and +window system independent. + +\l {http://www.khronos.org/opengles}{OpenGL ES} is a subset +of the \l {http://www.opengl.org}{OpenGL} standard. +Because it is meant for use in embedded systems, it has a smaller, +more constrained API. + +For reference, Nokia provides a plugin which integrates \l +{http://www.khronos.org/opengles}{OpenGL ES} with Qt for Embedded Linux, +but Qt for Embedded Linux can be adapted to a wide range of OpenGL +versions. + +There are three ways to use OpenGL with Qt for Embedded Linux: +\list + \o Perform OpenGL 3D graphics operations in applications; + \o Accelerate normal 2D painting operations; + \o Implement window compositing and special effects. +\endlist + +Qt for Embedded Linux is shipped with a reference integration example +that demonstrates all three uses. + +\section2 Using OpenGL 3D Graphics in Applications + +The \l {QtOpenGL module} offers classes that make it easy to draw 3D +graphics in GUI applications. The module API is cross-platform, so it +is also available on Windows, X11, and Mac OS X. + +To use OpenGL-enabled widgets in a Qt for Embedded Linux application, +all that is required is to subclass the QGLWidget and draw into instances of +the subclass with standard OpenGL functions. + +\section2 Using OpenGL to Accelerate Normal 2D Painting + +Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that +translates QPainter operations into OpenGL calls. This specialized +paint engine can be used to improve 2D rendering performance on +appropriate hardware. It can also overlay controls and decorations +onto 3D scenes drawn using OpenGL. + +\section2 Using OpenGL to Implement Window Compositing and Effects + +Qt for Embedded Linux includes a complete windowing system, which implements +real transparency. The windowing system can be accelerated using +OpenGL to implement top level window compositing. This makes it easy +to add 3D effects to applications, for instance when windows are +minimized or maximized. + +\section1 Acceleration Architecture + +The diagram below shows the Qt for Embedded Linux painting architecture. + +\image qt-embedded-opengl3.png + +A client process widget uses a paint engine to draw into a window +surface. The server then combines the window surfaces and displays the +composition on the screen. This architecture lets you +control the steps of the painting process by subclassing. + +Subclassing QPaintEngine allows you to implement the QPainter API +using accelerated hardware. Subclassing QWindowSurface lets you +decide the properties of the space your widgets will draw themselves +into, as well as which paint engine they should use to draw themselves +into that space. Subclassing QScreen lets you control the creation of +window surfaces and lets you decide how to implement window +compositing. Using subclassing, your implementation work is minimized +since you can reuse base class functionality you don't need to change. + +The elements of an accelerated Qt for Embedded Linux system are shown in the +diagram below. + +\image qt-embedded-opengl1.png + +The applications, using the Qt API, do not depend on the presence of +the acceleration plugin. The plugin uses the graphics hardware to +accelerate painting primitives. Any operations not accelerated by the +plugin are done in software by the software paint engine. + +To integrate an OpenGL implementation into Qt for Embedded Linux for a +particular platform, you use the same mechanisms you would use for +writing any other accelerated driver. Base classes, e.g., QGLScreen +and QWSGLWindowSurface, are provided to minimize the need for +reimplementing common functionality. + +\section1 The Reference Integration + +The \l{OpenGL for Embedded Systems Example} is the reference implementation +for integrating OpenGL ES and \l{http://www.khronos.org/egl/}{EGL} with +the graphics acceleration architecture of Qt for Embedded Linux. +(\l{http://www.khronos.org/egl/}{EGL} is a library that binds OpenGL ES to +native windowing systems.) + +The diagram below shows how OpenGL ES is used within the acceleration architecture: + +\image qt-embedded-opengl2.png + +The example implements a screen driver plugin that demonstrates all +three uses of OpenGL in Qt for Embedded Linux: 2D graphics acceleration, 3D +graphics operations using the \l {QtOpenGL module}, and top-level +window compositing and special effects. The applications still do +not talk directly to the accelerated plugin. + +For 2D graphics, applications use the normal Qt painting API. The example accelerates 2D +painting by using the QOpenGLPaintEngine, which is included in the \l {QtOpenGL module}. + +For 3D graphics applications use the OpenGL API directly, together with the functionality +in the Qt OpenGL support classes. The example supports this by creating a +QWSGLWindowSurface whenever a QGLWidget is instantiated. + +All access to the display is done through OpenGL. The example subclasses +QWSGLWindowSurface implementation and uses the \l +{http://oss.sgi.com/projects/ogl-sample/registry/EXT/framebuffer_object.txt} +{OpenGL Framebuffer Object extension} to draw windows into an offscreen buffer. This +lets the example use OpenGL to implement top level window compositing of opaque and +semi-transparent windows, and to provide a 3D animated transition effect as each new +window is shown. + +The specific OpenGL library being used by the example restricts all +OpenGL operations to occur in a single process. Hence the example +creates instances of QWSGLWindowSurface only in the server process. +Other processes then perform 2D graphics by creating instances +of the standard QWindowSurface classes for client processes. The +standard window surface performs software-based rendering into a +shared memory segment. The server then transfers the contents of this +shared memory into an OpenGL texture before they are drawn onto the +screen during window compositing. + +\omit + +\section1 Future Directions + +\section2 API Improvements + +Nokia is now working on enhancing the API for integrating OpenGL +with Qt for Embedded Linux. The current design plan includes the following +features: + +\list + + \o Provide convenience classes, e.g., QEGLScreen and + QWSEGLWindowSurface, which implement common uses of the EGL + API. These classes will simplify implementing an OpenGL ES + integration. + + \o Extend the screen driver API to provide more control over window + properties and animations, and provide a software-based integration + to enable testing on the desktop. + + \o Improve performance as opportunities arise. + +\endlist + +\section2 OpenVG Support + +\l {http://www.khronos.org/openvg} {OpenVG} is a dedicated API for 2D +graphics on mobile devices. It is therefore more likely to be a better +alternative for 2D acceleration than OpenGL. Until recently, no +OpenVG-capable hardware has been available, so Nokia has not yet +included an OpenVG solution in Qt for Embedded Linux. + +However, Nokia has done a feasibility study, implementing an +OpenVG paint engine on top of a software OpenVG implementation. +Assuming availability of the appropriate hardware, this OpenVG paint +engine can easily be completed and integrated using the existing +acceleration architecture. Since OpenVG shares the same EGL layer as +OpenGL ES, the work already done on the OpenGL integration can be +reused. + +Related technologies included in the \l +{http://www.khronos.org/openkode} {OpenKODE} API set will also be +considered. + +\endomit + +*/ diff --git a/doc/src/platforms/emb-performance.qdoc b/doc/src/platforms/emb-performance.qdoc new file mode 100644 index 0000000..c2b17d1 --- /dev/null +++ b/doc/src/platforms/emb-performance.qdoc @@ -0,0 +1,152 @@ +/**************************************************************************** +** +** 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 qt-performance.html + \title Qt Performance Tuning + \ingroup qtce + \ingroup qt-embedded-linux + \brief Ways to improve performance on embedded platforms. + + When building embedded applications on low-powered devices, + \l{Qt for Windows CE} and \l{Qt for Embedded Linux} provide + a number of options that reduce the memory and/or CPU requirements + by making various trade-offs. These options range from variations + in programming style, to linking and memory allocation. + + Note that the most direct way of saving resources, is to avoid compiling + in features that are not required. See the \l{Fine-Tuning Features in Qt} + {fine tuning features} documentation for details. + + \tableofcontents + + \section1 Programming Style + + Rather than creating dialogs and widgets every time they are + needed, and delete them when they are no longer required, create + them once and use the QWidget::hide() and QWidget::show() + functions whenever appropriate. To avoid a slow startup of the + application, delay the creation of dialogs and widgets until they + are requested. All this will improve the CPU performance, it + requires a little more memory, but will be much faster. + + \section1 Static vs. Dynamic Linking + + A lot of CPU and memory is used by the ELF (Executable and Linking + Format) linking process. Significant savings can be achieved by + using a static build of the application suite; rather than having + a collection of executables which link dynamically to Qt's + libraries, all the applications is built into into a single + executable which is statically linked to Qt's libraries. + + This improves the start-up time and reduces memory usage at the + expense of flexibility (to add a new application, you must + recompile the single executable) and robustness (if one + application has a bug, it might harm other applications). + + \table 100% + \row + \o \bold {Creating a Static Build} + + To compile Qt as a static library, use the \c -static option when + running configure: + + \snippet doc/src/snippets/code/doc_src_emb-performance.qdoc 0 + + To build the application suite as an all-in-one application, + design each application as a stand-alone widget (or set of + widgets) with only minimal code in the \c main() function. Then, + write an application that provides a means of switching between + the applications. The \l Qt Extended platform is an example using this + approach: It can be built either as a set of dynamically linked + executables, or as a single static application. + + Note that the application still should link dynamically against + the standard C library and any other libraries which might be used + by other applications on the target device. + + \endtable + + When installing end-user applications, this approach may not be an + option, but when building a single application suite for a device + with limited CPU power and memory, this option could be very + beneficial. + + \section1 Alternative Memory Allocation + + The libraries shipped with some C++ compilers on some platforms + have poor performance in the built-in "new" and "delete" + operators. Improved memory allocation and performance may be + gained by re-implementing these functions: + + \snippet doc/src/snippets/code/doc_src_emb-performance.qdoc 1 + + The example above shows the necessary code to switch to the plain + C memory allocators. + + \section1 Bypassing the Backing Store + + When rendering, Qt uses the concept of a backing store; i.e., a + paint buffer, to reduce flicker and to support graphics operations + such as blending. + + The default behavior is for each client to render + its widgets into memory while the server is responsible for + putting the contents of the memory onto the screen. But when the + hardware is known and well defined, as is often the case with + software for embedded devices, it might be useful to bypass the + backing store, allowing the clients to manipulate the underlying + hardware directly. + \if defined(qtce) + This is achieved by setting the Qt::WA_PaintOnScreen window attribute + for each widget. + \else + + There are two approaches to direct painting: The first approach is + to set the Qt::WA_PaintOnScreen window attribute for each widget, + the other is to use the QDirectPainter class to reserve a region + of the framebuffer. + For more information, see the + \l{Qt for Embedded Linux Architecture#Direct Painting}{direct painting} + section of the \l{Qt for Embedded Linux Architecture}{architecture} + documentation. + \endif +*/ diff --git a/doc/src/platforms/emb-pointer.qdoc b/doc/src/platforms/emb-pointer.qdoc new file mode 100644 index 0000000..ac5bd80 --- /dev/null +++ b/doc/src/platforms/emb-pointer.qdoc @@ -0,0 +1,209 @@ +/**************************************************************************** +** +** 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 qt-embedded-pointer.html + + \title Qt for Embedded Linux Pointer Handling + \ingroup qt-embedded-linux + + When running a \l{Qt for Embedded Linux} application, it either runs as a + server or connects to an existing server. The mouse driver is + loaded by the server application when it starts running, using + Qt's \l {How to Create Qt Plugins}{plugin system}. + + Internally in the client/server protocol, all system generated + events, including pointer events, are passed to the server + application which then propagates the event to the appropriate + client. Note that pointer handling in \l{Qt for Embedded Linux} works for + both mouse and mouse-like devices such as touch panels and + trackballs. + + Contents: + + \tableofcontents + + \section1 Available Drivers + + \l{Qt for Embedded Linux} provides ready-made drivers for the MouseMan, + IntelliMouse, Microsoft and Linux Touch Panel protocols, for the + standard Linux Input Subsystem as well as the universal touch screen + library, tslib. Run the \c configure script to list the available + drivers: + + \if defined(QTOPIA_PHONE) + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 0 + + \bold{Note:} By default only the PC mouse driver is enabled. + + The various drivers can be enabled and disabled using the \c + configure script. For example: + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 1 + + \else + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 2 + + In the default Qt configuration, only the "pc" mouse driver is + enabled. The various drivers can be enabled and disabled using + the \c configure script. For example: + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 3 + \endif + + Custom mouse drivers can be implemented by subclassing the + QWSMouseHandler class and creating a mouse driver plugin (derived + from the QMouseDriverPlugin class). The default implementation of the + QMouseDriverFactory class will automatically detect the plugin, + loading the driver into the server application at run-time. + + If you are creating a driver for a device that needs calibration + or noise reduction, such as a touchscreen, derive from the + QWSCalibratedMouseHandler subclass instead to take advantage of + its calibration functionality. + + \if defined(QTOPIA_PHONE) + For a tutorial on how to add a new keyboard driver plug-in + see: \l {Tutorial: Implementing a Device Plug-in}. + \endif + + \section1 Specifying a Driver + + Provided that the "pc" mouse driver is enabled, \l{Qt for Embedded Linux} will + try to auto-detect the mouse device if it is one of the supported + types on \c /dev/psaux or one of the \c /dev/ttyS? serial + lines. If multiple mice are detected, all may be used + simultaneously. + + Note that \l{Qt for Embedded Linux} does not support auto-detection of \e + {touch panels} in which case the driver must be specified + explicitly to determine which device to use. + + To manually specify which driver to use, set the QWS_MOUSE_PROTO + environment variable. For example (if the current shell is bash, + ksh, zsh or sh): + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 4 + + The valid values for the \c <driver> argument are \c MouseMan, \c + IntelliMouse, \c Microsoft, \c LinuxTP, \c LinuxInput, \c + Tslib and \l {QMouseDriverPlugin::keys()}{keys} identifying custom + drivers, and the driver specific options are typically a device, + e.g., \c /dev/mouse for mouse devices and \c /dev/ts for touch + panels. + + Multiple mouse drivers can be specified in one go: + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 5 + + Input will be read from all specified drivers. + + \table + \header \o The Tslib Mouse Driver + \row + \o + + The tslib mouse driver inherits the QWSCalibratedMouseHandler + class, providing calibration and noise reduction functionality in + addition to generating mouse events for devices using the + Universal Touch Screen Library. + + To be able to compile this mouse handler, \l{Qt for Embedded Linux} must be + configured with the \c -qt-mouse-tslib option as described + above. In addition, the tslib headers and library must be present + in the build environment. + + The tslib sources can be downloaded from \l + http://tslib.berlios.de. Use the \c configure script's -L and + -I options to explicitly specify the location of the library and + its headers: + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 7 + + In order to use this mouse driver, tslib must also be correctly + installed on the target machine. This includes providing a \c + ts.conf configuration file and setting the neccessary environment + variables (see the README file provided with tslib for details). + + The \c ts.conf file will usually contain the following two lines: + + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 8 + + To make \l{Qt for Embedded Linux} explicitly choose the tslib mouse + handler, set the QWS_MOUSE_PROTO environment variable as explained + above. + + \endtable + + \section1 Troubleshooting + + \section2 Device Files + + Make sure you are using the correct device file. + + As a first step, you can test whether the device file actually gives any + output. For instance, if you have specified the mouse driver with + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 9 + then try examining + the output from the device by entering the following command in a console: + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 10 + + If you see output from the device printed on the console when you move + the mouse, you are probably using the correct device file; otherwise, you + will need to experiment to find the correct device file. + + \section2 File Permissions + + Make sure you have sufficient permissions to access the device file. + + The Qt for Embedded Linux server process needs at least read permission for the + device file. Some drivers also require write access to the device file. + For instance, if you have specified the mouse driver with + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 11 + then examine the permissions of the device file by entering the following + command in a console: + \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 12 + + If the device file is actually a symbolic link to another file, you must + change the permissions of the actual file instead. +*/ diff --git a/doc/src/platforms/emb-porting.qdoc b/doc/src/platforms/emb-porting.qdoc new file mode 100644 index 0000000..978edb3 --- /dev/null +++ b/doc/src/platforms/emb-porting.qdoc @@ -0,0 +1,193 @@ +/**************************************************************************** +** +** 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 qt-embedded-porting-operatingsystem.html + + \title Porting Qt for Embedded Linux to Another Operating System + \ingroup qt-embedded-linux + + \l{Qt for Embedded Linux} is reasonably platform-independent, making use of + the standard C library and some POSIX functions, but only a Linux + implementation is publically available. If you are looking for a + non-Linux commercial implementation, it is worth contacting \l + {mailto:qt-info@nokia.com}{qt-info@nokia.com} to see if we can + help. + + There are several issues to be aware of if you plan to do your own + port to another operating system. In particular you must resolve + \l{Qt for Embedded Linux}'s shared memory and semaphores (used to share + window regions), and you must provide something similar to + Unix-domain sockets for inter-application communication. You must + also provide a screen driver, and if you want to implement sound + you must provide your own sound server. Finally you must modify + the event dispatcher used by \l{Qt for Embedded Linux}. + + Contents: + + \tableofcontents + + \section1 Shared Memory and Semaphores + + \l{Qt for Embedded Linux} uses System V IPC (shared memory and semaphores) + to share window regions between client and server. When porting, + something similar must be provided; otherwise it will not be + possible to run multiple applications. + + System V semaphores are also used for synchronizing access to the + framebuffer. + + \list + \o Modify \c qsharedmemory_p.cpp + \o Modify \c qlock_qws.cpp + \o Modify \c qwslock.cpp + \endlist + + \section1 Inter-Application Communication + + To communicate between applications, \l{Qt for Embedded Linux} uses the + Unix-domain sockets. When porting, something similar must be + provided; otherwise it will not be possible to run multiple + applications. + + It should be possible to use message queues or similar mechanisms + to achieve this. With the exception of QCOP messages, individual + messages should be no more than a few bytes in length (QCOP + messages are generated by the client applications and not Qt for + Embedded Linux). + + \list + \o Modify \c qwssocket_qws.cpp + \endlist + + \section1 Screen Management + + When rendering, the default behavior in \l{Qt for Embedded Linux} is + for each client to render its widgets into memory while the server is + responsible for putting the contents of the memory onto the screen + using the screen driver. + + When porting, a new screen driver must be implemented, providing a + byte pointer to a memory-mapped framebuffer and information about + width, height and bit depth (the latter information can most + likely be hard-coded). + + \list + \o Reimplement \c qscreen_qws.cpp + \endlist + + \section1 Sound Management + + To implement sound, \l{Qt for Embedded Linux} uses a Linux style device (\c + /dev/dsp). If you want to use the \l{Qt for Embedded Linux} sound server on + another platform you must reimplement it. + + \list + \o Reimplement \c qsoundqss_qws.cpp + \endlist + + \section1 Event Dispatching + + \l{Qt for Embedded Linux} uses an event dispatcher to pass events to and + from the \l{Qt for Embedded Linux} server application. Reimplement the \c + select() function to enable \l{Qt for Embedded Linux} to dispatch events on + your platform. + + \list + \o Modify \c qeventdispatcher_qws.cpp + \endlist +*/ + +/*! + \page qt-embedded-porting-device.html + + \title Porting Qt for Embedded Linux to a New Architecture + \ingroup qt-embedded-linux + + When porting \l{Qt for Embedded Linux} to a new architecture there are + several issues to be aware of: You must provide suitable hardware + drivers, and you must ensure to implement platform dependent + atomic operations to enable multithreading on the new + architecture. + + \section1 Hardware Drivers + + When running a \l{Qt for Embedded Linux} application, it either runs as a + server or connects to an existing server. All system generated + events, including keyboard and mouse events, are passed to the + server application which then propagates the event to the + appropriate client. When rendering, the default behavior is for + each client to render its widgets into memory while the server is + responsible for putting the contents of the memory onto the + screen. + + The various hardware drivers are loaded by the server + application when it starts running, using Qt's \l {How to Create + Qt Plugins}{plugin system}. + + Derive from the QWSMouseHandler, QWSKeyboardHandler and QScreen + classes to create a custom mouse, keyboard and screen driver + respectively. To load the drivers into the server application at + runtime, you must also create corresponding plugins. See the + following documentation for more details: + + \list + \o \l{Qt for Embedded Linux Pointer Handling}{Pointer Handling} + \o \l{Qt for Embedded Linux Character Input}{Character Input} + \o \l{Qt for Embedded Linux Display Management}{Display Management} + \endlist + + \section1 Atomic Operations + + Qt uses an optimization called \l {Implicitly Shared Classes}{implicit sharing} + for many of its value classes; implicitly shared classes can safely be + copied across threads. This technology is implemented using atomic + operations; i.e., \l{Qt for Embedded Linux} requires that platform-specific + atomic operations are implemented to support Linux. + + When porting \l{Qt for Embedded Linux} to a new architecture, it is + important to ensure that the platform-specific atomic operations + are implemented in a corresponding header file, and that this file + is located in Qt's \c src/corelib/arch directory. + + See the \l {Implementing Atomic Operations}{atomic operations} + documentation for more details. +*/ 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. +*/ diff --git a/doc/src/platforms/emb-running.qdoc b/doc/src/platforms/emb-running.qdoc new file mode 100644 index 0000000..67c9283 --- /dev/null +++ b/doc/src/platforms/emb-running.qdoc @@ -0,0 +1,210 @@ +/**************************************************************************** +** +** 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 qt-embedded-running.html + + \title Running Qt for Embedded Linux Applications + \ingroup qt-embedded-linux + + A \l{Qt for Embedded Linux} application requires a server application to be + running, or to be the server application itself. Any \l{Qt for Embedded Linux} + application can be the server application by constructing the QApplication + object with the QApplication::GuiServer type, or by running the application + with the \c -qws command line option. + + Applications can run using both single and multiple displays, and + various command line options are available. + + Note that this document assumes that you either are using the + \l{The Virtual Framebuffer} or that you are running \l{Qt for Embedded Linux} + using the \l {The VNC Protocol and Qt for Embedded Linux}{VNC} protocol, + \e or that you have the Linux framebuffer configured + correctly and that no server process is running. (To test that the + Linux framebuffer is set up correctly, use the program provided by + the \l {Testing the Linux Framebuffer} document.) + + \tableofcontents + + \section1 Using a Single Display + + To run the application using a single display, change to a Linux + console and select an application to run, e.g. \l {Text + Edit}{demos/textedit}. Run the application with the \c -qws + option: + + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 0 + + \table 100% + \row + \o + Provided that the environment variables are adjusted properly + during the \l {Installing Qt for Embedded Linux}{installation process}, you + should see the \l {Text Edit} demo appear. + + It might be that the hardware drivers must be specified explicitly + to make everything work properly. For more information, please + consult the following documentation: + + \list + \o \l{Qt for Embedded Linux Pointer Handling}{Pointer Handling} + \o \l{Qt for Embedded Linux Character Input}{Character Input} + \o \l{Qt for Embedded Linux Display Management}{Display Management} + \endlist + + \o + \inlineimage qt-embedded-runningapplication.png + \endtable + + Additional applications can be run as clients, i.e., by running + these applications \e without the \c -qws option they will connect + to the existing server as clients. You can exit the server + application at any time using \gui{Ctrl+Alt+Backspace}. + + \section1 Using Multiple Displays + + Qt for Embedded Linux also allows multiple displays to be used + simultaneously. There are two ways of achieving this: Either run + multiple Qt for Embedded Linux server processes, or use the + ready-made \c Multi screen driver. + + When running multiple server processes, the screen driver (and + display number) must be specified for each process using the \c + -display command line option or by setting the QWS_DISPLAY + environment variable. For example: + + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 1 + + See the \l {Qt for Embedded Linux Display Management}{display management} + documentation for more details on how to specify a screen + driver. Note that you must also specify the display (i.e., server + process) when starting client applications: + + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 2 + + There is no way of moving a client from one display to another + when running multiple server processes. Using the \c Multi screen + driver, on the other hand, applications can easiliy be moved + between the various screens. + + The \c Multi screen driver can be specified just like any other + screen driver by using the \c -display command line option or by + setting the QWS_DISPLAY environment variable. For example: + + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 3 + + See the \l {Qt for Embedded Linux Display Management}{display management} + documentation for details regarding arguments. + + \section1 Command Line Options + + \table 100% + \header + \o Option \o Description + \row + \o \bold -fn <font> + \o + Defines the application font. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 4 + The font should be specified using an X logical font description. + \row + \o \bold -bg <color> + \o + Sets the default application background color. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 5 + The color-name must be one of the names recognized by the QColor constructor. + \row + \o \bold -btn <color> \o + Sets the default button color. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 6 + The color-name must be one of the names recognized by the QColor constructor. + \row + \o \bold -fg <color> \o + Sets the default application foreground color. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 7 + The color-name must be one of the names recognized by the QColor constructor. + \row + \o \bold -name <objectname> \o + Sets the application name, i.e. the application object's object name. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 8 + \row + \o \bold -title <title> \o + Sets the application's title. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 9 + \row + \o \bold -geometry <width>x<height>+<Xoffset>+<Yoffset> \o + Sets the client geometry of the first window that is shown. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 10 + \row + \o \bold -keyboard \o + Enables the keyboard. + + See also: \l {Qt for Embedded Linux Character Input}. + \row + \o \bold -nokeyboard \o + Disables the keyboard. + \row + \o \bold -mouse \o + Enables the mouse cursor. + + See also: \l {Qt for Embedded Linux Pointer Handling}. + \row + \o \bold -nomouse \o + Disables the mouse cursor. + \row + \o \bold -qws \o + Runs the application as a server application, i.e. constructs a + QApplication object of the QApplication::GuiServer type. + \row + \o \bold -display \o + Specifies the screen driver. + + See also: \l {Qt for Embedded Linux Display Management}. + \row + \o \bold -decoration <style>\o + Sets the application decoration. For example: + \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 11 + The supported styles are \c windows, \c default and \c styled. + + See also QDecoration. + + \endtable +*/ diff --git a/doc/src/platforms/emb-vnc.qdoc b/doc/src/platforms/emb-vnc.qdoc new file mode 100644 index 0000000..1ded45d --- /dev/null +++ b/doc/src/platforms/emb-vnc.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** 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 qt-embedded-vnc.html + \brief A guide to using Qt for Embedded Linux applications as VNC servers + and clients. + + \title The VNC Protocol and Qt for Embedded Linux + \ingroup qt-embedded-linux + + VNC (Virtual Network Computing) software makes it possible to view + and interact with one computer (the "server") from any other + computer or mobile device (the "viewer") anywhere on a network. + + \image qt-embedded-vnc-screen.png + + VNC clients are available for a vast array of display systems, including + X11, Mac OS X and Windows. + + \section1 Configuring Qt with VNC Capabilities + + To run a \l{Qt for Embedded Linux} application using the VNC protocol, the + \l{Qt for Embedded Linux} library must be configured and compiled with the + \c -qt-gfx-vnc option: + + \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc 0 + + \section1 Running a Server Application + + Start a server application by specifying the \c -qws command + line option when running the application. (This can also be + specified in the application's source code.) + Use the \c -display command line option to specify the VNC server's + driver and the virtual screen to use. For example: + + \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc 1 + + The application will act as a VNC server which can be accessed using + an ordinary VNC client, either on the development machine or from a + different machine on a network. + + For example, using the X11 VNC client to view the application from the + same machine: + + \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc 2 + + To interact with the application from another machine on the network, + run a VNC client pointing to the machine that is running the server + application. + + \l{Qt for Embedded Linux} will create a 640 by 480 pixel display by + default. Alternatively, the \c QWS_SIZE environment variable can be + used to set another size; e.g., \c{QWS_SIZE=240x320}. + + \section1 Running Client Applications + + If you want to run more than one application on the same display, you + only need to start the first one as a server application, using the + \c -qws command line option to indicate that it will manage other + windows. + + \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc Starting server + + Subsequent client applications can be started \e without the \c -qws + option, but will each require the same \c -display option and argument + as those used for the server. + + \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc Starting clients + + However, for the clients, this option will not cause a new VNC server + to be started, but only indicates that their windows will appear on the + virtual screen managed by the server application. + + \section1 Related Resources + + It is not always necessary to specify the \c -qws command line option + when running a server application as long as the QApplication object + used by the application has been constructed with the + QApplication::GuiServer flag. + + See the \l{Running Qt for Embedded Linux Applications}{running applications} + documentation for more details about server and client applications. + + \table + \row + \o \bold {The Virtual Framebuffer} + + The \l{The Virtual Framebuffer}{virtual framebuffer} is + an alternative technique recommended for development and debugging + purposes. + + The virtual framebuffer emulates a framebuffer using a shared + memory region and the \c qvfb tool to display the framebuffer in a + window. + + Its use of shared memory makes the virtual framebuffer much faster + and smoother than using the VNC protocol, but it does not operate + over a network. + + \o \inlineimage qt-embedded-virtualframebuffer.png + \endtable +*/ diff --git a/doc/src/platforms/mac-differences.qdoc b/doc/src/platforms/mac-differences.qdoc new file mode 100644 index 0000000..22375e0 --- /dev/null +++ b/doc/src/platforms/mac-differences.qdoc @@ -0,0 +1,339 @@ +/**************************************************************************** +** +** 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 mac-differences.html + \title Qt for Mac OS X - Specific Issues + \brief A description of issues with Qt that are specific to Mac OS X. + \ingroup platform-specific + + This file outlines known issues and possible workarounds when + using Qt on Mac OS X. Contact Qt's technical support team if you find + additional issues which are not covered here. (See also the + document \l{qtmac-as-native.html} {Qt is Mac OS X Native}.) + + \tableofcontents + + \section1 GUI Applications + + Mac OS X handles most applications as "bundles". A bundle is a + directory structure that groups related files together (e.g., + widgets.app/). GUI applications in particular must be run from a + bundle or by using the open(1), because Mac OS X needs the bundle + to dispatch events correctly, as well as for accessing the menu + bar. + + If you are using older versions of GDB you must run with the full + path to the executable. Later versions allow you to pass the + bundle name on the command line. + + \section1 Painting + + Mac OS X always double buffers the screen so the + Qt::WA_PaintOnScreen attribute has no effect. Also it is + impossible to paint outside of a paint event so + Qt::WA_PaintOutsidePaintEvent has no effect either. + + \section1 Library Support + + \section2 Qt libraries as frameworks + + By default, Qt is built as a set of frameworks. Frameworks is the + Mac OS X "preferred" way of distributing libraries. There are + definite advantages to using them. See + \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html} + {Apple's Framework Programming Guide} for more information. + + In general, this shouldn't be an issue because qmake takes care of + the specifics for you. The + \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html} + {Framework Programming Guide} discusses issues to keep in mind + when choosing frameworks over the more typical, dynamic libraries. + However, one point to remember is: \bold {Frameworks always link + with "release" versions of libraries}. + + If you actually want to use a \e{debug} version of a Qt framework, + you must ensure that your application actually loads that debug + version. This is often done by using the DYLD_IMAGE_SUFFIX + environment variables, but that way often doesn't work so well. + Instead, you can temporarily swap your debug and release versions, + which is documented in + \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB} + {Apple's "Debugging Magic" technical note}. + + If you don't want to use frameworks, simply configure Qt with + \c{-no-framework}. + + \section2 Bundle-Based Libraries + + If you want to use some dynamic libraries in your Mac OS X + application bundle (the application directory), create a + subdirectory named "Frameworks" in the application bundle + directory and place your dynamic libraries there. The application + will find a dynamic library if it has the install name + \e{@executable_path/../Frameworks/libname.dylib}. + + If you use \c qmake and Makefiles, use the \c QMAKE_LFLAGS_SONAME setting: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 0 + + Alternatively, you can modify the install name using the + install_name_tool(1) on the command line. See its manpage for more + information. + + Note that the \c DYLD_LIBRARY_PATH environment variable will + override these settings, and any other default paths, such as a + lookup of dynamic libraries inside \c /usr/lib and similar default + locations. + + \section2 Combining Libraries + + If you want to build a new dynamic library combining the Qt 4 + dynamic libraries, you need to introduce the \c{ld -r} flag. Then + relocation information is stored in the output file, so that + this file could be the subject of another \c ld run. This is done + by setting the \c -r flag in the \c .pro file, and the \c LFLAGS + settings. + + \section2 Initialization Order + + dyld(1) calls global static initializers in the order they are + linked into your application. If a library links against Qt and + references globals in Qt (from global initializers in your own + library), be sure to link your application against Qt before + linking it against the library. Otherwise the result will be + undefined because Qt's global initializers have not been called + yet. + + \section1 Compile-Time Flags + + The follewing flags are helpful when you want to define Mac OS X specific + code: + + \list + + \o Q_OS_DARWIN is defined when Qt detects you are on a + Darwin-based system (including the Open Source version) + + \o Q_WS_MAC is defined when the Mac OS X GUI is present. + + \o QT_MAC_USE_COCOA is defined when Qt is built to use the Cocoa framework. + If it is not present, then Qt is using Carbon. + + \endlist + + A additional flag, Q_OS_MAC, is defined as a convenience whenever + Q_OS_DARWIN is defined. + + If you want to define code for specific versions of Mac OS X, use + the availability macros defined in /usr/include/AvailabilityMacros.h. + + See QSysInfo for information on runtime version checking. + + \section1 Mac OS X Native API Access + + \section2 Accessing the Bundle Path + + The Mac OS X application is actually a directory (ending with \c + .app). This directory contains sub-directories and files. It may + be useful to place items (e.g. plugins, online-documentation, + etc.) inside this bundle. You might then want to find out where + the bundle resides on the disk. The following code returns the + path of the application bundle: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 1 + + Note: When OS X is set to use Japanese, a bug causes this sequence + to fail and return an empty string. Therefore, always test the + returned string. + + For more information about using the CFBundle API, see + \l{http://developer.apple.com/documentation/CoreFoundation/Reference/CFBundleRef/index.html} + {Apple's Developer Website}. + + \section2 Translating the Application Menu and Native Dialogs + + The items in the Application Menu will be merged correctly for + your localized application, but they will not show up translated + until you + \l{http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/Concepts/BundleAnatomy.html#//apple_ref/doc/uid/20001119-105003-BAJFDAAG} + {add a localized resource folder} to the application bundle. + The main thing you need to do is create a file called + locversion.plist. Here is an example for Norwegian: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 2 + + Now when you run the application with your preferred language set + to Norwegian, you should see menu items like "Avslutt" instead of + "Quit". + + \section1 User Interface + + \section2 Right-Mouse Clicks + + If you want to provide right-mouse click support for Mac OS X, use + the QContextMenuEvent class. This will map to a context menu + event, i.e., a menu that will display a pop-up selection. This is + the most common use of right-mouse clicks, and maps to a + control-click with the Mac OS X one-button mouse support. + + \section2 Menu Bar + + Qt will automatically detect your menu bars for you and turn + them into Mac native menu bars. Fitting this into your existing Qt + application will normally be automatic. However, if you have + special needs, the Qt implementation currently selects a menu + bar by starting at the active window + (i.e. QApplication::activeWindow()) and applying the following + tests: + + \list 1 + + \i If the window has a QMenuBar, then it is used. + + \i If the window is modal, then its menu bar is used. If no menu + bar is specified, then a default menu bar is used (as + documented below). + + \i If the window has no parent, then the default menu bar is used + (as documented below). + + \endlist + + These tests are followed all the way up the parent window chain + until one of the above rules is satisifed. If all else fails, a + default menu bar will be created. Note the default menu bar on + Qt is an empty menu bar. However, you can create a different + default menu bar by creating a parentless QMenuBar. The first one + created will be designated the default menu bar and will be used + whenever a default menu bar is needed. + + Note that using native menu bars introduces certain limitations on + Qt classes. See the \l{#Limitations}{list of limitations} below + for more information about these. + + \section2 Special Keys + + To provide the expected behavior for Qt applications on Mac OS X, + the Qt::Meta, Qt::MetaModifier, and Qt::META enum values + correspond to the Control keys on the standard Macintosh keyboard, + and the Qt::Control, Qt::ControlModifier, and Qt::CTRL enum values + correspond to the Command keys. + + \section1 Limitations + + \section2 Menu Actions + + \list + + \o Actions in a QMenu with accelerators that have more than one + keystroke (QKeySequence) will not display correctly, when the + QMenu is translated into a Mac native menu bar. The first key + will be displayed. However, the shortcut will still be + activated as on all other platforms. + + \o QMenu objects used in the native menu bar are not able to + handle Qt events via the normal event handlers. + For Carbon, you will have to install a Carbon event handler on + the menu bar in order to receive Carbon events that are similar + to \l{QMenu::}{showEvent()}, \l{QMenu::}{hideEvent()}, and + \l{QMenu::}{mouseMoveEvent()}. For Cocoa, you will have to + install a delegate on the menu itself to be notified of these + changes. Alternatively, consider using the QMenu::aboutToShow() + and QMenu::aboutToHide() signals to keep track of menu visibility; + these provide a solution that should work on all platforms + supported by Qt. + + \endlist + + \section2 Native Widgets + + Qt has support for sheets and drawers, represented in the + window flags by Qt::Sheet and Qt::Drawer respectiviely. Brushed + metal windows can also be created by using the + Qt::WA_MacMetalStyle window attribute. + +*/ + +/*! + \page qt-mac-cocoa-licensing.html + + \title Contributions to the Following QtGui Files: qapplication_cocoa_p.h, qapplication_mac.mm, qdesktopwidget_mac.mm qeventdispatcher_mac.mm qeventdispatcher_mac_p.h qmacincludes_mac.h qt_cocoa_helpers.mm qt_cocoa_helpers_p.h qwidget_mac.mm qsystemtrayicon_mac.mm + + \contentspage {Other Licenses Used in Qt}{Contents} + + \ingroup licensing + \brief License information for contributions by Apple, Inc. to specific parts of the Qt/Mac Cocoa port. + + \legalese + + Copyright (C) 2007-2008, Apple, Inc. + + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + \list + \o Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + \o Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + \o Neither the name of Apple, Inc. nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + \endlist + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + \endlegalese +*/ diff --git a/doc/src/platforms/platform-notes-rtos.qdoc b/doc/src/platforms/platform-notes-rtos.qdoc new file mode 100644 index 0000000..4fef2f5 --- /dev/null +++ b/doc/src/platforms/platform-notes-rtos.qdoc @@ -0,0 +1,220 @@ +/*! + \page platform-notes-vxworks.html + \title Platform Notes - VxWorks + \contentspage Platform Notes + \target VxWorks + + \note VxWorks is a community supported platform. See the + \l{Supported Platforms} page for more information. + + This page contains information about the Qt for VxWorks port. More + information about the combinations of platforms and compilers supported + by Qt can be found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 Supported Versions + + Qt has been tested on WindRiver VxWorks 6.7 in kernel mode using the + vendor supplied GCC compiler, targetting both the x86 simulator + (simpentium) and Power-PC devices (ppc). + VxWorks' RTP mode is currently not supported. + + \section1 Limitations + + The VxWorks kernel has an optional POSIX compatibility layer, but this + layer does not implement all POSIX functionality needed for a complete + Qt port. + + \table + \header \o Function \o Notes + \row \o QProcess + \o Not available - VxWorks has no concept of processes. + \row \o QSharedMemory + \o Not available - VxWorks has only a global, flat address space. + \row \o QSystemSemaphore + \o Not available - VxWorks has no concept of processes. + \row \o QLibrary + \o QLibrary is only a small stub to make it possible to build + static plugins. + \row \o QCoreApplication + \o Can only be instantiated once. Qt's Q(CoreE)Application is + tightly coupled to one address space and process, while VxWorks + only supports one global address space and has no concept of + processes. + \row \o Phonon + \o There is no standard audio backend, which could be integrated into Phonon. + \row \o Qt3Support + \o The Qt3Support library is not available on VxWorks. + + \endtable + + \section1 Build Instructions + + Qt for VxWorks needs to be \l{Cross-Compiling Qt for Embedded Linux + Applications}{cross-compiled} on a Linux host. \c configure and \c make + the build like you would with a standard \l{Cross-Compiling Qt for + Embedded Linux Applications}{embedded Linux cross build}. Building the + VxWorks simulator would be done like this: + + \code + <path/to/qt/sources>/configure -xplatform unsupported/vxworks-simpentium-g++ -embedded vxworks -exceptions -no-gfx-linuxfb -no-mouse-linuxtp -no-mouse-pc -no-kbd-tty + make + \endcode + + \list + \o \c{-xplatform unsupported/qws/vxworks-simpentium-g++} - selects the x86 simulator mkspec for VxWorks + \o \c{-embedded vxworks} - builds the embedded version of Qt and sets the architecture to VxWorks + \o \c{-exceptions} - see General Notes below + \o \c{-no-gfx-linuxfb}, \c{-no-mouse-linuxtp}, \c{-no-mouse-pc} and \c{-no-kbd-tty} are Linux specific and won't work on VxWorks + \endlist + + \section1 General Notes + + \list + + \o Configuring with \c{-exceptions} is necessary, because the VxWorks + 6.7 g++ headers require exceptions to be enabled when compiling C++ + code. + + \o Configure's \c{-xplatform} can be any of + \c{unsupported/vxworks-(simpentium|ppc)-(g++|dcc)}, but \c{dcc} + (WindRiver DIAB compiler) has not yet tested been tested with Qt 4.6 and + VxWorks 6.7. + + \o Building shared libraries with \c{-shared} (the default) doesn't + really build shared libraries, like e.g. on Linux, since these are not + supported by VxWorks. Instead, qmake will created partially linked + objects, that can be loaded at runtime with \c{ld}. + + \o Creating static builds with \c{-static} is fully supported. + + \o "Munching" (generating constructors/destructors for static C++ + objects) is done automatically by a special qmake extension (for both + shared libraries and executables) + + \o VxWorks does not have a file system layer, but the low level storage + drivers have to supply a file system like interface to the applications. + Since each driver implements a different subset of the functionality + supported by this interface, Qt's file system auto-tests show wildly + differing results running on different "file systems". The best results + can be achieved when running on a (writable) NFS mount, since that + provides the most Unix-ish interface. The worst results come from the + FTP file system driver, which may crash when accessed by a + \c{QFileInfo}. + + \o Keep in mind that VxWorks doesn't call your \c{main()} function with + the standard \c{argc}/\c{argv} parameters. So either add a special + \c{vxmain()} function or use a tool like \c{callmain} to translate + VxWorks' commandline arguments to an \c{argc}/\c{argv} array. + + \o Some example will fail to build, due to some missing dependencies + (e.g. shared memory) - this will be fixed in a later release. + + \endlist +*/ + +/*! + \page platform-notes-qnx.html + \title Platform Notes - QNX + \contentspage Platform Notes + \target QNX + + \note QNX is a community supported platform. See the + \l{Supported Platforms} page for more information. + + This page contains information about the Qt for QNX port. More + information about the combinations of platforms and compilers supported + by Qt can be found on the \l{Supported Platforms} page. + + Note that Qt for QNX is currently based on \l{Qt for Embedded Linux}, which + contains its own windowing system. Mixing QNX's Photon environment with + Qt for QNX is currently not possible. Building Qt for QNX with Photon's + X11 embedded server is not recommended due to missing support for X11 extensions, + resulting in poor rendering quality. + + Qt for QNX contains experimental screen and input drivers based on QNX's + \c devi-hid and \c io-display. For more information, check the class documentation + for QQnxScreen, QWSQnxKeyboardHandler and QQnxMouseHandler. See the + \l{Porting Qt for Embedded Linux to a New Architecture} document for information + on how to add custom screen or input drivers. + + \tableofcontents + + \section1 Supported Versions + + Qt has been tested on QNX 6.4 on i386 and PowerPC targets with QNX's default + gcc compiler. + + \section1 Limitations + + Some of Qt's functionality is currently not available on QNX: + + \table + \header \o Function \o Notes + \row \o QProcess + \o Not available - QNX doesn't support mixing threads and processes. + \row \o QSharedMemory + \o Not available - QNX doesn't support SYSV style shared memory. + \row \o QSystemSemaphore + \o Not available - QNX doesn't support SYSV style system semaphores. + \row \o QWS Multi Process + \o QT_NO_QWS_MULTIPROCESS is always on due to missing shared memory support. + \row \o Phonon + \o There is no standard audio backend, which could be integrated into Phonon. + \row \o Qt3Support + \o The Qt3Support library is not available on QNX. + \endtable + + \section1 Build Instructions + + Qt for QNX needs to be built either on a QNX system, or \l{Cross-Compiling Qt + for Embedded Linux Applications}{cross-compiled} on a Linux host. In either + case, The QNX Software Development Platform must be installed. + + Example configure line for cross-compiling Qt for QNX on a Linux host for an + i386 QNX target: + + \code + configure -xplatform unsupported/qws/qnx-i386-g++ -embedded i386 -no-gfx-linuxfb -no-mouse-linuxtp -no-kbd-tty -no-qt3support -qt-gfx-qnx -qt-mouse-qnx -qt-kbd-qnx -no-exceptions + \endcode + + \list + \o \c{-xplatform unsupported/qws/qnx-i386-g++} - selects the i386-g++ mkspec for QNX + \o \c{-embedded i386} - builds the embedded version of Qt and sets the architecture to i386 + \o \c{-no-gfx-linuxfb}, \c{-no-mouse-linuxtp} and \c{-no-kbd-tty} are Linux specific and won't work on QNX + \o \c{-no-qt3support} - required since the Qt3 support classes are not supported on QNX + \o \c{-no-exceptions} - reduces the size of the library by disabling exception support + \o \c{-qt-gfx-qnx} - enables the experimental \c{io-graphics} based display driver + \o \c{-qt-mouse-qnx} - enables the experimental \c{devi-hig} based mouse driver + \o \c{-qt-kbd-qnx} - enables the experimental \c{devi-hig} based keyboard driver + \endlist + + \section1 General Notes + + \list + \o To enable the experimental QNX display and input drivers, \c{io-display} needs to be + up and running. The \c devi-hid based Qt input drivers require \c devi-hid to run + in resource mode without Photon support. To enable a standard mouse and keyboard + combination, run \c devi-hid as follows: \c{/usr/photon/bin/devi-hid -Pr kbd mouse}. + Note that your current shell will not accept keyboard and mouse input anymore after + running that command, so run it either from a script that launches a Qt application + afterwards, or make sure to have remote login available to launch a Qt application. + In addition, the \c QWS_DISPLAY, \c QWS_MOUSE_PROTO and \c QWS_KEYBOARD environment + variables should all be set to \c{qnx} before running a Qt application. + + \o The 3rd party TIFF library currently doesn't build due to the missing \c inflateSync + symbol from QNX's \c{libz.so.2}. Workarounds would be to manually replace QNX's libz + with a newer version, or disable the TIFF plugin entierly by appending + \c{QT_CONFIG += no-tiff} to \c{.qmake.cache} after configuring Qt. + + \o Some of the tools, examples and demos do not compile due to dependencies on QProcess + or other classes that are not available on QNX. + \endlist + + \section1 Platform Regressions + + Qt for QNX's behavior is mostly identical with \l{Qt for Embedded Linux}. However, + some regressions were spotted in QDateTime computation around year 0 and year 1970, + which have been tracked back to faulty time zone data on some QNX versions. +*/ diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc new file mode 100644 index 0000000..e79b2f4 --- /dev/null +++ b/doc/src/platforms/platform-notes.qdoc @@ -0,0 +1,425 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group platform-specific + \title Platform-Specific Documentation + \brief Documents describing platform-specific features of Qt. + + These documents describe platform-specific features provided by Qt, and + discuss issues related to particular platforms and environments. + + \generatelist{related} +*/ + +/*! + \page platform-notes.html + \ingroup platform-specific + \title Platform Notes + \brief Information about the platforms on which Qt can be used. + + This page contains information about the platforms Qt is currently known + to run on, with links to platform-specific notes, including any known bugs + or incompatibilities. + + \list + \o \l{Platform Notes - X11} + \tableofcontents{1 Platform Notes - X11} + \o \l{Platform Notes - Windows} + \tableofcontents{1 Platform Notes - Windows} + \o \l{Platform Notes - Mac OS X} + \tableofcontents{1 Platform Notes - Mac OS X} + \o \l{Platform Notes - Embedded Linux} + \tableofcontents{1 Platform Notes - Embedded Linux} + \o \l{Platform Notes - Windows CE} + \tableofcontents{1 Platform Notes - Windows CE} + \o \l{Platform Notes - QNX} + \tableofcontents{1 Platform Notes - QNX} + \o \l{Platform Notes - VxWorks} + \tableofcontents{1 Platform Notes - VxWorks} + \endlist + + See also the \l{Compiler Notes} for information about compiler-specific + build issues. Information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. + + If you have anything to add to this list or any of the platform or + compiler-specific pages, please submit it via the \l{Bug Report Form} + or through the \l{Public Qt Repository}. +*/ + +/*! + \page platform-notes-x11.html + \title Platform Notes - X11 + \contentspage Platform Notes + + This page contains information about the X11 platforms Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \target AIX + \section1 AIX - 5.2 + + Qt has been tested on AIX 5.2, using the + \l{Compiler Notes#IBM xlC (AIX)}{xlC} compiler. + + \table + \header \o Compiler \o Notes + \row \o xlC + \o If Qt is built correctly but all symbols are reported to be missing + when you link an application, your makeC++SharedLib script might be out + of date. Make sure you have the latest version from the + \l{http://www-306.ibm.com/software/awdtools/vacpp/support/}{IBM website}. + \row \o GCC + \o We have tested earlier versions of Qt 4 successfully with GCC version + 3.3 and above. Some versions of GCC may fail to link Qt with a "TOC overflow" + message. + Fix this by upgrading to the latest maintenance release of the dynamic + linker. On AIX this is bos.rte.bind_cmds.4.1.5.3 or later. + Some versions of GCC may fail to build Qt with STL and large-file support + enabled, due to + \l{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=9551}{a bug in GCC}. + Fix this by upgrading to the latest maintenance release of the compiler. + It is also possible to work around this problem by running configure with + either \c{-no-stl} or \c{-no-largefile}. + \endtable + + \target FreeBSD + \section1 FreeBSD - 6.0-RELEASE + + \note FreeBSD is a community supported platform. See the + \l{Supported Platforms} page for more information. + + The system compiler on FreeBSD 4.x is gcc 2.95.4, which is not + officially supported by Qt 4. We develop using and recommend + ports/lang/gcc34. You will need to run configure with the + \c{-platform freebsd-g++34} arguments. Optionally, you may use + ports/lang/icc. + + The system compiler on FreeBSD 5.x and 6.x is GCC 3.4.4, which should be + sufficient to build Qt. You do not need to add any special arguments when + running configure. Optionally, you may use ports/lang/icc. + + Note that we do not actively test FreeBSD 4.x and 5.x. Our developers + migrated to 6.x after the Qt 4 launch. FreeBSD-CURRENT is not supported. + + \target HP-UX + \section1 HP-UX + + Qt supports HP-UX on both PA-RISC and the Itanium (IA64) architectures. + + \section2 PA-RISC - B.11.11 or later + + You can configure Qt for aCC in 32 and 64 bit mode (hpux-acc-64 or + hpux-acc-32), or gcc in 32 bit mode (hpux-g++). The default platform is + hpux-acc-32. The minimum required version for aCC (HP ANSI C++) on PA-RISC + is A.03.57. The supported gcc compiler is gcc 3.4.3. + + \section2 Itanium - B.11.23 or later + + You can configure Qt for aCC in 32 and 64 bit mode (hpuxi-acc-64 or + hpuxi-acc-32). gcc is currently unsupported. The default platform is + hpuxi-acc-64. The minimum required version for aCC (HP ANSI C++) on + Itanium is A.06.12. + + \section2 OpenGL Support + + Qt's \l{QtOpenGL}{OpenGL} module requires GLX 1.3 or later to be installed. + This is available for HP-UX 11i - see the + \l{http://docs.hp.com/en/5992-2331/ch04s02.html}{Graphics and Technical Computing Software} + section of the release notes for more information. + + \target IRIX + \section1 IRIX - 6.5.x + + \bold{IRIX is an unsupported platform - please see Qt's online + \l{Platform Support Policy} for details.} + + Unpackaging and IRIX tar: + Because of long filenames some files will be cut off incorrectly with IRIX + tar. Please use GNU tar to unpack Qt packages. + + \section1 Linux + + There are no known problems with using Qt on production versions of + Linux/x86, Linux/ppc, Linux/amd64 and Linux/ia64 (including Altix(R)). + + For the gcc/g++ compiler, please also see the relevant + \l{Compiler Notes#GCC}{compiler page}. + + \section2 Installation problems + + See also the \l{Installation FAQ}. + + If you experience problems when installing new open source versions of Qt + versions, try to use the open source Qt archives (e.g., RPM) + provided by your Linux distribution. If you need to install the source (.tgz) + archive, be aware that you will probably end up with two different + versions of the Qt library installed on your system, which will probably + lead to link errors, like this: + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 0 + Fix this by removing the old version of the library. + + If you have problems installing open source versions of Qt + provided by your Linux distribution (e.g., RPM), please consult the + maintainers of the distribution, not us. + + Some RPM versions have problems installing some of the Qt RPM archives + where installation stops with an error message warning about a + "Failed Dependency". Use the \c{--nodeps} option to \c rpm to workaround + this problem. + + \target Solaris + \section1 Solaris - 9 or later + + \section2 Unpackaging and Solaris tar + + On some Solaris systems, both Solaris tar and GNU tar have been reported + to truncate long filenames. We recommend using star instead + (http://star.berlios.de). + + \section2 CC on Solaris + + Be sure to check our \l{Compiler Notes#Sun Studio}{Forte Developer / Sun Studio} + notes. + + \section2 GCC on Solaris + + Be sure to check the installation notes for \l{GCC on Solaris}. + Do not use GCC with Sun's assembler/linker, this will result in link-time + errors in shared libraries. Use GNU binutils instead. + + GCC 3.2.* is known to miscompile Qt due to an optimizer bug that will + cause the resulting binaries to hang. Please use GCC 3.4.2 or later. +*/ + +/*! + \page platform-notes-windows.html + \title Platform Notes - Windows + \contentspage Platform Notes + + This page contains information about the Windows platforms Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 Windows Vista + + At the time Qt %VERSION% was released, there were no known Vista-specific issues. + + \target Windows NT + \section1 Windows XP, Windows 2000 and Windows NT + + \section2 Installation location + + Installing Qt into a directory with spaces, e.g. C:\\Program Files, may + cause linker errors like the following: + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 2 + + Install Qt into a subdirectory without spaces to avoid this problem. + + \section2 AccelGALAXY graphic card + + When you use a NT 4.0 machine with the driver number + 4,00,1381,1000,021,4.0.0 there is a problem with drag an drop and icons. + The computer freezes, and you have to reset. The problem disappears with + the newest version of the driver, available at + \l{http://www.es.com/}{www.es.com}. + + \section2 Possible GL conflict + + There is a known issue with running Microsoft NetMeeting, Lotus SameTime + and other applications that require screen grabbing while direct + rendering is enabled. Other GL-applications may not work as expected, + unless direct rendering is disabled. +*/ + +/*! + \page platform-notes-mac.html + \title Platform Notes - Mac OS X + \contentspage Platform Notes + + This page contains information about the Mac OS X versions Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 General Information + + Qt 4.4 and Qt 4.5 development is only supported on Mac OS X 10.4 and up. + Applications built against these version of Qt can be deployed on Mac OS X + 10.3, but cannot be developed on that version of the operating system due + to compiler issues. + + Qt 4.3 has been tested to run on Mac OS X 10.3.9 and up. See notes on + the binary package for more information. + + Qt 4.1 has been tested to run on Mac OS X 10.2.8 and up. Qt 4.1.4 is the + last release to work with Mac OS X 10.2. + + \section2 Required GCC version + + Apple's gcc 4 that is shipped with the Xcode Tools for both Mac OS X 10.4 + and 10.5 will compile Qt. There is preliminary support for gcc 4.2 which + is included with Xcode Tools 3.1+ (configurable with + \c{-platform macx-g++42}). + + \section2 Binary Package + + The binary package requires that you have your .qt-license file in your + home directory. Installer.app cannot complete without a valid .qt-license + file. Evaluation users of Qt will have information about how to create + this file in the email they receive. + + The binary package was built on Mac OS X 10.4 with Xcode Tools 2.1 + (gcc 4.0.0) for Qt 4.1.0, Xcode Tools 2.2 (gcc 4.0.1) for Qt 4.1.1-4.1.4 + and Xcode Tools 2.3 for 4.2.0. It will only link executables built + against 10.4 (or a 10.4 SDK). You should be able to run applications + linked against these frameworks on Mac OS X 10.3.9 and Mac OS X 10.4+. + If you require a different configuration, you will have to use the + source package and build with GCC 3.3. + + \section2 Mac OS X on Intel hardware + + Qt 4 fully supports both the Intel and PowerPC architectures on the Mac. + As of Qt 4.1 it is possible to support the Intel architecture by + creating Universal Binaries with qmake. As of Qt 4.1 it is possible to + build Qt as a set of universal binaries and frameworks from configure by + adding these extra flags: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 3 + + If you are building on Intel hardware you can omit the sdk parameter, but + PowerPC hardware requires it. + + You can also generate universal binaries using qmake. Simply add these + lines to your .pro file: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 4 + + \section2 Build Issues + + If Qt does not build upon executing make, and fails with an error message + such as + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 5 + + this could be an indication you have upgraded your version of Mac OS X + (e.g. 10.3 to 10.4), without upgrading your Developer Tools (Xcode Tools). + These must match in order to successfully compile files. + + Please be sure to upgrade both simultaneously. If problems still occur, + contact support. + + \section2 Fink + + If you have installed the Qt for X11 package from \l{Fink}, + it will set the QMAKESPEC environment variable to darwin-g++. This will + cause problems when you build the Qt for Mac OS X package. To fix this, simply + unset your QMAKESPEC or set it to macx-g++ before you run configure. + You need to have a fresh Qt distribution (make confclean). + + \section2 MySQL and Mac OS X + + There seems to be a issue when both -prebind and -multi_module are + defined when linking static C libraries into dynamic library. If you + get the following error message when linking Qt: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 6 + + re-link Qt using -single_module. This is only a problem when building the + MySQL driver into Qt. It does not affect plugins or static builds. + + \section2 Qt and Precompiled Headers (PCH) + + Starting with Qt 3.3.0 it is possible to use precompiled headers. They + are not enabled by default as it appears that some versions of Apple's + GCC and make have problems with this feature. If you want to use + precompiled headers when building the Qt source package, specify the + -pch option to configure. If, while using precompiled headers, you + encounter an internal compile error, try removing the -include header + statement from the compile line and trying again. If this solves the + problem, it probably is a good idea to turn off precompiled headers. + Also, consider filing a bug report with Apple so that they can + improve support for this feature. +*/ + +/*! + \page platform-notes-windows-ce.html + \title Platform Notes - Windows CE + \contentspage Platform Notes + + This page contains information about the Windows CE and Windows Mobile + platforms Qt is currently known to run on, with links to platform-specific + notes. More information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. +*/ + +/*! + \page platform-notes-symbian.html + \title Platform Notes - Symbian + \contentspage Platform Notes + + This page contains information about the Symbian platforms Qt is currently known + to run on. More information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. + + For information about mixing exceptions with symbian leaves, + see \l{Exception Safety with Symbian} +*/ + +/*! + \page platform-notes-embedded-linux.html + \title Platform Notes - Embedded Linux + \contentspage Platform Notes + + This page contains information about the Embedded Linux platforms Qt is + currently known to run on, with links to platform-specific notes. More + information about the combinations of platforms and compilers supported + by Qt can be found on the \l{Supported Platforms} page. +*/ diff --git a/doc/src/platforms/qt-embedded-linux.qdoc b/doc/src/platforms/qt-embedded-linux.qdoc new file mode 100644 index 0000000..0bb2f7d --- /dev/null +++ b/doc/src/platforms/qt-embedded-linux.qdoc @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qws + \title Qt for Embedded Linux Classes + \ingroup groups + \ingroup qt-embedded-linux + \ingroup platform-specific + + \brief Classes that are specific to Qt for Embedded Linux. + + These classes are relevant to \l{Qt for Embedded Linux} users. +*/ + + +/*! + \group qt-embedded-linux + \ingroup qt-embedded + \title Qt for Embedded Linux + \brief Documents specifically about Qt for Embedded Linux. + + Qt for Embedded Linux is a C++ framework for GUI and application development + for embedded devices. It runs on a variety of processors, usually + with Embedded Linux. Qt for Embedded Linux provides the standard Qt API for + embedded devices with a lightweight window system. + + \image qt-embedded-architecture.png + + Qt for Embedded Linux applications write directly to the framebuffer, + eliminating the need for the X Window System and saving memory. + The Linux framebuffer is enabled by default on all modern Linux + distributions. For information on older versions, please refer to + the \l{Framebuffer HOWTO} document. For development + and debugging purposes, Qt for Embedded Linux provides a \l {The + Virtual Framebuffer}{virtual framebuffer}. It is also possible to + run an application using the + \l{The VNC Protocol and Qt for Embedded Linux}{VNC protocol}. + + \table 100% + \header \o Getting Started \o Reference \o Features + \row + \o + \list + \o \l {Qt for Embedded Linux Architecture}{Architecture Overview} + \o \l {Installing Qt for Embedded Linux}{Installation} + \o \l {Running Qt for Embedded Linux Applications}{Running Applications} + \o \l {Qt for Embedded Linux Examples}{Examples} + \endlist + \o + \list + \o \l {Qt for Embedded Linux Classes}{Classes} + \o \l {Qt for Embedded Linux Environment Variables}{Environment Variables} + \o \l {Licenses for Fonts Used in Qt for Embedded Linux}{Font Licenses} + \endlist + \o + \list + \o \l {Qt for Embedded Linux Pointer Handling}{Pointer Handling} + \o \l {Qt for Embedded Linux Character Input}{Character Input} + \o \l {Qt for Embedded Linux Display Management}{Display Management} + \o \l {Qt for Embedded Linux and OpenGL}{OpenGL} + \o \l {Qt for Embedded Linux Fonts}{Fonts} + \endlist + + \header \o Development \o Porting \o Optimization + \row + \o + \list + \o \l {The Virtual Framebuffer}{Virtual Framebuffer} + \o \l {The VNC Protocol and Qt for Embedded Linux}{VNC Protocol} + \o \l {Testing the Linux Framebuffer} + \o \l {Cross Compiling Qt for Embedded Linux Applications}{Cross Compiling Applications} + \o \l {Deploying Qt for Embedded Linux Applications}{Deploying Applications} + \endlist + \o + \list + \o \l {Porting Qt Applications to Qt for Embedded Linux} + \o \l {Porting Qt for Embedded Linux to a New Architecture} + \o \l {Porting Qt for Embedded Linux to Another Operating System} + \endlist + \o + \list + \o \l {Qt Performance Tuning} + \o \l {Fine-Tuning Features in Qt} + \o \l {Adding an Accelerated Graphics Driver to Qt for Embedded Linux}{Adding an Accelerated Graphics Driver} + \endlist + \endtable +*/ diff --git a/doc/src/platforms/qt-embedded.qdoc b/doc/src/platforms/qt-embedded.qdoc new file mode 100644 index 0000000..43a124d --- /dev/null +++ b/doc/src/platforms/qt-embedded.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qt-embedded + \title Qt for Embedded Platforms + \brief Documents related to Qt for Embedded Platforms. + \ingroup platform-specific + + Qt is available for embedded platforms and devices as well as for a number + of desktop platforms. The features provided for each platform depend on the + capabilities and architecture of the operating system. + + Currently, two embedded platforms are supported by Qt: + + \table 90% + \header + \raw HTML + <td style="width: 40%">Embedded Linux</td> + <td style="background: white; width: 5%"></td> + <td style="width: 40%">Windows CE</td> + \endraw + \row \o \l{Qt for Embedded Linux} is designed to be used on Linux devices + without X11 or existing graphical environments. This flavor of + Qt includes a framework for creating both applications and an + environment for them. As a result, it includes features for + window management, inter-process communication and facilities + for handling input and display devices. + \raw HTML + <td style="background: white; width: 5%"></td> + \endraw + \o \l{Qt for Windows CE} is used to create applications running in + existing Windows CE and Windows Mobile environments. + Applications use the appropriate style for the embedded + environment and use native features, such as menus, to conform + to the native style guidelines. + \endtable +*/ diff --git a/doc/src/platforms/qtmac-as-native.qdoc b/doc/src/platforms/qtmac-as-native.qdoc new file mode 100644 index 0000000..97b4c57 --- /dev/null +++ b/doc/src/platforms/qtmac-as-native.qdoc @@ -0,0 +1,202 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/**************************************************************************** +** +** Qt for Mac OS X documentation +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part 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 qtmac-as-native.html + \title Qt is Mac OS X Native + \brief An explanation of Qt's native features on Mac OS X. + \ingroup platform-specific + + This document explains what makes an application native on Mac OS X. + It shows the areas where Qt is compliant, and the grey areas where + compliance is more questionable. (See also the document + \l{mac-differences.html}{Qt for Mac OS X - Specific Issues}.) + + Normally when referring to a native Mac application, one really means an + application that talks directly to the underlying window system, rather + than one that uses some intermediary (for example Apple's X11 server, or a + web browser). Qt applications run as first class citizens, just like + Cocoa, and Carbon applications. In fact, we use Carbon and HIView + internally to communicate with OS X. + + When an application is running as a first class citizen, it means that + it can interact with specific components of the Mac OS X experience: + + \tableofcontents + + \section1 The Global Menu Bar + + Qt does this via the QMenuBar abstraction. Mac users expect to + have a menu bar at the top of the screen and Qt honors this. + + Additionally, users expect certain conventions to be respected, for + example the application menu should contain About, Preferences, + Quit, etc. Qt handles this automatically, although it does not + provide a means of interacting directly with the application menu. + (By doing this automatically, Qt makes it easier to port Qt + applications to other platforms.) + + \section1 Aqua + + This is a critical piece of Mac OS X (documentation can be found at + \l{http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html}). + It is a huge topic, but the most important guidelines for GUI + design are probably these: + + \list + \i \e{Aqua look} + + As with Cocoa/Carbon, Qt provides widgets that look like those + described in the Human Interface Descriptions. Qt's widgets use + Appearance Manager on Mac OS X 10.2 and the new HIThemes on Mac OS X 10.3 + and higher to implement the look, in other words we use Apple's own API's + for doing the rendering. + + \i \e{Aqua feel} + + This is a bit more subjective, but certainly Qt strives to + provide the same feel as any Mac OS X application (and we + consider situations where it doesn't achieve this to be bugs). + Of course Qt has other concerns to bear in mind, especially + remaining cross-platform. Some "baggage" that Qt carries is in + an effort to provide a widget on a platform for which an + equivelant doesn't exist, or so that a single API can be used to + do something, even if the API doesn't make entire sense for a + specific widget. + + \i \e{Aqua guides} + + This is the most subjective, but there are many suggestions and + guidelines in the Aqua style guidelines. This is the area where Qt is + of least assistance. The decisions that must be made to conform (widget + sizes, widget layouts with respect to other widgets, window margins, + placement of OK and Cancel, etc) must be made based on the user + experience demanded by your application. If your user base is small or + mostly comes from the Windows or Unix worlds, these are minor issues much + less important than trying to make a mass market product. Qt for Mac OS X + is fully API compatible with Qt for Windows and X11, but Mac OS X is a + significantly different platform to Windows and some special + considerations must be made based on your audience. + + \endlist + + \section1 Dock + + Interaction with the dock is possible. The icon can be set by calling + QWidget::setWindowIcon() on the main window in your application. The + setWindowIcon() call can be made as often as necessary, providing an + icon that can be easily updated. + \omit + It is also possible to set a QMenu as the dock menu through the use of the + qt_mac_set_dock_menu() function. + \endomit + + \section1 Accessiblity + + Although many users never use this, some users will only interact with your + applications via assistive devices. With Qt the aim is to make this + automatic in your application so that it conforms to accepted practice on + its platform. Qt uses Apple's accessibility framework to provide access + to users with diabilities. + + \section1 Development Tools + + Mac OS X developers expect a certain level of interopability + between their development toolkit and the platform's developer + tools (for example Visual Studio, gmake, etc). Qt supports both Unix + style Makefiles, and ProjectBuilder/Xcode project files by using + the \l qmake tool. For example: + + \snippet doc/src/snippets/code/doc_src_qtmac-as-native.qdoc 0 + + will generate an Xcode project file from project.pro. With \l qmake + you do not have to worry about rules for Qt's preprocessors (\l moc + and \l uic) since \l qmake automatically handles them and ensures that + everything necessary is linked into your application. + + Qt does not entirely interact with the development environment (for + example plugins to set a file to "mocable" from within the Xcode + user interface). Nokia is actively working on improving Qt's + interoperability with various IDEs. +*/ diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc new file mode 100644 index 0000000..8aec1e2 --- /dev/null +++ b/doc/src/platforms/supported-platforms.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** 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 supported-platforms.html + \title Supported Platforms + \brief The platforms supported by Nokia for Qt. + \ingroup platform-specific + + The Qt team strives to provide support for the platforms most + frequently used by Qt users. We have designed our internal testing procedure to + divide platforms into three test categories (Tier 1, Tier 2 and Tier 3) in order + to prioritize internal testing and development resources so that the most + frequently used platforms are subjected to our most rigorous testing processes. + + Qt is supported on a variety of 32-bit and 64-bit platforms, and can + usually be built on each platform with GCC, a vendor-supplied compiler, or + a third party compiler. Although Qt may be built on a range of platform-compiler + combinations, only a subset of these are actively supported by Nokia. + + \tableofcontents + + Information about the specific platforms Qt runs on can be found on the + \l{Platform Notes} page. Information about the compilers used on each platform + can be found on the \l{Compiler Notes} page. + + \section1 Tier 1 Platforms + + All Tier 1 platforms are subjected to our unit test suite and other internal + testing tools on a frequent basis (prior to new version releases, source tree + branching, and at other significant period points in the development process). + Errors or bugs discovered in these platforms are prioritized for correction + by the development team. Significant errors discovered in Tier 1 platforms can + impact release dates and Qt Development Frameworks strives to resolve all known + high priority errors in Tier 1 platforms prior to new version releases. + + \table + \header \o Platform + \o Compilers + \row \o Linux (32 and 64-bit) + \o gcc 4.2 + \row \o Microsoft Windows XP + \o gcc 3.4.2 (MinGW) (32-bit), MSVC 2003, 2005 (32 and 64-bit) + \row \o Microsoft Windows Vista + \o MSVC 2005, 2008 + \row \o Microsoft Windows Vista 64bit + \o MSVC 2008 + \row \o Apple Mac OS X 10.5 "Leopard" x86_64 (Carbon, Cocoa 32 and 64bit) + \o As provided by Apple + \row \o Embedded Linux QWS (ARM) + \o gcc (\l{http:\\www.codesourcery.com}{Codesourcery version)} + \row \o Windows CE 5.0 (ARMv4i, x86, MIPS) + \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii) + \endtable + + \section1 Tier 2 Platforms + + Tier 2 platforms are subjected to our unit test suite and other internal testing + tools prior to release of new product versions. Qt users should note, however, + that errors may be present in released product versions for Tier 2 platforms and, + subject to resource availability, known errors in Tier 2 platforms may or may not + be corrected prior to new version releases. + + \table + \header \o Platform + \o Compilers + \row \o Apple Mac OS X 10.4 "Tiger" + \o As provided by Apple + \row \o HPUXi 11.11 + \o aCC 3.57, gcc 3.4 + \row \o HPUXi 11.23 + \o aCC 6.10 + \row \o Solaris 10 UltraSparc + \o Sun Studio 12 + \row \o AIX 6 + \o Power5 xlC 7 + \row \o Microsoft Windows XP + \o Intel Compiler + \row \o Linux + \o Intel Compiler + \row \o Embedded Linux QWS (Mips, PowerPC) + \o gcc (\l{http:\\www.codesourcery.com}{Codesourcery version)} + \row \o Windows CE 6.0 (ARMv4i, x86, MIPS) + \o MSVC 2008 WinCE 6.0 Professional + \endtable + + \section1 Tier 3 Platforms (Not supported by Nokia) + + All platforms not specifically listed above are not supported by Nokia. Nokia does + not run its unit test suite or perform any other internal tests on platforms not + listed above. Qt users should note, however, that there may be various open source + projects, community users and/or Qt partners who are able to provide assistance with + platforms not supported by Nokia. + + \section1 General Legal Disclaimer + + Please note that Qt is offered on an "as is" basis without warranty + of any kind and that our products are not error or bug free. To the maximum extent + permitted by applicable law, Nokia on behalf of itself and its suppliers, disclaims all + warranties and conditions, either express or implied, including, but not limited to, + implied warranties of merchantability, fitness for a particular purpose, title and + non-infringement with regard to the Licensed Software. +*/ diff --git a/doc/src/platforms/wince-customization.qdoc b/doc/src/platforms/wince-customization.qdoc new file mode 100644 index 0000000..18237a2 --- /dev/null +++ b/doc/src/platforms/wince-customization.qdoc @@ -0,0 +1,264 @@ +/**************************************************************************** +** +** 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 windowsce-customization.html + \ingroup qtce + \title Windows CE - Working with Custom SDKs + \brief How to set up Qt for use with custom Windows CE SDKs. + + When working with a custom SDK for Windows CE, Qt provides an easy way + to add support for it to your development environment. The following is + a tutorial that covers how to create a specification for Qt on Windows + CE platforms. + + \tableofcontents + + \section1 Creating a Custom Build Specification + + Create a subdirectory in the \c mkspecs folder of the Qt directory. + New specifications for Qt for Windows CE following this naming convention: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 0 + + Using this convention makes it possible for \l{qmake} to identify that + you are building Qt for Windows CE, and will customize the compilation + process accordingly. + + Create the files \c qmake.conf and \c qplatformdefs.h inside the new + specification directory. Take a look at the implementation of the other + Windows CE specifications included in the \c mkspecs directory to see + what is required to build Qt for Windows CE successfully. + + + \section1 Fine-Tuning Options + + Compared to the desktop versions, Qt for Windows CE needs two additional + options: + + \list + \o \bold{CE_SDK} specifies the name of the SDK. + \o \bold{CE_ARCH} specifies information about the target architecture. + \endlist + + Following is an example configuration for the Windows Mobile 5 for + Pocket PC SDK: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 1 + + \note \l{qmake} uses this information to build a valid Visual Studio + project file. You need to ensure that they are identical to the + configuration of the custom SDK, otherwise you might not be able to compile + or debug your project with Visual Studio. + + Additionally, most Windows CE SDKs use extra compiler options. These + can be specified by expanding the \c DEFINES value. + + For example, with Windows Mobile 5 for Pocket PC, the \c DEFINES variable + is expanded in the following way: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 2 + + The mkspec may require additional configuration to be used inside of Visual + Studio, depending on the Windows CE SDK. The above example defines + \c _M_ARM. This definition is available internally in Visual Studio. Hence, + the compiler will warn you about redefinition during the build step. These + warnings can be disabled by adding a \c default_post.prf file containing + the following lines, within the subdirectory. + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 8 + + + \section1 Cross-compilation Environment for a Custom SDK + + Qt for Windows CE supports a convenience script, \c{setcepaths.bat}, that + prepares the environment in a command prompt for cross-compilation. + However, on custom SDKs, the \c checksdk tool is provided to identify the + environment, so Qt compiles successfully. + + \c checksdk is generated during the \c configure step and allows for the + following options: + + \list + \o \c list: Returns a list of available Windows CE SDKs. (This list + may contain one or more SDKs not supported on Qt for Windows CE, + e.g., Pocket PC 2003.) + \o \c sdk: The parameter to specify an SDK. Returns a setup of + environment variables that must be set to cross-compile Qt. + \o \c script: Stores your setup in a \c{.bat} file. This simplifies + the process of switching environments when you load a command + prompt in future. + \endlist + + + \section1 Compiling Qt for a Custom SDK + + Windows CE is highly customizable, hence it is possible that some SDKs have + feature-stripped setups. Depending on the SDK's configuration, Qt may not + compile in its standard configuration, as Qt for Windows CE is designed to + be compatible with the Standard SDK setup. + + However, it is possible to exclude features of Qt and create a version that + compiles for the desired SDK. + + Further information on stripping features can be found in the + \l{Fine-Tuning Features in Qt}{QFeatures} documentation. + + + \section1 Making Qt Applications Start on a Custom Device + + Sometimes, a Windows CE device has been created with a configuration + different from the corresponding SDK's configuration. In this case, symbols + that were available at linking stage will be missing from the run-time + libraries. + + Unfortunately, the operating system will not provide an error message that + mentions which symbols are absent. Instead, a message box with the following + message will appear: + + \c{app.exe is not a valid CE application!} + + To identify the missing symbols, you need to create a temporary + application that attempts to dynamically load the Qt for Windows CE + libraries using \c LoadLibrary. The following code can be used for this: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 9 + + Once you have compiled and deployed the application as well as the Qt + libraries, start a remote debugger. The debugger will then print the + ordinal number of the unresolved symbol. + + Search for parts of Qt that rely on these functions and disable them using + the \l{Fine-Tuning Features in Qt}{QFeatures} functionality. + + In our experience, when Qt applications do not start on Windows CE, it is + usually the result of missing symbols for the following classes or + features: + \list + \o \l{Drag and Drop} + \o \l{QClipboard} + \o \l{QCursor} + \endlist + + Please refer to the Microsoft documentation + \l{http://msdn.microsoft.com/en-us/library/e7tsx612.aspx}{here} for + information on what ordinals are and how you can create them. Information + on accessing the corresponding symbol name to a given ordinal value can + also be found in the Microsoft documentation. + +*/ + +/*! + \page shadow builds-wince.html + \ingroup qtce + \title Windows CE - Using shadow builds + \brief How to create a shadow build for Qt for Windows CE. + + \tableofcontents + + While developing for Windows CE you might want to compile a + version of Qt for several different platforms and SDKs. In order + to create those different builds of Qt you do not have to copy the + whole Qt package or the Qt source. You are able to create multiple + Qt builds from a single source tree. Such builds are called shadow + builds. + + Basically a shadow build is created by calling configure.exe from a + different directory. + + To make sure that the shadow build compiles correctly it is important + that you following these guidelines: + + \list + \o The original Qt source package must be left untouched - configure must + never have been run in the source tree directory. + + \o The shadow build directory must be on the same level as the Qt source + package.\br + If the Qt package is in \c{C:\Qt\%VERSION%} the shadow build directory + could be \c{C:\Qt\shadowbuild}. A shadow build from a directory like + \c{C:\shadowbuild} will not compile. + \o Avoid using "release" and "debug" in the path to the shadow build + directory. (This is an internal limitation of the build system.) + \o The \c{\bin} directory of the shadow build directory must be added to the + \c PATH environment variable. + \o Perl has been installed on your system. (\l{ActivePerl} is a popular + distribution of Perl on Windows.) + \endlist + + So lets assume you have installed Qt in \c{C:\Qt\%VERSION%} and you want + to create a shadow build in \c{C:\Qt\mobile5-shadow}: + + \list + \o First add \c{C:\Qt\mobile5-shadow\bin} to the \c PATH variable. + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 3 + + \o Make sure the enviroment variables for your compiler are set. + + Visual Studio includes \c{vcvars32.bat} for that purpose - or simply use + the "Visual Studio Command Prompt" from the Start menu. + + \o Now navigate to your shadow build directory and run configure: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 4 + + \o To build Qt, you have to update your \c{PATH, INCLUDE} and \c LIB paths + to point to your target platforms. + + For a default installation of the Windows Mobile 5.0 Pocket PC SDK, you + can do the following: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 5 + + We have provided a convenience script for this called \c{setcepaths}. Simply + type: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 6 + + \o Finally, to build the shadow build type: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 7 + + \o That's all. You have successfully created a shadow build of Qt in + \c{C:\Qt\mobile5-shadow}. + \endlist +*/ diff --git a/doc/src/platforms/wince-introduction.qdoc b/doc/src/platforms/wince-introduction.qdoc new file mode 100644 index 0000000..2018eaa --- /dev/null +++ b/doc/src/platforms/wince-introduction.qdoc @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qtce + \title Qt for Windows CE + \ingroup qt-embedded + \brief Documents related to Qt on Windows CE + + Qt for Windows CE is a C++ framework for GUI and application development + for embedded devices running Windows CE. It runs on a variety of processors, + including ARM, Intel x86, MIPS and SH-4. + + \table 100% + \header \o Getting Started \o Reference \o Performance and Optimization + \row + \o + \list + \o \l {Qt for Windows CE Requirements} + \o \l {Installing Qt on Windows CE} + \o \l {Windows CE - Introduction to using Qt}{Introduction to using Qt} + \endlist + \o + \list + \o \l {Windows CE - Using shadow builds}{Using shadow builds} + \o \l {Windows CE - Working with Custom SDKs}{Working with Custom SDKs} + \endlist + \o + \list + \o \l {Windows CE OpenGL ES}{OpenGL ES} + \o \l {Qt Performance Tuning} + \o \l {Fine-Tuning Features in Qt} + \endlist + \endtable +*/ + +/*! + \page wince-with-qt-introduction.html + + \title Windows CE - Introduction to using Qt + \brief An introduction to Qt for Windows CE developers. + \ingroup qtce + + \tableofcontents + + \section1 Required tools + + In order to use Qt for Windows CE you need to have Visual Studio + 2005 and at least one of the supported Windows CE/Mobile SDKs + installed. + + We recommend the \e{Windows Mobile 5.0 SDK for Pocket PC} SDK available + \l{http://www.microsoft.com/downloads/details.aspx?FamilyID=83a52af2-f524-4ec5-9155-717cbe5d25ed&DisplayLang=en}{here}. + + \section1 Installing Qt + + Follow the instructions found in \l{Installing Qt on Windows CE}. + + \section1 Building your own applications + + If you are new to Qt development, have a look at \l{How to Learn Qt} + and \l{Tutorials}. In general there is little or no difference in + developing Qt applications for Windows CE compared to any of the + other platforms supported by Qt. + + Once you have a \c .pro file, there are two ways of building your + application. You can either do it on the command line or inside of + VS2005. To do it on the command line, simply write: + + \snippet doc/src/snippets/code/doc_src_wince-introduction.qdoc 0 + + To build the project inside of VS2005, on the command line write: + + \snippet doc/src/snippets/code/doc_src_wince-introduction.qdoc 1 + + then start VS2005 with the generated \c .vcproj or \c .sln file and + select \e{Build project}. + + For more information on how to use qmake have a look at the \l + {qmake Tutorial}. + + \section1 Running the application + + In order to run the application, it needs to be deployed on the + Windows CE/Mobile device you want to test it for. This can either + be done manually or automated using VS2005. + + To do it manually, simply copy the executable, the Qt \c{.dll} + files needed for the application to run, and the C-runtime library + into a folder on the device, and then click on the executable to + start the program. You can either use the \e Explorer found in + ActiveSync or the \e{Remote File Viewer} found in VS2005 to do + this. + + VS2005 can do this step automatically for you as well. If you have + built the project inside VS2005, simply select \e Deploy and then + \e Debug to deploy and then run the application. You can change the + device type by changing the \e{Target Device} specified in the + VS2005 toolbar. + + Further information on deploying Qt applications for Windows can + be found in the \l{Deploying an Application on Windows} + {deployment document}. +*/ diff --git a/doc/src/platforms/wince-opengl.qdoc b/doc/src/platforms/wince-opengl.qdoc new file mode 100644 index 0000000..7070926 --- /dev/null +++ b/doc/src/platforms/wince-opengl.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** 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 windowsce-opengl.html + \title Windows CE OpenGL ES + \ingroup qtce + \brief Information about support for OpenGL ES with Qt for Windows CE. + + \section1 Introduction + + \l {http://www.opengl.org}{OpenGL} is an industry standard API for 2D/3D + graphics. It provides a powerful, low-level interface between software + and acceleration hardware, and it is operating system and window system + independent. + + \l {http://www.khronos.org/opengles}{OpenGL ES} is a subset of the + \l {http://www.opengl.org}{OpenGL} standard. It is meant for use in + embedded systems. Hence, it has a smaller, more constrained API. + + Qt for Windows CE uses EGL 1.1 to embed OpenGL ES windows within the + Windows CE window manager. + + To use OpenGL ES enabled widgets in a Qt for Windows CE application, you + only need to subclass QGLWidget and draw on instances of the subclass with + OpenGL ES functions. + + OpenGL ES includes profiles for floating-point and fixed-point arithmetic. + The floating point profile is called OpenGL ES CM (Common) and the + fixed-point profile is called OpenGL ES CL (Common Lite). + + You can run \c{configure} with the \c{-opengl-es-cm} option for the Common + profile or \c{-opengl-es-cl} for the Common Lite profile. In both cases, + ensure that the \c{lib} and \c{includes} paths include the OpenGL ES + headers and libararies from your SDK. The OpenGL ES lib should be called + either \c{libGLES_CM.lib} for the Common profile or \c{libGLES_CL.lib} + for the Common Lite profile. + + To configure Qt for Windows Mobile 5.0 and OpenGL ES Common Lite support + you can run \c{configure} like this: + + \snippet doc/src/snippets/code/doc_src_wince-opengl.qdoc 0 + + The distinction between the Common and Common Lite profiles is important, + because the Common Lite profile has less functionality and only supports a + fixed-point vertex format. + + To start programming with Qt and OpenGL ES on Windows CE, you can start + with the \l{Hello GL ES Example}. This example shows how to use QGLWidget + and QGLPainter with OpenGL ES. It also provides some hints on how to port + OpenGL code to OpenGL ES. + + \section2 Using OpenGL to Accelerate Normal 2D Painting + + Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that translates + QPainter operations into OpenGL calls. This is especially convenient for + drawing text or QImage objects in an OpenGL ES context. For further + details, refer to the \l{Hello GL ES Example}. + +*/ diff --git a/doc/src/platforms/winsystem.qdoc b/doc/src/platforms/winsystem.qdoc new file mode 100644 index 0000000..a20ce5d --- /dev/null +++ b/doc/src/platforms/winsystem.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** 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 winsystem.html + \title Window System Specific Notes + \ingroup platform-specific + + Qt is a cross-platform GUI toolkit, so almost the entire API is the + same on all platforms and window systems. If you wish to use + platform-specific features, and still maintain a platform-independent + source tree, you should protect the platform-specific code using the + appropriate \c{#ifdef} directives (see below). + + Qt provides a few low-level global functions for fine-tuning + applications on specific platforms. See \l{Platform-Specific + Functions} for details. + + \tableofcontents + + For information about which platforms are supported by Qt, see the + \l{Platform Notes}. For information on distributing Qt applications, see + \l{Deploying Qt Applications}. + + \target x11 + \section1 Qt for X11 + + When compiling for this platform, the macro \c{Q_WS_X11} is defined. + + \e{Not documented here. Please contact Qt's technical support team + if you have queries.} + + See the \l{Qt for X11 Requirements} page for more information about the + libraries required to build Qt with as many features as possible. + + \target win + \section1 Qt for Windows + + When compiling for this platform, the macro \c{Q_WS_WIN} is defined. + + \e{Not documented here. Please contact Qt's technical support team + if you have queries.} + + \target macosx + \section1 Qt for Mac OS X + + When compiling for this platform, the macro \c{Q_WS_MAC} is defined. + + \list + \i \l{Qt for Mac OS X - Specific Issues} + \i \l{Qt is Mac OS X Native} + \endlist + + \target qws + \section1 Qt for Embedded Linux + + When compiling for this platform, the macro \c{Q_WS_QWS} is + defined (the window system is literally the Qt Window System). See + the \l{Qt for Embedded Linux} documentation for more information. +*/ diff --git a/doc/src/platforms/x11overlays.qdoc b/doc/src/platforms/x11overlays.qdoc new file mode 100644 index 0000000..7d7a776 --- /dev/null +++ b/doc/src/platforms/x11overlays.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** 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 x11overlays.html + \title How to Use X11 Overlays with Qt + + X11 overlays are a powerful mechanism for drawing + annotations etc., on top of an image without destroying it, thus saving + a great deal of image rendering time. For more information, see the highly + recommended book \e{OpenGL Programming for the X Window System} (Mark + Kilgard, Addison Wesley Developers Press 1996). + + \warning The Qt OpenGL Extension includes direct support for the + use of OpenGL overlays. For many uses of overlays, this makes the + technique described below redundant. The following is a discussion + on how to use non-QGL widgets in overlay planes. + + In the typical case, X11 overlays can easily be used together with the + current version of Qt and the Qt OpenGL Extension. The following + requirements apply: + + \list 1 + \i Your X server and graphics card/hardware must support overlays. + For many X servers, overlay support can be turned on with + a configuration option; consult your X server installation + documentation. + + \i Your X server must (be configured to) use an overlay visual as the + default visual. Most modern X servers do this, since this has the + added advantage that pop-up menus, overlapping windows etc., will + \e not affect underlying images in the main plane, thereby + avoiding expensive redraws. + + \i The best (deepest) visual for OpenGL rendering is in the main + plane. This is the normal case. Typically, X servers that support + overlays provide a 24-bit \c TrueColor visual in the main plane, + and an 8-bit \c PseudoColor (default) visual in the overlay plane. + \endlist + + Assuming that the requirements mentioned above are met, a + QGLWidget will default to using the main plane visual, while all + other widgets will use the overlay visual. Thus, we can place a + normal widget on top of the QGLWidget, and do drawing on it, + without affecting the image in the OpenGL window. In other words, + we can use all the drawing capabilities of QPainter to draw + annotations, rubberbands, etc. For the typical use of overlays, + this is much easier than using OpenGL for rendering annotations. + + An overlay plane has a specific color called the transparent + color. Pixels drawn in this color will not be visible; instead + the underlying OpenGL image will show through. + + To use this technique, you must not use the + QApplication::ManyColor or QApplication::TrueColor color + specification for QApplication, because this will force the + normal Qt widgets to use a \c TrueColor visual, which will + typically be in the main plane, not in the overlay plane as + desired. +*/ |