diff options
Diffstat (limited to 'doc/src/howtos')
| -rw-r--r-- | doc/src/howtos/accelerators.qdoc | 138 | ||||
| -rw-r--r-- | doc/src/howtos/appicon.qdoc | 215 | ||||
| -rw-r--r-- | doc/src/howtos/custom-types.qdoc | 179 | ||||
| -rw-r--r-- | doc/src/howtos/guibooks.qdoc | 120 | ||||
| -rw-r--r-- | doc/src/howtos/openvg.qdoc | 322 | ||||
| -rw-r--r-- | doc/src/howtos/qtdesigner.qdoc | 144 | ||||
| -rw-r--r-- | doc/src/howtos/restoring-geometry.qdoc | 87 | ||||
| -rw-r--r-- | doc/src/howtos/session.qdoc | 178 | ||||
| -rw-r--r-- | doc/src/howtos/sharedlibrary.qdoc | 176 | ||||
| -rw-r--r-- | doc/src/howtos/timers.qdoc | 137 | ||||
| -rw-r--r-- | doc/src/howtos/unix-signal-handlers.qdoc | 105 |
11 files changed, 1801 insertions, 0 deletions
diff --git a/doc/src/howtos/accelerators.qdoc b/doc/src/howtos/accelerators.qdoc new file mode 100644 index 0000000..bb1b2d7 --- /dev/null +++ b/doc/src/howtos/accelerators.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** 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 accelerators.html + \title Standard Accelerator Keys + + \ingroup best-practices + + Applications invariably need to define accelerator keys for actions. + Qt fully supports accelerators, for example with \l Q3Accel::shortcutKey(). + + Here are Microsoft's recommendations for accelerator keys, with + comments about the Open Group's recommendations where they exist + and differ. For most commands, the Open Group either has no advice or + agrees with Microsoft. + + The emboldened letter plus Alt is Microsoft's recommended choice, and + we recommend supporting it. For an Apply button, for example, we + recommend QAbstractButton::setText(\link QWidget::tr() tr \endlink("&Apply")); + + If you have conflicting commands (e.g. About and Apply buttons in the + same dialog), you must decide for yourself. + + \list + \i \bold{\underline{A}}bout + \i Always on \bold{\underline{T}}op + \i \bold{\underline{A}}pply + \i \bold{\underline{B}}ack + \i \bold{\underline{B}}rowse + \i \bold{\underline{C}}lose (CDE: Alt+F4; Alt+F4 is "close window" in Windows) + \i \bold{\underline{C}}opy (CDE: Ctrl+C, Ctrl+Insert) + \i \bold{\underline{C}}opy Here + \i Create \bold{\underline{S}}hortcut + \i Create \bold{\underline{S}}hortcut Here + \i Cu\bold{\underline{t}} + \i \bold{\underline{D}}elete + \i \bold{\underline{E}}dit + \i \bold{\underline{E}}xit (CDE: E\bold{\underline{x}}it) + \i \bold{\underline{E}}xplore + \i \bold{\underline{F}}ile + \i \bold{\underline{F}}ind + \i \bold{\underline{H}}elp + \i Help \bold{\underline{T}}opics + \i \bold{\underline{H}}ide + \i \bold{\underline{I}}nsert + \i Insert \bold{\underline{O}}bject + \i \bold{\underline{L}}ink Here + \i Ma\bold{\underline{x}}imize + \i Mi\bold{\underline{n}}imize + \i \bold{\underline{M}}ove + \i \bold{\underline{M}}ove Here + \i \bold{\underline{N}}ew + \i \bold{\underline{N}}ext + \i \bold{\underline{N}}o + \i \bold{\underline{O}}pen + \i Open \bold{\underline{W}}ith + \i Page Set\bold{\underline{u}}p + \i \bold{\underline{P}}aste + \i Paste \bold{\underline{L}}ink + \i Paste \bold{\underline{S}}hortcut + \i Paste \bold{\underline{S}}pecial + \i \bold{\underline{P}}ause + \i \bold{\underline{P}}lay + \i \bold{\underline{P}}rint + \i \bold{\underline{P}}rint Here + \i P\bold{\underline{r}}operties + \i \bold{\underline{Q}}uick View + \i \bold{\underline{R}}edo (CDE: Ctrl+Y, Shift+Alt+Backspace) + \i \bold{\underline{R}}epeat + \i \bold{\underline{R}}estore + \i \bold{\underline{R}}esume + \i \bold{\underline{R}}etry + \i \bold{\underline{R}}un + \i \bold{\underline{S}}ave + \i Save \bold{\underline{A}}s + \i Select \bold{\underline{A}}ll + \i Se\bold{\underline{n}}d To + \i \bold{\underline{S}}how + \i \bold{\underline{S}}ize + \i S\bold{\underline{p}}lit + \i \bold{\underline{S}}top + \i \bold{\underline{U}}ndo (CDE: Ctrl+Z or Alt+Backspace) + \i \bold{\underline{V}}iew + \i \bold{\underline{W}}hat's This? + \i \bold{\underline{W}}indow + \i \bold{\underline{Y}}es + \endlist + + There are also a lot of other keys and actions (that use other + modifier keys than Alt). See the Microsoft and The Open Group + documentation for details. + + The + \l{http://www.amazon.com/exec/obidos/ASIN/0735605661/trolltech/t}{Microsoft book} + has ISBN 0735605661. The corresponding Open Group + book is very hard to find, rather expensive and we cannot recommend + it. However, if you really want it, ogpubs@opengroup.org might be able + to help. Ask them for ISBN 1859121047. +*/ diff --git a/doc/src/howtos/appicon.qdoc b/doc/src/howtos/appicon.qdoc new file mode 100644 index 0000000..a664ade --- /dev/null +++ b/doc/src/howtos/appicon.qdoc @@ -0,0 +1,215 @@ +/**************************************************************************** +** +** 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 appicon.html + \title Setting the Application Icon + + \ingroup best-practices + + The application icon, typically displayed in the top-left corner of an + application's top-level windows, is set by calling the + QWidget::setWindowIcon() method on top-level widgets. + + In order to change the icon of the executable application file + itself, as it is presented on the desktop (i.e., prior to + application execution), it is necessary to employ another, + platform-dependent technique. + + \tableofcontents + + \section1 Setting the Application Icon on Windows + + First, create an ICO format bitmap file that contains the icon + image. This can be done with e.g. Microsoft Visual C++: Select + \menu{File|New}, then select the \menu{File} tab in the dialog + that appears, and choose \menu{Icon}. (Note that you do not need + to load your application into Visual C++; here we are only using + the icon editor.) + + Store the ICO file in your application's source code directory, + for example, with the name \c myappico.ico. Then, create a text + file called, say, \c myapp.rc in which you put a single line of + text: + + \snippet doc/src/snippets/code/doc_src_appicon.qdoc 0 + + Finally, assuming you are using \c qmake to generate your + makefiles, add this line to your \c myapp.pro file: + + \snippet doc/src/snippets/code/doc_src_appicon.qdoc 1 + + Regenerate your makefile and your application. The \c .exe file + will now be represented with your icon in Explorer. + + If you do not use \c qmake, the necessary steps are: first, run + the \c rc program on the \c .rc file, then link your application + with the resulting \c .res file. + + \section1 Setting the Application Icon on Mac OS X + + The application icon, typically displayed in the application dock + area, is set by calling QWidget::setWindowIcon() on a top-level + widget. It is possible that the program could appear in the + application dock area before the function call, in which case a + default icon will appear during the bouncing animation. + + To ensure that the correct icon appears, both when the application is + being launched, and in the Finder, it is necessary to employ a + platform-dependent technique. + + Although many programs can create icon files (\c .icns), the + recommended approach is to use the \e{Icon Composer} program + supplied by Apple (in the \c Developer/Application folder). + \e{Icon Composer} allows you to import several different sized + icons (for use in different contexts) as well as the masks that + go with them. Save the set of icons to a file in your project + directory. + + If you are using qmake to generate your makefiles, you only need + to add a single line to your \c .pro project file. For example, + if the name of your icon file is \c{myapp.icns}, and your project + file is \c{myapp.pro}, add this line to \c{myapp.pro}: + + \snippet doc/src/snippets/code/doc_src_appicon.qdoc 2 + + This will ensure that \c qmake puts your icons in the proper + place and creates an \c{Info.plist} entry for the icon. + + If you do not use \c qmake, you must do the following manually: + \list 1 + \i Create an \c Info.plist file for your application (using the + \c PropertyListEditor, found in \c Developer/Applications). + \i Associate your \c .icns record with the \c CFBundleIconFile record in the + \c Info.plist file (again, using the \c PropertyListEditor). + \i Copy the \c Info.plist file into your application bundle's \c Contents + directory. + \i Copy the \c .icns file into your application bundle's \c Contents/Resources + directory. + \endlist + + \section1 Setting the Application Icon on Common Linux Desktops + + In this section we briefly describe the issues involved in providing + icons for applications for two common Linux desktop environments: + \l{http://www.kde.org/}{KDE} and \l{http://www.gnome.org/}{GNOME}. + The core technology used to describe application icons + is the same for both desktops, and may also apply to others, but there + are details which are specific to each. The main source of information + on the standards used by these Linux desktops is + \l{http://www.freedesktop.org/}{freedesktop.org}. For information + on other Linux desktops please refer to the documentation for the + desktops you are interested in. + + Often, users do not use executable files directly, but instead launch + applications by clicking icons on the desktop. These icons are + representations of "desktop entry files" that contain a description of + the application that includes information about its icon. Both desktop + environments are able to retrieve the information in these files, and + they use it to generate shortcuts to applications on the desktop, in + the start menu, and on the panel. + + More information about desktop entry files can be found in the + \l{http://www.freedesktop.org/Standards/desktop-entry-spec}{Desktop Entry + Specification}. + + Although desktop entry files can usefully encapsulate the application's details, + we still need to store the icons in the conventional location for each desktop + environment. A number of locations for icons are given in the + \l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme + Specification}. + + Although the path used to locate icons depends on the desktop in use, + and on its configuration, the directory structure beneath each of + these should follow the same pattern: subdirectories are arranged by + theme, icon size, and application type. Generally, application icons + are added to the hicolor theme, so a square application icon 32 pixels + in size would be stored in the \c hicolor/32x32/apps directory beneath + the icon path. + + \section2 K Desktop Environment (KDE) + + Application icons can be installed for use by all users, or on a per-user basis. + A user currently logged into their KDE desktop can discover these locations + by using \l{http://developer.kde.org/documentation/other/kde-config.html}{kde-config}, + for example, by typing the following in a terminal window: + + \snippet doc/src/snippets/code/doc_src_appicon.qdoc 3 + + Typically, the list of colon-separated paths printed to stdout includes the + user-specific icon path and the system-wide path. Beneath these + directories, it should be possible to locate and install icons according + to the conventions described in the + \l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme Specification}. + + If you are developing exclusively for KDE, you may wish to take + advantage of the \link + http://developer.kde.org/documentation/other/makefile_am_howto.html + KDE build system\endlink to configure your application. This ensures + that your icons are installed in the appropriate locations for KDE. + + The KDE developer website is at \l{http://developer.kde.org/}. + + \section2 GNOME + + Application icons are stored within a standard system-wide + directory containing architecture-independent files. This + location can be determined by using \c gnome-config, for example + by typing the following in a terminal window: + + \snippet doc/src/snippets/code/doc_src_appicon.qdoc 4 + + The path printed on stdout refers to a location that should contain a directory + called \c{pixmaps}; the directory structure within the \c pixmaps + directory is described in the \link + http://www.freedesktop.org/Standards/icon-theme-spec Icon Theme + Specification \endlink. + + If you are developing exclusively for GNOME, you may wish to use + the standard set of \link + http://developer.gnome.org/tools/build.html GNU Build Tools\endlink, + also described in the relevant section of + the \link http://developer.gnome.org/doc/GGAD/ggad.html GTK+/Gnome + Application Development book\endlink. This ensures that your icons are + installed in the appropriate locations for GNOME. + + The GNOME developer website is at \l{http://developer.gnome.org/}. +*/ diff --git a/doc/src/howtos/custom-types.qdoc b/doc/src/howtos/custom-types.qdoc new file mode 100644 index 0000000..997c8bc --- /dev/null +++ b/doc/src/howtos/custom-types.qdoc @@ -0,0 +1,179 @@ +/**************************************************************************** +** +** 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 custom-types.html + \title Creating Custom Qt Types + \brief How to create and register new types with Qt. + + \ingroup best-practices + + \tableofcontents + + \section1 Overview + + When creating user interfaces with Qt, particularly those with specialized controls and + features, developers sometimes need to create new data types that can be used alongside + or in place of Qt's existing set of value types. + + Standard types such as QSize, QColor and QString can all be stored in QVariant objects, + used as the types of properties in QObject-based classes, and emitted in signal-slot + communication. + + In this document, we take a custom type and describe how to integrate it into Qt's object + model so that it can be stored in the same way as standard Qt types. We then show how to + register the custom type to allow it to be used in signals and slots connections. + + \section1 Creating a Custom Type + + Before we begin, we need to ensure that the custom type we are creating meets all the + requirements imposed by QMetaType. In other words, it must provide: + + \list + \o a public default constructor, + \o a public copy constructor, and + \o a public destructor. + \endlist + + The following \c Message class definition includes these members: + + \snippet examples/tools/customtype/message.h custom type definition + + The class also provides a constructor for normal use and two public member functions + that are used to obtain the private data. + + \section1 Declaring the Type with QMetaType + + The \c Message class only needs a suitable implementation in order to be usable. + However, Qt's type system will not be able to understand how to store, retrieve + and serialize instances of this class without some assistance. For example, we + will be unable to store \c Message values in QVariant. + + The class in Qt responsible for custom types is QMetaType. To make the type known + to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header + file where it is defined: + + \snippet examples/tools/customtype/message.h custom type meta-type declaration + + This now makes it possible for \c Message values to be stored in QVariant objects + and retrieved later. See the \l{Custom Type Example} for code that demonstrates + this. + + The Q_DECLARE_METATYPE() macro also makes it possible for these values to be used as + arguments to signals, but \e{only in direct signal-slot connections}. + To make the custom type generally usable with the signals and slots mechanism, we + need to perform some extra work. + + \section1 Creating and Destroying Custom Objects + + Although the declaration in the previous section makes the type available for use + in direct signal-slot connections, it cannot be used for queued signal-slot + connections, such as those that are made between objects in different threads. + This is because the meta-object system does not know how to handle creation and + destruction of objects of the custom type at run-time. + + To enable creation of objects at run-time, call the qRegisterMetaType() template + function to register it with the meta-object system. This also makes the type + available for queued signal-slot communication as long as you call it before you + make the first connection that uses the type. + + The \l{Queued Custom Type Example} declares a \c Block class which is registered + in the \c{main.cpp} file: + + \snippet examples/threads/queuedcustomtype/main.cpp main start + \dots + \snippet examples/threads/queuedcustomtype/main.cpp register meta-type for queued communications + \dots + \snippet examples/threads/queuedcustomtype/main.cpp main finish + + This type is later used in a signal-slot connection in the \c{window.cpp} file: + + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start + \dots + \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type + \dots + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish + + If a type is used in a queued connection without being registered, a warning will be + printed at the console; for example: + + \code + QObject::connect: Cannot queue arguments of type 'Block' + (Make sure 'Block' is registered using qRegisterMetaType().) + \endcode + + \section1 Making the Type Printable + + It is often quite useful to make a custom type printable for debugging purposes, + as in the following code: + + \snippet examples/tools/customtype/main.cpp printing a custom type + + This is achieved by creating a streaming operator for the type, which is often + defined in the header file for that type: + + \snippet examples/tools/customtype/message.h custom type streaming operator + + The implementation for the \c Message type in the \l{Custom Type Example} + goes to some effort to make the printable representation as readable as + possible: + + \snippet examples/tools/customtype/message.cpp custom type streaming operator + + The output sent to the debug stream can, of course, be made as simple or as + complicated as you like. Note that the value returned by this function is + the QDebug object itself, though this is often obtained by calling the + maybeSpace() member function of QDebug that pads out the stream with space + characters to make it more readable. + + \section1 Further Reading + + The Q_DECLARE_METATYPE() macro and qRegisterMetaType() function documentation + contain more detailed information about their uses and limitations. + + The \l{Custom Type Example}{Custom Type}, + \l{Custom Type Sending Example}{Custom Type Sending} + and \l{Queued Custom Type Example}{Queued Custom Type} examples show how to + implement a custom type with the features outlined in this document. + + The \l{Debugging Techniques} document provides an overview of the debugging + mechanisms discussed above. +*/ diff --git a/doc/src/howtos/guibooks.qdoc b/doc/src/howtos/guibooks.qdoc new file mode 100644 index 0000000..0a7200e --- /dev/null +++ b/doc/src/howtos/guibooks.qdoc @@ -0,0 +1,120 @@ +/**************************************************************************** +** +** 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 guibooks.html + \title Books about GUI Design + \ingroup best-practices + + This is not a comprehensive list -- there are many other books worth + buying. Here we mention just a few user interface books that don't + gather dust on our shelves. + + \bold{\l{http://www.amazon.com/gp/product/0132354160/ref=ase_trolltech/}{C++ + GUI Programming with Qt 4, Second Edition}} + by Jasmin Blanchette and Mark + Summerfield, ISBN 0-13-235416-0. This is the official Qt book written + by two veteran Trolls. The first edition, which is based on Qt 4.1, is available + \l{http://www.qtrac.eu/C++-GUI-Programming-with-Qt-4-1st-ed.zip}{online}. + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0385267746/trolltech/t}{The Design of Everyday Things}} + by Donald Norman, ISBN 0-38526774-6, is one of the classics of human + interface design. Norman shows how badly something as simple as a + kitchen stove can be designed, and everyone should read it who will + design a dialog box, write an error message, or design just about + anything else humans are supposed to use. + + \target fowler + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0070592748/trolltech/t}{GUI Design Handbook}} + by Susan Fowler, ISBN 0-07-059274-8, is an + alphabetical dictionary of widgets and other user interface elements, + with comprehensive coverage of each. Each chapter covers one widget + or other element, contains the most important recommendation from the + Macintosh, Windows and Motif style guides, notes about common + problems, comparison with other widgets that can serve some of the + same roles as this one, etc. + + \target Design Patterns + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0201633612/103-8144203-3273444} + {Design Patterns - Elements of Reusable Object-Oriented Software}} + by Gamma, Helm, Johnson, and Vlissides, ISBN 0-201-63361-2, provides + more information on the Model-View-Controller (MVC) paradigm, explaining + MVC and its sub-patterns in detail. + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0201622165/trolltech/t}{Macintosh + Human Interface Guidelines}}, Second Edition, ISBN + 0-201-62216-5, is worth buying for the \e {don't}s alone. Even + if you're not writing Macintosh software, avoiding most of what it + advises against will produce more easily comprehensible software. + Doing what it tells you to do may also help. This book is now available + \link http://developer.apple.com/techpubs/mac/HIGuidelines/HIGuidelines-2.html + online\endlink and there is a + \link http://developer.apple.com/techpubs/mac/HIGOS8Guide/thig-2.html Mac + OS 8 addendum.\endlink + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/047159900X/trolltech/t}{The + Microsoft Windows User Experience}}, ISBN 1-55615-679-0, + is Microsoft's look and feel bible. Indispensable for everyone who + has customers that worship Microsoft, and it's quite good, too. + It is also available + \link http://msdn.microsoft.com/library/en-us/dnwue/html/welcome.asp online\endlink. + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/047159900X/trolltech/t}{The Icon Book}} + by William Horton, ISBN 0-471-59900-X, is perhaps the only thorough + coverage of icons and icon use in software. In order for icons to be + successful, people must be able to do four things with them: decode, + recognize, find and activate them. This book explains these goals + from scratch and how to reach them, both with single icons and icon + families. Some 500 examples are scattered throughout the text. + + + \section1 Buying these Books from Amazon.com + + These books are made available in association with Amazon.com, our + favorite online bookstore. Here is more information about + \link http://www.amazon.com/exec/obidos/subst/help/shipping-policy.html/t + Amazon.com's shipping options\endlink and its + \link http://www.amazon.com/exec/obidos/subst/help/desk.html/t + customer service.\endlink When you buy a book by following one of these + links, Amazon.com gives about 15% of the purchase price to + \link http://www.amnesty.org/ Amnesty International.\endlink + +*/ diff --git a/doc/src/howtos/openvg.qdoc b/doc/src/howtos/openvg.qdoc new file mode 100644 index 0000000..f2049ce --- /dev/null +++ b/doc/src/howtos/openvg.qdoc @@ -0,0 +1,322 @@ +/**************************************************************************** +** +** 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 openvg.html + \title OpenVG Rendering in Qt + \since 4.6 + \ingroup best-practices + + \brief Efficient rendering on embedded devices with OpenVG + + OpenVG is a standard API from the + \l{http://www.khronos.org/openvg}{Khronos Group} for accelerated + 2D vector graphics that is appearing in an increasing number of + embedded devices. The QtOpenVG plugin provides support for OpenVG + painting. + + OpenVG is optimized for 2D vector operations, and closely matches + the functionality in QPainter. It can therefore be an excellent + substitute for the default raster-based QPaintEngine on hardware + that supports OpenVG. + + \tableofcontents + + \section1 Building Qt with OpenVG support + + OpenVG support can be enabled by passing the \c{-openvg} option + to configure. It is assumed that the following qmake variables + are set to appropriate values in the qmake.conf file for your + platform: + + \list + \o QMAKE_INCDIR_OPENVG + \o QMAKE_LIBDIR_OPENVG + \o QMAKE_LIBS_OPENVG + \endlist + + Most OpenVG implementations are based on EGL, so the following + variables may also need to be set: + + \list + \o QMAKE_INCDIR_EGL + \o QMAKE_LIBDIR_EGL + \o QMAKE_LIBS_EGL + \endlist + + See \l{qmake Variable Reference} for more information on these variables. + + Two kinds of OpenVG engines are currently supported: EGL based, + and engines built on top of OpenGL such as + \l{http://sourceforge.net/projects/shivavg}{ShivaVG}. + EGL based engines are preferred. + + It is assumed that the EGL implementation has some way to turn a + QWidget::winId() into an EGL rendering surface with + \c{eglCreateWindowSurface()}. If this is not the case, then + modifications may be needed to the code under \c{src/gui/egl} and + \c{src/plugins/graphicssystems/openvg} to accomodate the EGL + implementation. + + The ShivaVG graphics system under \c{src/plugins/graphicssystems/shivavg} + is an example of how to integrate a non-EGL implementation of + OpenVG into Qt. It is currently only supported with Qt/X11 + and being an example only, the resulting screen output may not + be as good as with other OpenVG engines. + + \section1 Using the OpenVG graphics system + + Once the graphics system plugin has been built and installed, + applications can be run as follows to use the plugin: + + \code + app -graphicssystem OpenVG + \endcode + + If ShivaVG is being used, then substitute \c ShivaVG instead of + \c OpenVG in the line above. + + If the plugin fails to load, try setting the \c QT_DEBUG_PLUGINS + environment variable to 1 and try again. Usually the plugin + cannot be loaded because Qt cannot locate it in the directory + \c{plugins/graphicssystems} within the Qt installation, or the + dynamic library path does not include the directory containing + the system's \c libOpenVG.so library. + + \section1 Supported features + + \section2 Context modes + + The default configuration is "single-context" mode, where a single + EGLContext object is used for all drawing, regardless of the surface. + Multiple EGLSurfaces are created, one for each window surface or pixmap. + eglMakeCurrent() is called with the same EGLContext every time, but a + different EGLSurface. + + Single-context mode is necessary for QPixmapData to be implemented in + terms of a VGImage. If single-context mode is not enabled, then QPixmapData + will use the fallback QRasterPixmapData implementation, which is less + efficient performance-wise. + + Single-context mode can be disabled with the QVG_NO_SINGLE_CONTEXT define + if the OpenVG engine does not support one context with multiple surfaces. + + \section2 Transformation matrices + + All affine and projective transformation matrices are supported. + + QVGPaintEngine will use the engine to accelerate affine transformation + matrices only. When a projective transformation matrix is used, + QVGPaintEngine will transform the coordinates before passing them + to the engine. This will probably incur a performance penalty. + + Pixmaps and images are always transformed by the engine, because + OpenVG specifies that projective transformations must work for images. + + It is recommended that client applications should avoid using projective + transformations for non-image elements in performance critical code. + + \section2 Composition modes + + The following composition modes are supported: + + \list + \o QPainter::CompositionMode_SourceOver + \o QPainter::CompositionMode_DestinationOver + \o QPainter::CompositionMode_Source + \o QPainter::CompositionMode_SourceIn + \o QPainter::CompositionMode_DestinationIn + \o QPainter::CompositionMode_Plus + \o QPainter::CompositionMode_Multiply + \o QPainter::CompositionMode_Screen + \o QPainter::CompositionMode_Darken + \o QPainter::CompositionMode_Lighten + \endlist + + The other members of QPainter::CompositionMode are not supported + because OpenVG 1.1 does not have an equivalent in its \c VGBlendMode + enumeration. Any attempt to set an unsupported mode will result in + the actual mode being set to QPainter::CompositionMode_SourceOver. + Client applications should avoid using unsupported modes. + + \section2 Pens and brushes + + All pen styles are supported, including cosmetic pens. + + All brush styles are supported except for conical gradients, which are + not supported by OpenVG 1.1. Conical gradients will be converted into a + solid color brush corresponding to the first color in the gradient's + color ramp. + + Affine matrices are supported for brush transforms, but not projective + matrices. + + \section2 Rectangles, lines, and points + + Rectangles and lines use cached VGPath objects to try to accelerate + drawing operations. vgModifyPathCoords() is used to modify the + co-ordinates in the cached VGPath object each time fillRect(), + drawRects(), or drawLines() is called. + + If the engine does not implement vgModifyPathCoords() properly, then the + QVG_NO_MODIFY_PATH define can be set to disable path caching. This will + incur a performance penalty. + + Points are implemented as lines from the point to itself. The cached + line drawing VGPath object is used when drawing points. + + \section2 Polygons and Ellipses + + Polygon and ellipse drawing creates a new VGPath object every time + drawPolygon() or drawEllipse() is called. If the client application is + making heavy use of these functions, the constant creation and destruction + of VGPath objects could have an impact on performance. + + If a projective transformation is active, ellipses are converted into + cubic curves prior to transformation, which may further impact performance. + + Client applications should avoid polygon and ellipse drawing in performance + critical code if possible. + + \section2 Other Objects + + Most other objects (arcs, pies, etc) use drawPath(), which takes a + QPainterPath argument. The default implementation in QPainterEngineEx + converts the QPainterPath into a QVectorPath and then calls draw(), + which in turn converts the QVectorPath into a VGPath for drawing. + + To reduce the overhead, we have overridden drawPath() in QVGPaintEngine + to convert QPainterPath's directly into VGPath's. This should help improve + performance compared to the default implementation. + + Client applications should try to avoid these types of objects in + performance critical code because of the QPainterPath to VGPath + conversion cost. + + \section2 Clipping + + Clipping with QRect, QRectF, and QRegion objects is supported on all + OpenVG engines with vgMask() if the transformation matrix is the identity + or a simple origin translation. + + Clipping with an arbitrary QPainterPath, or setting the clip region when + the transformation matrix is simple, is supported only if the OpenVG engine + has the vgRenderToMask() function (OpenVG 1.1 and higher). + + The QVG_NO_RENDER_TO_MASK define will disable the use of vgRenderToMask(). + + The QVG_SCISSOR_CLIP define will disable clipping with vgMask() or + vgRenderToMask() and instead use the scissor rectangle list to perform + clipping. Clipping with an arbitrary QPainterPath will not be supported. + The QVG_SCISSOR_CLIP define should only be used if the OpenVG engine + does not support vgMask() or vgRenderToMask(). + + \section2 Opacity + + Opacity is supported for all drawing operations. Solid color pens, + solid color brushes, gradient brushes, and image drawing with drawPixmap() + and drawImage() will probably have the best performance compared to + other kinds of pens and brushes. + + \section2 Text Drawing + + If OpenVG 1.1 is used, the paint engine will use VG fonts to cache glyphs + while drawing. If the engine does not support VG fonts correctly, + QVG_NO_DRAW_GLYPHS can be defined to disable this mode. Text drawing + performance will suffer if VG fonts are not used. + + By default, image-based glyphs are used. If QVG_NO_IMAGE_GLYPHS is defined, + then path-based glyphs will be used instead. QVG_NO_IMAGE_GLYPHS is ignored + if QVG_NO_DRAW_GLYPHS is defined. + + If path-based glyphs are used, then the OpenVG engine will need to + support hinting to render text with good results. Image-based glyphs + avoids the need for hinting and will usually give better results than + path-based glyphs. + + \section2 Pixmaps + + In single-context mode, pixmaps will be implemented using VGImage + unless QVG_NO_PIXMAP_DATA is defined. + + QVGPixmapData will convert QImage's into VGImage's when the application + calls drawPixmap(), and the pixmap will be kept in VGImage form for the + lifetime of the QVGPixmapData object. When the application tries to paint + into a QPixmap with QPainter, the data will be converted back into a + QImage and the raster paint engine will be used to render into the QImage. + + This arrangement optimizes for the case of drawing the same static pixmap + over and over (e.g. for icons), but does not optimize the case of drawing + into pixmaps. + + Bitmaps must use QRasterPixmapData. They are not accelerated with + VGImage at present. + + \section2 Pixmap filters + + Convolution, colorize, and drop shadow filters are accelerated using + OpenVG operations. + + \section1 Known issues + + Performance of copying the contents of an OpenVG-rendered window to the + screen needs platform-specific work in the QVGWindowSurface class. + + Clipping with arbitrary non-rectangular paths only works on engines + that support vgRenderToMask(). Simple rectangular paths are supported + on all engines that correctly implement vgMask(). + + The paint engine is not yet thread-safe, so it is not recommended for + use in threaded Qt applications that draw from multiple threads. + Drawing should be limited to the main GUI thread. + + Performance of projective matrices for non-image drawing is not as good + as for affine matrices. + + QPixmap's are implemented as VGImage objects so that they can be quickly + rendered with drawPixmap(). Rendering into a QPixmap using QPainter + will use the default Qt raster paint engine on a QImage copy of the + QPixmap, and will not be accelerated. This issue may be addressed in + a future version of the engine. + + ShivaVG support is highly experimental and limited to Qt/X11. It is + provided as an example of how to integrate a non-EGL engine. +*/ diff --git a/doc/src/howtos/qtdesigner.qdoc b/doc/src/howtos/qtdesigner.qdoc new file mode 100644 index 0000000..ae84f93 --- /dev/null +++ b/doc/src/howtos/qtdesigner.qdoc @@ -0,0 +1,144 @@ +/**************************************************************************** +** +** 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 qtdesigner-components.html + \title Creating and Using Components for Qt Designer + \ingroup best-practices + + \tableofcontents + + \section1 Creating Custom Widget Plugins + + When implementing a custom widget plugin for \QD, you must + subclass QDesignerCustomWidgetInterface to expose your custom + widget to \QD. A single custom widget plugin is built as a + separate library. If you want to include several custom widget + plugins in the same library, you must in addition subclass + QDesignerCustomWidgetCollectionInterface. + + To provide your custom widget plugin with the expected behavior + and functionality within \QD's workspace you can subclass the + associated extension classes: + + The QDesignerContainerExtension class allows you to add pages to a + custom multi-page container. The QDesignerTaskMenuExtension class + allows you to add custom menu entries to \QD's task menu. The + QDesignerMemberSheetExtension class allows you to manipulate a + widget's member functions which is displayed when configuring + connections using \QD's mode for editing signals and slots. And + finally, the QDesignerPropertySheetExtension class allows you to + manipulate a widget's properties which is displayed in \QD's + property editor. + + \image qtdesignerextensions.png + + In \QD the extensions are not created until they are required. For + that reason, when implementing extensions, you must also subclass + QExtensionFactory, i.e create a class that is able to make + instances of your extensions. In addition, you must make \QD's + extension manager register your factory; the extension manager + controls the construction of extensions as they are required, and + you can access it through QDesignerFormEditorInterface and + QExtensionManager. + + For a complete example creating a custom widget plugin with an + extension, see the \l {designer/taskmenuextension}{Task Menu + Extension} or \l {designer/containerextension}{Container + Extension} examples. + + \section1 Retrieving Access to \QD Components + + The purpose of the classes mentioned in this section is to provide + access to \QD's components, managers and workspace, and they are + not intended to be instantiated directly. + + \QD is composed by several components. It has an action editor, a + property editor, widget box and object inspector which you can + view in its workspace. + + \image qtdesignerscreenshot.png + + \QD also has an object that works behind the scene; it contains + the logic that integrates all of \QD's components into a coherent + application. You can access this object, using the + QDesignerFormEditorInterface, to retrieve interfaces to \QD's + components: + + \list + \o QDesignerActionEditorInterface + \o QDesignerObjectInspectorInterface + \o QDesignerPropertyEditorInterface + \o QDesignerWidgetBoxInterface + \endlist + + In addition, you can use QDesignerFormEditorInterface to retrieve + interfaces to \QD's extension manager (QExtensionManager) and form + window manager (QDesignerFormWindowManagerInterface). The + extension manager controls the construction of extensions as they + are required, while the form window manager controls the form + windows appearing in \QD's workspace. + + Once you have an interface to \QD's form window manager + (QDesignerFormWindowManagerInterface), you also have access to all + the form windows currently appearing in \QD's workspace: The + QDesignerFormWindowInterface class allows you to query and + manipulate the form windows, and it provides an interface to the + form windows' cursors. QDesignerFormWindowCursorInterface is a + convenience class allowing you to query and modify a given form + window's widget selection, and in addition modify the properties + of all the form's widgets. + + \section1 Creating User Interfaces at Run-Time + + The \c QtDesigner module contains the QFormBuilder class that + provides a mechanism for dynamically creating user interfaces at + run-time, based on UI files created with \QD. This class is + typically used by custom components and applications that embed + \QD. Standalone applications that need to dynamically generate + user interfaces at run-time use the QUiLoader class, found in + the QtUiTools module. + + For a complete example using QUiLoader, see + the \l {designer/calculatorbuilder}{Calculator Builder example}. + + \sa {Qt Designer Manual}, {QtUiTools Module} +*/ diff --git a/doc/src/howtos/restoring-geometry.qdoc b/doc/src/howtos/restoring-geometry.qdoc new file mode 100644 index 0000000..c9e6f4f --- /dev/null +++ b/doc/src/howtos/restoring-geometry.qdoc @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** 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 restoring-geometry.html + \title Restoring a Window's Geometry + + \ingroup best-practices + + This document describes how to save and restore a window's + geometry using the geometry properties. On Windows, this is + basically storing the result of QWidget::geometry() and calling + QWidget::setGeometry() in the next session before calling + \l{QWidget::show()}{show()}. + + On X11, this won't work because an invisible window doesn't have + a frame yet. The window manager will decorate the window later. + When this happens, the window shifts towards the bottom/right + corner of the screen depending on the size of the decoration frame. + Although X provides a way to avoid this shift, most window managers + fail to implement this feature. + + Since version 4.2, Qt provides functions that saves and restores a + window's geometry and state for you. QWidget::saveGeometry() + saves the window geometry and maximized/fullscreen state, while + QWidget::restoreGeometry() restores it. The restore function also + checks if the restored geometry is outside the available screen + geometry, and modifies it as appropriate if it is. + + If those functions are not available or cannot be used, then a + workaround is to call \l{QWidget::setGeometry()}{setGeometry()} + after \l{QWidget::show()}{show()}. This has the two disadvantages + that the widget appears at a wrong place for a millisecond + (results in flashing) and that currently only every second window + manager gets it right. A safer solution is to store both + \l{QWidget::pos()}{pos()} and \l{QWidget::size()}{size()} and to + restore the geometry using \l{QWidget::resize()} and + \l{QWidget::move()}{move()} before calling + \l{QWidget::show()}{show()}, as demonstrated in the following + code snippets (from the \l{mainwindows/application}{Application} + example): + + \snippet examples/mainwindows/application/mainwindow.cpp 35 + \codeline + \snippet examples/mainwindows/application/mainwindow.cpp 38 + + This method works on Windows, Mac OS X, and most X11 window + managers. +*/ diff --git a/doc/src/howtos/session.qdoc b/doc/src/howtos/session.qdoc new file mode 100644 index 0000000..8e51b6b --- /dev/null +++ b/doc/src/howtos/session.qdoc @@ -0,0 +1,178 @@ +/**************************************************************************** +** +** 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 session.html + \title Session Management + + \ingroup best-practices + + A \e session is a group of running applications, each of which has a + particular state. The session is controlled by a service called the \e + session \e manager. The applications participating in the session are + called \e{session clients}. + + The session manager issues commands to its clients on behalf of the + user. These commands may cause clients to commit unsaved changes (for + example by saving open files), to preserve their state for future + sessions, or to terminate gracefully. The set of these operations is + called \e session \e management. + + In the common case, a session consists of all applications that a + user runs on their desktop at a time. Under Unix/X11, however, a + session may include applications running on different computers and + may span multiple displays. + + \section1 Shutting a Session Down + + A session is shut down by the session manager, usually on behalf of + the user when they want to log out. A system might also perform an + automatic shutdown in an emergency situation, for example, if power is + about to be lost. Clearly there is a significant difference between + these types of shutdown. During the first, the user may want to + interact with the application, specifying exactly which files should + be saved and which should be discarded. In the latter case, there's no + time for interaction. There may not even be a user sitting in front of + the machine! + + + \section1 Protocols and Support on Different Platforms + + On Mac OS X, and Microsoft Windows versions prior to Windows 2000, + there is nothing like complete session management for applications + yet, i.e. no restoring of previous sessions. (Windows 2000 and XP + provide "hibernation" where the entire memory is saved to disk and + restored when the machine is restarted.) They do support graceful + logouts where applications have the opportunity to cancel the process + after getting confirmation from the user. This is the functionality + that corresponds to the QApplication::commitData() method. + + X11 has supported complete session management since X11R6. + + \section1 Getting Session Management to Work with Qt + + Start by reimplementing QApplication::commitData() to + enable your application to take part in the graceful logout process. If + you are only targeting the Microsoft Windows platform, this is all you can + and must provide. Ideally, your application should provide a shutdown + dialog similar to the following: + + \img session.png A typical dialog on shutdown + + Example code for this dialog can be found in the documentation of + QSessionManager::allowsInteraction(). + + For complete session management (only supported on X11R6 at present), + you must also take care of saving the application's state, and + potentially of restoring the state in the next life cycle of the + session. This saving is done by reimplementing + QApplication::saveState(). All state data you are saving in this + function, should be marked with the session identifier + QApplication::sessionId(). This application specific identifier is + globally unique, so no clashes will occur. (See QSessionManager for + information on saving/restoring the state of a particular Qt + application.) + + Restoration is usually done in the application's main() + function. Check if QApplication::isSessionRestored() is \c true. If + that's the case, use the session identifier + QApplication::sessionId() again to access your state data and restore + the state of the application. + + \bold{Important:} In order to allow the window manager to + restore window attributes such as stacking order or geometry + information, you must identify your top level widgets with + unique application-wide object names (see QObject::setObjectName()). When + restoring the application, you must ensure that all restored + top level widgets are given the same unique names they had before. + + \section1 Testing and Debugging Session Management + + Session management support on Mac OS X and Windows is fairly limited + due to the lack of this functionality in the operating system + itself. Simply shut the session down and verify that your application + behaves as expected. It may be useful to launch another application, + usually the integrated development environment, before starting your + application. This other application will get the shutdown message + afterwards, thus permitting you to cancel the shutdown. Otherwise you + would have to log in again after each test run, which is not a problem + per se, but is time consuming. + + On Unix you can either use a desktop environment that supports + standard X11R6 session management or, the recommended method, use the + session manager reference implementation provided by the X Consortium. + This sample manager is called \c xsm and is part of a standard X11R6 + installation. As always with X11, a useful and informative manual page + is provided. Using \c xsm is straightforward (apart from the clumsy + Athena-based user interface). Here's a simple approach: + + \list + \i Run X11R6. + \i Create a dot file \c .xsmstartup in your home directory which + contains the single line + \snippet doc/src/snippets/code/doc_src_session.qdoc 0 + This tells \c xsm that the default/failsafe session is just an xterm + and nothing else. Otherwise \c xsm would try to invoke lots of + clients including the windowmanager \c twm, which isn't very helpful. + \i Now launch \c xsm from another terminal window. Both a session + manager window and the xterm will appear. The xterm has a nice + property that sets it apart from all the other shells you are + currently running: within its shell, the \c SESSION_MANAGER + environment variable points to the session manager you just started. + \i Launch your application from the new xterm window. It will connect + itself automatically to the session manager. You can check with the \e + ClientList push button whether the connect was successful. + + \bold{Note:} Never keep the \e ClientList open when you + start or end session managed clients! Otherwise \c xsm is likely to + crash. + \i Use the session manager's \e Checkpoint and \e Shutdown buttons + with different settings and see how your application behaves. The save + type \e local means that the clients should save their state. It + corresponds to the QApplication::saveState() function. The \e + global save type asks applications to save their unsaved changes in + permanent, globally accessible storage. It invokes + QApplication::commitData(). + \i Whenever something crashes, blame \c xsm and not Qt. \c xsm is far + from being a usable session manager on a user's desktop. It is, + however, stable and useful enough to serve as testing environment. + \endlist +*/ diff --git a/doc/src/howtos/sharedlibrary.qdoc b/doc/src/howtos/sharedlibrary.qdoc new file mode 100644 index 0000000..1e108a6 --- /dev/null +++ b/doc/src/howtos/sharedlibrary.qdoc @@ -0,0 +1,176 @@ +/**************************************************************************** +** +** 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 sharedlibrary.html + \title Creating Shared Libraries + + \ingroup best-practices + + The following sections list certain things that should be taken into + account when creating shared libraries. + + \section1 Using Symbols from Shared Libraries + + Symbols - functions, variables or classes - contained in shared libraries + intended to be used by \e{clients}, such as applications or other + libraries, must be marked in a special way. These symbols are called + \e{public symbols} that are \e{exported} or made publicly visible. + + The remaining symbols should not be visible from the outside. On most + platforms, compilers will hide them by default. On some platforms, a + special compiler option is required to hide these symbols. + + When compiling a shared library, it must be marked for \e{export}. To use + the shared library from a client, some platforms may require a special + \e{import} declaration as well. + + Depending on your target platform, Qt provides special macros that contain + the necessary definitions: + \list + \o \c{Q_DECL_EXPORT} must be added to the declarations of symbols used + when compiling a shared library. + \o \c{Q_DECL_IMPORT} must be added to the declarations of symbols used + when compiling a client that uses the shared library. + \endlist + + Now, we need to ensure that the right macro is invoked -- whether we + compile a share library itself, or just the client using the shared + library. + Typically, this can be solved by adding a special header. + + Let us assume we want to create a shared library called \e{mysharedlib}. + A special header for this library, \c{mysharedlib_global.h}, looks like + this: + + \code + #include <QtCore/QtGlobal> + + #if defined(MYSHAREDLIB_LIBRARY) + # define MYSHAREDLIB_EXPORT Q_DECL_EXPORT + #else + # define MYSHAREDLIB_EXPORT Q_DECL_IMPORT + #endif + \endcode + + In the \c{.pro} file of the shared library, we add: + + \code + DEFINES += MYSHAREDLIB_LIBRARY + \endcode + + In each header of the library, we specify the following: + + \code + #include "mysharedlib_global.h" + + MYSHAREDLIB_EXPORT void foo(); + class MYSHAREDLIB_EXPORT MyClass... + \endcode + This ensures that the right macro is seen by both library and clients. We + also use this technique in Qt's sources. + + + \section1 Header File Considerations + + Typically, clients will include only the public header files of shared + libraries. These libraries might be installed in a different location, when + deployed. Therefore, it is important to exclude other internal header files + that were used when building the shared library. + + For example, the library might provide a class that wraps a hardware device + and contains a handle to that device, provided by some 3rd-party library: + + \code + #include <footronics/device.h> + + class MyDevice { + private: + FOOTRONICS_DEVICE_HANDLE handle; + }; + \endcode + + A similar situation arises with forms created by Qt Designer when using + aggregation or multiple inheritance: + + \code + #include "ui_widget.h" + + class MyWidget : public QWidget { + private: + Ui::MyWidget m_ui; + }; + \endcode + + When deploying the library, there should be no dependency to the internal + headers \c{footronics/device.h} or \c{ui_widget.h}. + + This can be avoided by making use of the \e{Pointer to implementation} + idiom described in various C++ programming books. For classes with + \e{value semantics}, consider using QSharedDataPointer. + + + \section1 Binary compatibility + + For clients loading a shared library, to work correctly, the memory + layout of the classes being used must match exactly the memory layout of + the library version that was used to compile the client. In other words, + the library found by the client at runtime must be \e{binary compatible} + with the version used at compile time. + + This is usually not a problem if the client is a self-contained software + package that ships all the libraries it needs. + + However, if the client application relies on a shared library that belongs + to a different installation package or to the operating system, then we + need to think of a versioning scheme for shared libraries and decide at + which level \e{Binary compatibility} is to be maintained. For example, Qt + libraries of the same \e{major version number} are guaranteed to be binary + compatible. + + Maintaining \e{Binary compatibility} places some restrictions on the changes + you can make to the classes. A good explanation can be found at + \l{http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++} + {KDE - Policies/Binary Compatibility Issues With C++}. These issues should + be considered right from the start of library design. + We recommend that the principle of \e{Information hiding} and the + \e{Pointer to implementation} technique be used wherever possible. +*/ diff --git a/doc/src/howtos/timers.qdoc b/doc/src/howtos/timers.qdoc new file mode 100644 index 0000000..ed46b76 --- /dev/null +++ b/doc/src/howtos/timers.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** 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 timers.html + \title Timers + \brief How to use timers in your application. + + \ingroup best-practices + + QObject, the base class of all Qt objects, provides the basic + timer support in Qt. With QObject::startTimer(), you start a + timer with an interval in milliseconds as argument. The function + returns a unique integer timer ID. The timer will now fire at + regular intervals until you explicitly call QObject::killTimer() + with the timer ID. + + For this mechanism to work, the application must run in an event + loop. You start an event loop with QApplication::exec(). When a + timer fires, the application sends a QTimerEvent, and the flow of + control leaves the event loop until the timer event is processed. + This implies that a timer cannot fire while your application is + busy doing something else. In other words: the accuracy of timers + depends on the granularity of your application. + + In multithreaded applications, you can use the timer mechanism in + any thread that has an event loop. To start an event loop from a + non-GUI thread, use QThread::exec(). Qt uses the object's + \l{QObject::thread()}{thread affinity} to determine which thread + will deliver the QTimerEvent. Because of this, you must start and + stop all timers in the object's thread; it is not possible to + start timers for objects in another thread. + + The upper limit for the interval value is determined by the number + of milliseconds that can be specified in a signed integer + (in practice, this is a period of just over 24 days). The accuracy + depends on the underlying operating system. Windows 98 has 55 + millisecond accuracy; other systems that we have tested can handle + 1 millisecond intervals. + + The main API for the timer functionality is QTimer. That class + provides regular timers that emit a signal when the timer fires, and + inherits QObject so that it fits well into the ownership structure + of most GUI programs. The normal way of using it is like this: + + \snippet doc/src/snippets/timers/timers.cpp 0 + \snippet doc/src/snippets/timers/timers.cpp 1 + \snippet doc/src/snippets/timers/timers.cpp 2 + + The QTimer object is made into a child of this widget so that, + when this widget is deleted, the timer is deleted too. + Next, its \l{QTimer::}{timeout()} signal is connected to the slot + that will do the work, it is started with a value of 1000 + milliseconds, indicating that it will time out every second. + + QTimer also provides a static function for single-shot timers. + For example: + + \snippet doc/src/snippets/timers/timers.cpp 3 + + 200 milliseconds (0.2 seconds) after this line of code is + executed, the \c updateCaption() slot will be called. + + For QTimer to work, you must have an event loop in your + application; that is, you must call QCoreApplication::exec() + somewhere. Timer events will be delivered only while the event + loop is running. + + In multithreaded applications, you can use QTimer in any thread + that has an event loop. To start an event loop from a non-GUI + thread, use QThread::exec(). Qt uses the timer's + \l{QObject::thread()}{thread affinity} to determine which thread + will emit the \l{QTimer::}{timeout()} signal. Because of this, you + must start and stop the timer in its thread; it is not possible to + start a timer from another thread. + + The \l{widgets/analogclock}{Analog Clock} example shows how to use + QTimer to redraw a widget at regular intervals. From \c{AnalogClock}'s + implementation: + + \snippet examples/widgets/analogclock/analogclock.cpp 0 + \snippet examples/widgets/analogclock/analogclock.cpp 2 + \snippet examples/widgets/analogclock/analogclock.cpp 3 + \snippet examples/widgets/analogclock/analogclock.cpp 4 + \snippet examples/widgets/analogclock/analogclock.cpp 5 + \snippet examples/widgets/analogclock/analogclock.cpp 6 + \dots + \snippet examples/widgets/analogclock/analogclock.cpp 7 + + Every second, QTimer will call the QWidget::update() slot to + refresh the clock's display. + + If you already have a QObject subclass and want an easy + optimization, you can use QBasicTimer instead of QTimer. With + QBasicTimer, you must reimplement + \l{QObject::timerEvent()}{timerEvent()} in your QObject subclass + and handle the timeout there. The \l{widgets/wiggly}{Wiggly} + example shows how to use QBasicTimer. +*/ diff --git a/doc/src/howtos/unix-signal-handlers.qdoc b/doc/src/howtos/unix-signal-handlers.qdoc new file mode 100644 index 0000000..4e123bc --- /dev/null +++ b/doc/src/howtos/unix-signal-handlers.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** 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 unix-signals.html + \title Calling Qt Functions From Unix Signal Handlers + \brief You can't. But don't despair, there is a way... + + \ingroup platform-specific + \ingroup best-practices + + You \e can't call Qt functions from Unix signal handlers. The + standard POSIX rule applies: You can only call async-signal-safe + functions from signal handlers. See \l + {http://www.opengroup.org/onlinepubs/000095399/functions/xsh_chap02_04.html#tag_02_04_01} + {Signal Actions} for the complete list of functions you can call + from Unix signal handlers. + + But don't despair, there is a way to use Unix signal handlers with + Qt. The strategy is to have your Unix signal handler do something + that will eventually cause a Qt signal to be emitted, and then you + simply return from your Unix signal handler. Back in your Qt + program, that Qt signal gets emitted and then received by your Qt + slot function, where you can safely do whatever Qt stuff you + weren't allowed to do in the Unix signal handler. + + One simple way to make this happen is to declare a socket pair in + your class for each Unix signal you want to handle. The socket + pairs are declared as static data members. You also create a + QSocketNotifier to monitor the \e read end of each socket pair, + declare your Unix signal handlers to be static class methods, and + declare a slot function corresponding to each of your Unix signal + handlers. In this example, we intend to handle both the SIGHUP and + SIGTERM signals. Note: You should read the socketpair(2) and the + sigaction(2) man pages before plowing through the following code + snippets. + + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 0 + + In the MyDaemon constructor, use the socketpair(2) function to + initialize each file descriptor pair, and then create the + QSocketNotifier to monitor the \e read end of each pair. The + activated() signal of each QSocketNotifier is connected to the + appropriate slot function, which effectively converts the Unix + signal to the QSocketNotifier::activated() signal. + + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 1 + + Somewhere else in your startup code, you install your Unix signal + handlers with sigaction(2). + + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 2 + + In your Unix signal handlers, you write a byte to the \e write end + of a socket pair and return. This will cause the corresponding + QSocketNotifier to emit its activated() signal, which will in turn + cause the appropriate Qt slott function to run. + + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 3 + + In the slot functions connected to the + QSocketNotifier::activated() signals, you \e read the byte. Now + you are safely back in Qt with your signal, and you can do all the + Qt stuff you weren'tr allowed to do in the Unix signal handler. + + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 4 +*/ |