diff options
Diffstat (limited to 'doc/src/frameworks-technologies')
25 files changed, 12270 insertions, 0 deletions
diff --git a/doc/src/frameworks-technologies/accessible.qdoc b/doc/src/frameworks-technologies/accessible.qdoc new file mode 100644 index 000000000..1822a5f00 --- /dev/null +++ b/doc/src/frameworks-technologies/accessible.qdoc @@ -0,0 +1,624 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group accessibility + \title Accessibility Classes +*/ + +/*! + \page accessible.html + \title Accessibility + + \ingroup frameworks-technologies + + \tableofcontents + + \section1 Introduction + + Accessibility in computer software is making applications usable + for people with disabilities. This could be achieved by providing + keyboard shortcuts, a high-contrast user interface that uses + specially selected colors and fonts, or support for assistive tools + such as screen readers and braille displays. + + An application does not usually communicate directly with + assistive tools but through an assistive technology, which is a + bridge for exchange of information between the applications and + the tools. Information about user interface elements, such + as buttons and scroll bars, is exposed to the assistive technologies. + Qt supports Microsoft Active Accessibility (MSAA) on Windows and + Mac OS X Accessibility on Mac OS X. + On Unix/X11, support is preliminary. The individual technologies + are abstracted from Qt, and there is only a single interface to + consider. We will use MSAA throughout this document when we need + to address technology related issues. + + In this overview document, we will examine the overall Qt + accessibility architecture, and how to implement accessibility for + custom widgets and elements. + + \section1 Architecture + + Providing accessibility is a collaboration between accessibility + compliant applications, the assistive technology, and the + assistive tools. + + \image accessibilityarchitecture.png + + Accessibility compliant applications are called AT-Servers while + assistive tools are called AT-Clients. A Qt application will + typically be an AT-Server, but specialized programs might also + function like AT-Clients. We will refer to clients and servers + when talking about AT-Clients and AT-Servers in the rest of this + document. + + We will from now on focus on the Qt accessibility interface and + how it is implemented to create Qt applications that support + accessibility. + + \section2 Accessibility in Qt + + These classes provide support for accessible applications. + + \annotatedlist accessibility + + When we communicate with the assistive technologies, we need to + describe Qt's user interface in a way that they can understand. Qt + applications use QAccessibleInterface to expose information about the + individual UI elements. Currently, Qt provides support for its widgets + and widget parts, e.g., slider handles, but the interface could + also be implemented for any QObject if necessary. QAccessible + contains enums that describe the UI. The description is mainly + based on MSAA and is independent of Qt. We will examine the enums + in the course of this document. + + The structure of the UI is represented as a tree of + QAccessibleInterface subclasses. You can think of this as a + representation of a UI like the QObject tree built by Qt. Objects + can be widgets or widget parts (such as scroll bar handles). We + examine the tree in detail in the next section. + + Servers notify clients through \l{QAccessible::}{updateAccessibility()} + about changes in objects by sending events, and the clients + register to receive the events. The available events are defined + by the QAccessible::Event enum. The clients may then query for + the object that generated the event through + QAccessible::queryAccessibleInterface(). + + Three of the enums in QAccessible help clients query and alter + accessible objects: + + \list + \o \l{QAccessible::}{Role}: Describes the role the object + fills in the user interface, e.g., if it is a main + window, a text caret, or a cell in an item view. + \o \l{QAccessible::}{Action}: The actions that the + clients can perform on the objects, e.g., pushing a + button. + \o \l{QAccessible::}{Relation}: Describes the relationship + between objects in the object tree. + This is used for navigation. + \endlist + + The clients also have some possibilities to get the content of + objects, e.g., a button's text; the object provides strings + defined by the QAccessible::Text enum, that give information + about content. + + The objects can be in a number of different states as defined by + the \l{QAccessible::}{State} enum. Examples of states are whether + the object is disabled, if it has focus, or if it provides a pop-up + menu. + + \section2 The Accessible Object Tree + + As mentioned, a tree structure is built from the accessible + objects of an application. By navigating through the tree, the + clients can access all elements in the UI. Object relations give + clients information about the UI. For instance, a slider handle is + a child of the slider to which it belongs. QAccessible::Relation + describes the various relationships the clients can ask objects + for. + + Note that there are no direct mapping between the Qt QObject tree + and the accessible object tree. For instance, scroll bar handles + are accessible objects but are not widgets or objects in Qt. + + AT-Clients have access to the accessibility object tree through + the root object in the tree, which is the QApplication. They can + query other objects through QAccessible::navigate(), which fetches + objects based on \l{QAccessible::}{Relation}s. The children of any + node is 1-based numbered. The child numbered 0 is the object + itself. The children of all interfaces are numbered this way, + i.e., it is not a fixed numbering from the root node in the entire + tree. + + Qt provides accessible interfaces for its widgets. Interfaces for + any QObject subclass can be requested through + QAccessible::queryInterface(). A default implementation is + provided if a more specialized interface is not defined. An + AT-Client cannot acquire an interface for accessible objects that + do not have an equivalent QObject, e.g., scroll bar handles, but + they appear as normal objects through interfaces of parent + accessible objects, e.g., you can query their relationships with + QAccessible::relationTo(). + + To illustrate, we present an image of an accessible object tree. + Beneath the tree is a table with examples of object relationships. + + \image accessibleobjecttree.png + + The labels in top-down order are: the QAccessibleInterface class + name, the widget for which an interface is provided, and the + \l{QAccessible::}{Role} of the object. The Position, PageLeft and + PageRight correspond to the slider handle, the slider groove left + and the slider groove right, respectively. These accessible objects + do not have an equivalent QObject. + + \table 40% + \header + \o Source Object + \o Target Object + \o Relation + \row + \o Slider + \o Indicator + \o Controller + \row + \o Indicator + \o Slider + \o Controlled + \row + \o Slider + \o Application + \o Ancestor + \row + \o Application + \o Slider + \o Child + \row + \o PushButton + \o Indicator + \o Sibling + \endtable + + \section2 The Static QAccessible Functions + + The accessibility is managed by QAccessible's static functions, + which we will examine shortly. They produce QAccessible + interfaces, build the object tree, and initiate the connection + with MSAA or the other platform specific technologies. If you are + only interested in learning how to make your application + accessible, you can safely skip over this section to + \l{Implementing Accessibility}. + + The communication between clients and the server is initiated when + \l{QAccessible::}{setRootObject()} is called. This is done when + the QApplication instance is instantiated and you should not have + to do this yourself. + + When a QObject calls \l{QAccessible::}{updateAccessibility()}, + clients that are listening to events are notified of the + change. The function is used to post events to the assistive + technology, and accessible \l{QAccessible::Event}{events} are + posted by \l{QAccessible::}{updateAccessibility()}. + + \l{QAccessible::}{queryAccessibleInterface()} returns accessible + interfaces for \l{QObject}s. All widgets in Qt provide interfaces; + if you need interfaces to control the behavior of other \l{QObject} + subclasses, you must implement the interfaces yourself, although + the QAccessibleObject convenience class implements parts of the + functionality for you. + + The factory that produces accessibility interfaces for QObjects is + a function of type QAccessible::InterfaceFactory. It is possible + to have several factories installed. The last factory installed + will be the first to be asked for interfaces. + \l{QAccessible::}{queryAccessibleInterface()} uses the factories + to create interfaces for \l{QObject}s. Normally, you need not be + concerned about factories because you can implement plugins that + produce interfaces. We will give examples of both approaches + later. + + \section2 Enabling Accessibility Support + + By default, Qt applications are run with accessibility support + enabled on Windows and Mac OS X. On Unix/X11 platforms, applications + must be launched in an environment with the \c QT_ACCESSIBILITY + variable set to 1. For example, this is set in the following way with + the bash shell: + + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc environment + + Accessibility features are built into Qt by default when the libraries + are configured and built. + + \section1 Implementing Accessibility + + To provide accessibility support for a widget or other user + interface element, you need to implement the QAccessibleInterface + and distribute it in a QAccessiblePlugin. It is also possible to + compile the interface into the application and provide a + QAccessible::InterfaceFactory for it. The factory can be used if + you link statically or do not want the added complexity of + plugins. This can be an advantage if you, for instance, are + delivering a 3-rd party library. + + All widgets and other user interface elements should have + interfaces and plugins. If you want your application to support + accessibility, you will need to consider the following: + + \list + \o Qt already implements accessibility for its own widgets. + We therefore recommend that you use Qt widgets where possible. + \o A QAccessibleInterface needs to be implemented for each element + that you want to make available to accessibility clients. + \o You need to send accessibility events from the custom + user interface elements that you implement. + \endlist + + In general, it is recommended that you are somewhat familiar with + MSAA, which Qt's accessibility support originally was built for. + You should also study the enum values of QAccessible, which + describe the roles, actions, relationships, and events that you + need to consider. + + Note that you can examine how Qt's widgets implement their + accessibility. One major problem with the MSAA standard is that + interfaces are often implemented in an inconsistent way. This + makes life difficult for clients and often leads to guesswork on + object functionality. + + It is possible to implement interfaces by inheriting + QAccessibleInterface and implementing its pure virtual functions. + In practice, however, it is usually preferable to inherit + QAccessibleObject or QAccessibleWidget, which implement part of + the functionality for you. In the next section, we will see an + example of implementing accessibility for a widget by inheriting + the QAccessibleWidget class. + + \section2 The QAccessibleObject and QAccessibleWidget Convenience Classes + + When implementing an accessibility interface for widgets, one would + as a rule inherit QAccessibleWidget, which is a convenience class + for widgets. Another available convenience class, which is + inherited by QAccessibleWidget, is the QAccessibleObject, which + implements part of the interface for QObjects. + + The QAccessibleWidget provides the following functionality: + + \list + \o It handles the navigation of the tree and + hit testing of the objects. + \o It handles events, roles, and actions that are common for all + \l{QWidget}s. + \o It handles action and methods that can be performed on + all widgets. + \o It calculates bounding rectangles with + \l{QAccessibleInterface::}{rect()}. + \o It gives \l{QAccessibleInterface::}{text()} strings that are + appropriate for a generic widget. + \o It sets the \l{QAccessible::State}{states} that + are common for all widgets. + \endlist + + \section2 QAccessibleWidget Example + + Instead of creating a custom widget and implementing an interface + for it, we will show how accessibility can be implemented for one of + Qt's standard widgets: QSlider. Making this widget accessible + demonstrates many of the issues that need to be faced when making + a custom widget accessible. + + The slider is a complex control that functions as a + \l{QAccessible::}{Controller} for its accessible children. + This relationship must be known by the interface (for + \l{QAccessibleInterface::}{relationTo()} and + \l{QAccessibleInterface::}{navigate()}). This can be done + using a controlling signal, which is a mechanism provided by + QAccessibleWidget. We do this in the constructor: + + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 0 + + The choice of signal shown is not important; the same principles + apply to all signals that are declared in this way. Note that we + use QLatin1String to ensure that the signal name is correctly + specified. + + When an accessible object is changed in a way that users need + to know about, it notifies clients of the change by sending them + an event via the accessible interface. This is how QSlider calls + \l{QAccessibleInterface::}{updateAccessibility()} to indicate that + its value has changed: + + \snippet doc/src/snippets/qabstractsliderisnippet.cpp 0 + \dots + \snippet doc/src/snippets/qabstractsliderisnippet.cpp 1 + \dots + \snippet doc/src/snippets/qabstractsliderisnippet.cpp 2 + + Note that the call is made after the value of the slider has + changed because clients may query the new value immediately after + receiving the event. + + The interface must be able to calculate bounding rectangles of + itself and any children that do not provide an interface of their + own. The \c QAccessibleSlider has three such children identified by + the private enum, \c SliderElements, which has the following values: + \c PageLeft (the rectangle on the left hand side of the slider + handle), \c PageRight (the rectangle on the right hand side of the + handle), and \c Position (the slider handle). Here is the + implementation of \l{QAccessibleInterface::}{rect()}: + + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 1 + \dots + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 2 + \dots + + The first part of the function, which we have omitted, uses the + current \l{QStyle}{style} to calculate the slider handle's + bounding rectangle; it is stored in \c srect. Notice that child 0, + covered in the default case in the above code, is the slider itself, + so we can simply return the QSlider bounding rectangle obtained + from the superclass, which is effectively the value obtained from + QAccessibleWidget::rect(). + + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 3 + + Before the rectangle is returned it must be mapped to screen + coordinates. + + The QAccessibleSlider must reimplement + QAccessibleInterface::childCount() since it manages children + without interfaces. + + The \l{QAccessibleInterface::}{text()} function returns the + QAccessible::Text strings for the slider: + + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 4 + + The \c slider() function returns a pointer to the interface's + QSlider. Some values are left for the superclass's implementation. + Not all values are appropriate for all accessible objects, as you + can see for QAccessible::Value case. You should just return an + empty string for those values where no relevant text can be + provided. + + The implementation of the \l{QAccessibleInterface::}{role()} + function is straightforward: + + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 5 + + The role function should be reimplemented by all objects and + describes the role of themselves and the children that do not + provide accessible interfaces of their own. + + Next, the accessible interface needs to return the + \l{QAccessible::State}{states} that the slider can be in. We look + at parts of the \c state() implementation to show how just a few + of the states are handled: + + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 6 + \dots + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 7 + + The superclass implementation of + \l{QAccessibleInterface::}{state()}, uses the + QAccessibleInterface::state() implementation. We simply need to + disable the buttons if the slider is at its minimum or maximum. + + We have now exposed the information we have about the slider to + the clients. For the clients to be able to alter the slider - for + example, to change its value - we must provide information about + the actions that can be performed and perform them upon request. + We discuss this in the next section. + + \section2 Handling Action Requests from Clients + + QAccessible provides a number of \l{QAccessible::}{Action}s + that can be performed on request from clients. If an + accessible object supports actions, it should reimplement the + following functions from QAccessibleInterface: + + \list + \o \l{QAccessibleInterface::}{actionText()} returns + strings that describe each action. The descriptions + to be made available are one for each + \l{QAccessible::}{Text} enum value. + \o \l{QAccessibleInterface::}{doAction()} executes requests + from clients to perform actions. + \endlist + + Note that a client can request any action from an object. If + the object does not support the action, it returns false from + \l{QAccessibleInterface::}{doAction()}. + + None of the standard actions take any parameters. It is possible + to provide user-defined actions that can take parameters. + The interface must then also reimplement + \l{QAccessibleInterface::}{userActionCount()}. Since this is not + defined in the MSAA specification, it is probably only useful to + use this if you know which specific AT-Clients will use the + application. + + QAccessibleInterface gives another technique for clients to handle + accessible objects. It works basically the same way, but uses the + concept of methods in place of actions. The available methods are + defined by the QAccessible::Method enum. The following functions + need to be reimplemented from QAccessibleInterface if the + accessible object is to support methods: + + \list + \o \l{QAccessibleInterface::}{supportedMethods()} returns + a QSet of \l{QAccessible::}{Method} values that are + supported by the object. + \o \l{QAccessibleInterface::}{invokeMethod()} executes + methods requested by clients. + \endlist + + The action mechanism will probably be substituted by providing + methods in place of the standard actions. + + To see examples on how to implement actions and methods, you + could examine the QAccessibleObject and QAccessibleWidget + implementations. You might also want to take a look at the + MSAA documentation. + + \section2 Implementing Accessible Plugins + + In this section we will explain the procedure of implementing + accessible plugins for your interfaces. A plugin is a class stored + in a shared library that can be loaded at run-time. It is + convenient to distribute interfaces as plugins since they will only + be loaded when required. + + Creating an accessible plugin is achieved by inheriting + QAccessiblePlugin, reimplementing \l{QAccessiblePlugin::}{keys()} + and \l{QAccessiblePlugin::}{create()} from that class, and adding + one or two macros. The \c .pro file must be altered to use the + plugin template, and the library containing the plugin must be + placed on a path where Qt searches for accessible plugins. + + We will go through the implementation of \c SliderPlugin, which is an + accessible plugin that produces interfaces for the + QAccessibleSlider we implemented in the \l{QAccessibleWidget Example}. + We start with the \c key() function: + + \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 0 + + We simply need to return the class name of the single interface + our plugin can create an accessible interface for. A plugin + can support any number of classes; just add more class names + to the string list. We move on to the \c create() function: + + \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 1 + + We check whether the interface requested is for the QSlider; if it + is, we create and return an interface for it. Note that \c object + will always be an instance of \c classname. You must return 0 if + you do not support the class. + \l{QAccessible::}{updateAccessibility()} checks with the + available accessibility plugins until it finds one that does not + return 0. + + Finally, you need to include macros in the cpp file: + + \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 2 + + The Q_EXPORT_PLUGIN2 macro exports the plugin in the \c + SliderPlugin class into the \c acc_sliderplugin library. The first + argument is the name of the plugin library file, excluding the + file suffix, and the second is the class name. For more information + on plugins, consult the plugins \l{How to Create Qt + Plugins}{overview document}. + + You can omit the first macro unless you want the plugin + to be statically linked with the application. + + \section2 Implementing Interface Factories + + If you do not want to provide plugins for your accessibility + interfaces, you can use an interface factory + (QAccessible::InterfaceFactory), which is the recommended way to + provide accessible interfaces in a statically-linked application. + + A factory is a function pointer for a function that takes the same + parameters as \l{QAccessiblePlugin}'s + \l{QAccessiblePlugin::}{create()} - a QString and a QObject. It + also works the same way. You install the factory with the + \l{QAccessible::}{installFactory()} function. We give an example + of how to create a factory for the \c SliderPlugin class: + + \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 0 + \dots + \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 1 + + \omit + + \section1 Implementing Bridges for Other Assistive Technologies + + An accessibility bridge provides the means for an assistive + technology to talk to Qt. On Windows and Mac, the built-in bridges + will be used. On UNIX, however, there are no built-in standard + assistive technology, and it might therefore be necessary to + implement an accessible bridge. + + A bridge is implemented by inheriting QAccessibleBridge for the + technology to support. The class defines the interface that Qt + needs an assistive technology to support: + + \list + \o A root object. This is the root in the accessible + object tree and is of type QAccessibleInterface. + \o Receive events from from accessible objects. + \endlist + + The root object is set with the + \l{QAccessibleBridge::}{setRootObject()}. In the case of Qt, this + will always be an interface for the QApplication instance of the + application. + + Event notification is sent through + \l{QAccessibleBridge::}{notifyAccessibilityUpdate()}. This + function is called by \l{QAccessible::}{updateAccessibility()}. Even + though the bridge needs only to implement these two functions, it + must be able to communicate the entire QAccessibleInterface to the + underlying technology. How this is achieved is, naturally, up to + the individual bridge and none of Qt's concern. + + As with accessible interfaces, you distribute accessible bridges + in plugins. Accessible bridge plugins are subclasses of the + QAccessibleBridgePlugin class; the class defines the functions + \l{QAccessibleBridgePlugin::}{create()} and + \l{QAccessibleBridgePlugin::}{keys()}, which must me + reimplemented. If Qt finds a built-in bridge to use, it will + ignore any available plugins. + + \endomit + + \section1 Further Reading + + The \l{Cross-Platform Accessibility Support in Qt 4} document contains a more + general overview of Qt's accessibility features and discusses how it is + used on each platform. + issues +*/ diff --git a/doc/src/frameworks-technologies/activeqt-container.qdoc b/doc/src/frameworks-technologies/activeqt-container.qdoc new file mode 100644 index 000000000..79515bfa1 --- /dev/null +++ b/doc/src/frameworks-technologies/activeqt-container.qdoc @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page activeqt-container.html + \title Using ActiveX controls and COM objects in Qt + + \brief The QAxContainer module is a Windows-only extension for + accessing ActiveX controls and COM objects. + + The QAxContainer module is part of the \l ActiveQt framework. It + provides a library implementing a QWidget subclass, QAxWidget, + that acts as a container for ActiveX controls, and a QObject + subclass, QAxObject, that can be used to easily access non-visual + COM objects. Scripting COM objects embedded using these classes + is possible through the QAxScript, QAxScriptManager and + QAxScriptEngine classes, and a set of \l{Tools for ActiveQt}{tools} + makes it easy to access COM objects programmatically. + + The module consists of six classes + \list 1 + \o QAxBase is an abstract class that provides an API to initialize + and access a COM object or ActiveX control. + \o QAxObject provides a QObject that wraps a COM object. + \o QAxWidget is a QWidget that wraps an ActiveX control. + \o QAxScriptManager, QAxScript and QAxScriptEngine provide an + interface to the Windows Script Host. + \endlist + + Some \l{ActiveQt Examples}{example applications} that use + standard ActiveX controls to provide high-level user interface + functionality are provided. + + \sa {ActiveQt Framework} + + Topics: + + \tableofcontents + + \section1 Using the Library + + To build Qt applications that can host COM objects and ActiveX controls + link the application against the QAxContainer module by adding + + \snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 0 + + to your application's \c .pro file. + + \section2 Distributing QAxContainer Applications + + The QAxContainer library is static, so there is no need to redistribute + any additional files when using this module. Note however that the + ActiveX server binaries you are using might not be installed on the + target system, so you have to ship them with your package and register + them during the installation process of your application. + + \section1 Instantiating COM Objects + + To instantiate a COM object use the QAxBase::setControl() API, or pass + the name of the object directly into the constructor of the QAxBase + subclass you are using. + + The control can be specified in a variety of formats, but the fastest + and most powerful format is to use the class ID (CLSID) of the object + directly. The class ID can be prepended with information about a remote + machine that the object should run on, and can include a license key + for licensed controls. + + \section2 Typical Error Messages + + ActiveQt prints error messages to the debug output when it + encounters error situations at runtime. Usually you must run + your program in the debugger to see these messages (e.g. in Visual + Studio's Debug output). + + \section3 Requested control could not be instantiated + + The control requested in QAxBase::setControl() is not installed + on this system, or is not accessible for the current user. + + The control might require administrator rights, or a license key. + If the control is licensed, pass the license key to QAxBase::setControl + as documented. + + \section1 Accessing the Object API + + ActiveQt provides a Qt API to the COM object, and replaces COM + datatypes with Qt equivalents. + + There are four ways to call APIs on the COM object: + + \list + \o Generating a C++ namespace + \o Call-by-name + \o Through a script engine + \o Using the native COM interfaces + \endlist + + \section2 Generating a C++ Namespace + + To generate a C++ namespace for the type library you want to access, + use the \l dumpcpp tool. Run this tool manually on the type library you + want to use, or integrate it into the build system by adding the type + libraries to the \c TYPELIBS variable in your application's \c .pro file: + + \snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 1 + + Note that \l dumpcpp might not be able to expose all APIs in the type + library. + + Include the resulting header file in your code to access the + object APIs through the generated C++ classes. See the + \l{activeqt/qutlook}{Qutlook} example for more information. + + \section2 Call-by-Name + + Use QAxBase::dynamicCall() and QAxBase::querySubObject() as well as + the QObject::setProperty() and QObject::property() APIs to call the + methods and properties of the COM object through their name. Use the + \l dumpdoc tool to get the documentation of the Qt API for any COM + object and its subobjects; note that not all of the COM object's APIs + might be available. + + See the \l{activeqt/webbrowser}{Webbrowser} example for more information. + + \section2 Calling Function Through a Script Engine + + A Qt application can host any ActiveScript engine installed on the system. + The script engine can then run script code that accesses the COM objects. + + To instantiate a script engine, use QAxScriptManager::addObject() to + register the COM objects you want to access from script, and + QAxScriptManager::load() to load the script code into the engine. Then + call the script functions using QAxScriptManager::call() or + QAxScript::call(). + + Which APIs of the COM object are available through scripting depends on + the script language used. + + The \l{testcon - An ActiveX Test Container (ActiveQt)}{ActiveX Test Container} + demonstrates loading of script files. + + \section2 Calling a Function Using the Native COM Interfaces + + To call functions of the COM object that can not be accessed via any + of the above methods it is possible to request the COM interface directly + using QAxBase::queryInterface(). To get a C++ definition of the respective + interface classes use the \c #import directive with the type library + provided with the control; see your compiler manual for details. + + \section2 Typical Error Messages + + ActiveQt prints error messages to the debug output when it + encounters error situations at runtime. Usually you must run + your program in the debugger to see these messages (e.g. in Visual + Studio's Debug output). + + \section3 QAxBase::internalInvoke: No such method + + A QAxBase::dynamicCall() failed - the function prototype did not + match any function available in the object's API. + + \section3 Error calling IDispatch member: Non-optional parameter missing + + A QAxBase::dynamicCall() failed - the function prototype was correct, + but too few parameters were provided. + + \section3 Error calling IDispatch member: Type mismatch in parameter n + + A QAxBase::dynamicCall() failed - the function prototype was correct, + but the paramter at index \c n was of the wrong type and could + not be coerced to the correct type. + + \section3 QAxScriptManager::call(): No script provides this function + + You try to call a function that is provided through an engine + that doesn't provide introspection (ie. ActivePython or + ActivePerl). You need to call the function directly on the + respective QAxScript object. +*/ diff --git a/doc/src/frameworks-technologies/activeqt-server.qdoc b/doc/src/frameworks-technologies/activeqt-server.qdoc new file mode 100644 index 000000000..89456bf03 --- /dev/null +++ b/doc/src/frameworks-technologies/activeqt-server.qdoc @@ -0,0 +1,856 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page activeqt-server.html + \title Building ActiveX servers and controls with Qt + + \brief The QAxServer module is a Windows-only static library that + you can use to turn a standard Qt binary into a COM server. + + The QAxServer module is part of the \l ActiveQt framework. It + consists of three classes: + + \list + \o QAxFactory defines a factory for the creation of COM objects. + \o QAxBindable provides an interface between the Qt widget and the + COM object. + \o QAxAggregated can be subclassed to implement additional COM interfaces. + \endlist + + Some \l{ActiveQt Examples}{example implementations} of ActiveX + controls and COM objects are provided. + + \sa {ActiveQt Framework} + + Topics: + + \tableofcontents + + \section1 Using the Library + + To turn a standard Qt application into a COM server using the + QAxServer library you must add \c qaxserver as a CONFIG setting + in your \c .pro file. + + An out-of-process executable server is generated from a \c .pro + file like this: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 0 + + To build an in-process server, use a \c .pro file like this: + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 1 + + The files \c qaxserver.rc and \c qaxserver.def are part of the + framework and can be used from their usual location (specify a + path in the \c .pro file), or copied into the project directory. + You can modify these files as long as it includes any file as the + type library entry, ie. you can add version information or specify + a different toolbox icon. + + The \c qaxserver configuration will cause the \c qmake tool to add the + required build steps to the build system: + + \list + \o Link the binary against \c qaxserver.lib instead of \c qtmain.lib + \o Call the \l idc tool to generate an IDL file for the COM server + \o Compile the IDL into a type library using the MIDL tool (part of the + compiler installation) + \o Attach the resulting type library as a binary resource to the server + binary (again using the \l idc tool) + \o Register the server + \endlist + + Note that the QAxServer build system is not supported on Windows 98/ME + (attaching of resources to a binary is not possible there), but a server + built on Windows NT/2000/XP will work on previous Windows versions as well. + + To skip the post-processing step, also set the \c qaxserver_no_postlink + configuration. + + Additionally you can specify a version number using the \c VERSION + variable, e.g. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 2 + + The version number specified will be used as the version of the type + library and of the server when registering. + + \section2 Out-of-Process vs. In-Process + + Whether your COM server should run as a stand-alone executable + or as a shared library in the client process depends mainly on the + type of COM objects you want to provide in the server. + + An executable server has the advantage of being able to run as a + stand-alone application, but adds considerable overhead to the + communication between the COM client and the COM object. If the + control has a programming error only the server process running + the control will crash, and the client application will probably + continue to run. Not all COM clients support executable servers. + + An in-process server is usually smaller and has faster startup + time. The communication between client and server is done directly + through virtual function calls and does not introduce the overhead + required for remote procedure calls. However, if the server crashes the + client application is likely to crash as well, and not every + functionality is available for in-process servers (i.e. register in + the COM's running-object-table). + + Both server types can use Qt either as a shared library, or statically + linked into the server binary. + + \section2 Typical Errors During the Post-Build Steps + + For the ActiveQt specific post-processing steps to work the + server has to meet some requirements: + + \list + \o All controls exposed can be created with nothing but a QApplication + instance being present + \o The initial linking of the server includes a temporary type + library resource + \o All dependencies required to run the server are in the system path + (or in the path used by the calling environment; note that Visual + Studio has its own set of environment variables listed in the + Tools|Options|Directories dialog). + \endlist + + If those requirements are not met one ore more of the following + errors are likely to occur: + + \section3 The Server Executable Crashes + + To generate the IDL the widgets exposed as ActiveX controls need to + be instantiated (the constructor is called). At this point, nothing + else but a QApplication object exists. Your widget constructor must + not rely on any other objects to be created, e.g. it should check for + null-pointers. + + To debug your server run it with -dumpidl outputfile and check where + it crashes. + + Note that no functions of the control are called. + + \section3 The Server Executable Is Not a Valid Win32 Application + + Attaching the type library corrupted the server binary. This is a + bug in Windows and happens only with release builds. + + The first linking step has to link a dummy type library into the + executable that can later be replaced by idc. Add a resource file + with a type library to your project as demonstrated in the examples. + + \section3 "Unable to locate DLL" + + The build system needs to run the server executable to generate + the interface definition, and to register the server. If a dynamic + link library the server links against is not in the path this + might fail (e.g. Visual Studio calls the server using the + enivronment settings specified in the "Directories" option). Make + sure that all DLLs required by your server are located in a + directory that is listed in the path as printed in the error + message box. + + \section3 "Cannot open file ..." + + The ActiveX server could not shut down properly when the last + client stopped using it. It usually takes about two seconds for + the application to terminate, but you might have to use the task + manager to kill the process (e.g. when a client doesn't release + the controls properly). + + \section1 Implementing Controls + + To implement a COM object with Qt, create a subclass of QObject + or any existing QObject subclass. If the class is a subclass of QWidget, + the COM object will be an ActiveX control. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 3 + + The Q_OBJECT macro is required to provide the meta object information + about the widget to the ActiveQt framework. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 4 + + Use the Q_CLASSINFO() macro to specify the COM identifiers for the COM + object. \c ClassID and \c InterfaceID are required, while \c EventsID is + only necessary when your object has signals. To generate these identifiers, + use system tools like \c uuidgen or \c guidgen. + + You can specify additional attributes for each of your classes; see + \l{Class Information and Tuning} for details. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 5 + + Use the Q_PROPERTY() macro to declare properties for the ActiveX control. + + Declare a standard constructor taking a parent object, and functions, + signals and slots like for any QObject subclass. + \footnote + If a standard constructor is not present the compiler will issue + an error "no overloaded function takes 2 parameters" when using + the default factory through the QAXFACTORY_DEFAULT() macro. If you + cannot provide a standard constructor you must implement a + QAxFactory custom factory and call the constructor you have in + your implementation of QAxFactory::create. + \endfootnote + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 6 + + The ActiveQt framework will expose properties and public slots as ActiveX + properties and methods, and signals as ActiveX events, and convert between + the Qt data types and the equivalent COM data types. + + \section2 Data Types + + The Qt data types that are supported for properties are: + + \table + \header + \o Qt data type + \o COM property + \row + \o bool + \o VARIANT_BOOL + \row + \o QString + \o BSTR + \row + \o int + \o int + \row + \o uint + \o unsigned int + \row + \o double + \o double + \row + \o \l qlonglong + \o CY + \row + \o \l qulonglong + \o CY + \row + \o QColor + \o OLE_COLOR + \row + \o QDate + \o DATE + \row + \o QDateTime + \o DATE + \row + \o QTime + \o DATE + \row + \o QFont + \o IFontDisp* + \row + \o QPixmap + \o IPictureDisp* + \footnote + COM cannot marshal IPictureDisp accross process boundaries, + so QPixmap properties cannot be called for out-of-process servers. You + can however marshal the image data via e.g. temporary files. See the + Microsoft + \link http://support.microsoft.com/default.aspx?scid=kb;[LN];Q150034 KB article + Q150034 \endlink for more information. + \endfootnote + \row + \o QVariant + \o VARIANT + \row + \o QVariantList (same as QList\<QVariant\>) + \o SAFEARRAY(VARIANT) + \row + \o QStringList + \o SAFEARRAY(BSTR) + \row + \o QByteArray + \o SAFEARRAY(BYTE) + \row + \o QRect + \o User defined type + \row + \o QSize + \o User defined type + \row + \o QPoint + \o User defined type + \endtable + + The Qt data types that are supported for parameters in signals and + slots are: + \table + \header + \o Qt data type + \o COM parameter + \row + \o bool + \o [in] VARIANT_BOOL + \row + \o bool& + \o [in, out] VARIANT_BOOL* + \row + \o QString, const QString& + \o [in] BSTR + \row + \o QString& + \o [in, out] BSTR* + \row + \o QString& + \o [in, out] BSTR* + \row + \o int + \o [in] int + \row + \o int& + \o [in,out] int + \row + \o uint + \o [in] unsigned int + \row + \o uint& + \o [in, out] unsigned int* + \row + \o double + \o [in] double + \row + \o double& + \o [in, out] double* + \row + \o QColor, const QColor& + \o [in] OLE_COLOR + \row + \o QColor& + \o [in, out] OLE_COLOR* + \row + \o QDate, const QDate& + \o [in] DATE + \row + \o QDate& + \o [in, out] DATE* + \row + \o QDateTime, const QDateTime& + \o [in] DATE + \row + \o QDateTime& + \o [in, out] DATE* + \row + \o QFont, const QFont& + \o [in] IFontDisp* + \row + \o QFont& + \o [in, out] IFontDisp** + \row + \o QPixmap, const QPixmap& + \o [in] IPictureDisp* + \row + \o QPixmap& + \o [in, out] IPictureDisp** + \row + \o QList\<QVariant\>, const QList\<QVariant\>& + \o [in] SAFEARRAY(VARIANT) + \row + \o QList\<QVariant\>& + \o [in, out] SAFEARRAY(VARIANT)* + \row + \o QStringList, const QStringList& + \o [in] SAFEARRAY(BSTR) + \row + \o QStringList& + \o [in, out] SAFEARRAY(BSTR)* + \row + \o QByteArray, const QByteArray& + \o [in] SAFEARRAY(BYTE) + \row + \o QByteArray& + \o [in, out] SAFEARRAY(BYTE)* + \row + \o QObject* + \o [in] IDispatch* + \row + \o QRect& + \footnote + OLE needs to marshal user defined types by reference (ByRef), and cannot + marshal them by value (ByVal). This is why const-references and object + parameters are not supported for QRect, QSize and QPoint. Also note that + servers with this datatype require Windows 98 or DCOM 1.2 to be installed. + \endfootnote + \o [in, out] struct QRect (user defined) + \row + \o QSize& + \o [in, out] struct QSize (user defined) + \row + \o QPoint& + \o [in, out] struct QPoint (user defined) + \endtable + + Also supported are exported enums and flags (see Q_ENUMS() and + Q_FLAGS()). The in-parameter types are also supported as + return values. + + Properties and signals/slots that have parameters using any other + data types are ignored by the ActiveQt framework. + + \section2 Sub-Objects + + COM objects can have multiple sub-objects that can represent a sub element + of the COM object. A COM object representing a multi-document spread sheet + application can for example provide one sub-object for each spread sheet. + + Any QObject subclass can be used as the type for a sub object in ActiveX, as + long as it is known to the QAxFactory. Then the type can be used in properties, + or as the return type or paramter of a slot. + + \section2 Property Notification + + To make the properties bindable for the ActiveX client, use multiple + inheritance from the QAxBindable class: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 7 + + When implementing the property write functions, use the + QAxBindable class's requestPropertyChange() and propertyChanged() + functions to allow ActiveX clients to bind to the control + properties. + \footnote + This is not required, but gives the client more control over + the ActiveX control. + \endfootnote + + \section1 Serving Controls + + To make a COM server available to the COM system it must be registered + in the system registry using five unique identifiers. + These identifiers are provided by tools like \c guidgen or \c uuidgen. + The registration information allows COM to localize the binary providing + a requested ActiveX control, marshall remote procedure calls to the + control and read type information about the methods and properties exposed + by the control. + + To create the COM object when the client asks for it the server must export + an implementation of a QAxFactory. The easist way to do this is to use a set + of macros: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 8 + + This will export \c MyWidget and \c MyWidget2 as COM objects that can be + created by COM clients, and will register \c MySubType as a type that can + be used in properties and parameters of \c MyWidget and \c MyWidget2. + + The \link QAxFactory QAxFactory class documentation \endlink explains + how to use this macro, and how to implement and use custom factories. + + For out-of-process executable servers you can implement a main() + function to instantiate a QApplication object and enter the event + loop just like any normal Qt application. By default the + application will start as a standard Qt application, but if you + pass \c -activex on the command line it will start as an ActiveX + server. Use QAxFactory::isServer() to create and run a standard + application interface, or to prevent a stand-alone execution: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 9 + + This is however not necessary as ActiveQt provides a default implementation + of a main function. The default implemenation calls QAxFactory::startServer(), + creates a QApplication instance and calls exec(). + + To build the ActiveX server executable run \c qmake + to generate the makefile, and use your compiler's + make tool as for any other Qt application. The make process will + also register the controls in the system registry by calling the + resulting executable with the \c -regserver command line option. + + If the ActiveX server is an executable, the following command line + options are supported: + \table + \header \o Option \o Result + \row \o \c -regserver \o Registers the server in the system registry + \row \o \c -unregserver \o Unregisters the server from the system registry + \row \o \c -activex \o Starts the application as an ActiveX server + \row \o \c{-dumpidl <file> -version x.y} \o Writes the server's IDL to the + specified file. The type library will have version x.y + \endtable + + In-process servers can be registered using the \c regsvr32 tool available + on all Windows systems. + + \section2 Typical Compile-Time Problems + + The compiler/linker errors listed are based on those issued by the + Microsoft Visual C++ 6.0 compiler. + + \section3 "No overloaded function takes 2 parameters" + + When the error occurs in code that uses the QAXFACTORY_DEFAULT() + macro, the widget class had no constructor that can be used by the + default factory. Either add a standard widget constructor or + implement a custom factory that doesn't require one. + + When the error occurs in code that uses the QAXFACTORY_EXPORT() + macro, the QAxFactory subclass had no appropriate constructor. + Provide a public class constructor like + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 10 + + for your factory class. + + \section3 "Syntax error: bad suffix on number" + + The unique identifiers have not been passed as strings into the + QAXFACTORY_EXPORT() or QAXFACTORY_DEFAULT() macro. + + \section3 "Unresolved external symbol _ucm_instantiate" + + The server does not export an implementation of a QAxFactory. Use + the QAXFACTORY_EXPORT() macro in one of the project's + implementation files to instantiate and export a factory, or use + the QAXFACTORY_DEFAULT() macro to use the default factory. + + \section3 "_ucm_initialize already defined in ..." + + The server exports more than one implementation of a QAxFactory, + or exports the same implementation twice. If you use the default + factory, the QAXFACTORY_DEFAULT() macro must only be used once in + the project. Use a custom QAxFactory implementation and the + QAXFACTORY_EXPORT() macro if the server provides multiple ActiveX + controls. + + \section2 Distributing QAxServer Binaries + + ActiveX servers written with Qt can use Qt either as a shared + library, or have Qt linked statically into the binary. Both ways + will produce rather large packages (either the server binary + itself becomes large, or you have to ship the Qt DLL). + + \section3 Installing Stand-Alone Servers + + When your ActiveX server can also run as a stand-alone application, + run the server executable with the \c -regserver command line + parameter after installing the executable on the target system. + After that the controls provided by the server will be available to + ActiveX clients. + + \section3 Installing In-Process Servers + + When your ActiveX server is part of an installation package, use the + \c regsvr32 tool provided by Microsoft to register the controls on + the target system. If this tool is not present, load the DLL into + your installer process, resolve the \c DllRegisterServer symbol and + call the function: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 11 + + \section3 Distributing Servers over the Internet + + If you want to use controls in your server in web-pages you need to + make the server available to the browser used to view your page, and + you need to specify the location of the server package in your page. + + To specify the location of a server, use the CODEBASE attribute in + the OBJECT tag of your web-site. The value can point to the server + file itself, to an INF file listing other files the server requires + (e.g. the Qt DLL), or a compressed CAB archive. + + INF and CAB files are documented in almost every book available about + ActiveX and COM programming as well as in the MSDN library and various + other Online resources. The examples include INF files that can be used + to build CAB archives: + + \snippet examples/activeqt/simple/simple.inf 0 + + The CABARC tool from Microsoft can easily generate CAB archives: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 12 + + The INF files assume a static build of Qt, so no dependencies to other DLLs + are listed in the INF files. To distribute an ActiveX server depending on + DLLs you must add the dependencies, and provide the library files + with the archive. + + \section1 Using the Controls + + To use the ActiveX controls, e.g. to embed them in a web page, use + the \c <object> HTML tag. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 13 + + To initialize the control's properties, use + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 14 + + If the web browser supports scripting use JavaScript, VBScript + and forms to script the control. The + \l{ActiveQt Examples} include demonstration HTML pages for the example + controls. + + \section2 Supported and Unsupported ActiveX Clients + + The following is largly based on our own experiements with ActiveX + controls and client applications, and is by no means complete. + + \section3 Supported Clients + + These standard applications work with ActiveX controls developed with + ActiveQt. Note that some clients support only in-process controls. + + \list + \o Internet Explorer + \o Microsoft ActiveX Control Test Container + \o Microsoft Visual Studio 6.0 + \o Microsoft Visual Studio.NET/2003 + \o Microsoft Visual Basic 6.0 + \o MFC- and ATL-based containers + \o Sybase PowerBuilder + \o ActiveQt based containers + \endlist + + Microsoft Office applications are supported, but you need to register + the controls as "Insertable" objects. Reimplement QAxFactory::registerClass + to add this attribute to the COM class, or set the "Insertable" class info + for your class to "yes" using the Q_CLASSINFO macro. + + \section3 Unsupported Clients + + We have not managed to make ActiveQt based COM objects work with the + following client applications. + + \list + \o Borland C++ Builder (Versions 5 and 6) + \o Borland Delphi + \endlist + + \section2 Typical Runtime Errors + + \section3 The Server Does Not Respond + + If the system is unable to start the server (check with the task + manager whether the server runs a process), make sure that no DLL + the server depends on is missing from the system path (e.g. the Qt + DLL!). Use a dependency walker to view all dependencies of the server + binary. + + If the server runs (e.g. the task manager lists a process), see + the following section for information on debugging your server. + + \section3 The Object Cannot Be Created + + If the server could be built and registered correctly during the build + process, but the object cannot be initiliazed e.g. by the OLE/COM Object + Viewer application, make sure that no DLL the server depends on is + missing from the system path (e.g. the Qt DLL). Use a dependency walker + to view all dependencies of the server binary. + + If the server runs, see the following section for information on + debugging your server. + + \section2 Debugging Runtime Errors + + To debug an in-process server in Visual Studio, set the server project + as the active project, and specify a client "executable for debug + session" in the project settings (e.g. use the ActiveX Test Container). + You can set breakpoints in your code, and also step into ActiveQt and + Qt code if you installed the debug version. + + To debug an executable server, run the application in a debugger + and start with the command line parameter \c -activex. Then start + your client and create an instance of your ActiveX control. COM + will use the existing process for the next client trying to create + an ActiveX control. + + \section1 Class Information and Tuning + + To provide attributes for each COM class, use the Q_CLASSINFO macro, which is part of + Qt's meta object system. + + \table + \header + \o Key + \o Meaning of value + \row + \o Version + \o The version of the class (1.0 is default) + \row + \o Description + \o A string describing the class. + \row + \o ClassID + \o The class ID. + You must reimplement QAxFactory::classID if not specified. + \row + \o InterfaceID + \o The interface ID. + You must reimplement QAxFactory::interfaceID if not specified. + \row + \o EventsID + \o The event interface ID. + No signals are exposed as COM events if not specified. + \row + \o DefaultProperty + \o The property specified represents the default property of this class. + Ie. the default property of a push button would be "text". + \row + \o DefaultSignal + \o The signal specified respresents the default signal of this class. + Ie. the default signal of a push button would be "clicked". + \row + \o LicenseKey + \o Object creation requires the specified license key. The key can be + empty to require a licensed machine. By default classes are not + licensed. Also see the following section. + \row + \o StockEvents + \o Objects expose stock events if value is "yes". + See \l QAxFactory::hasStockEvents() + \row + \o ToSuperClass + \o Objects expose functionality of all super-classes up to and + including the class name in value. + See \l QAxFactory::exposeToSuperClass() + \row + \o Insertable + \o If the value is "yes" the class is registered to be "Insertable" + and will be listed in OLE 2 containers (ie. Microsoft Office). This + attribute is not be set by default. + \row + \o Aggregatable + \o If the value is "no" the class does not support aggregation. By + default aggregation is supported. + \row + \o Creatable + \o If the value is "no" the class cannot be created by the client, + and is only available through the API of another class (ie. the + class is a sub-type). + \row + \o RegisterObject + \o If the value is "yes" objects of this class are registered with + OLE and accessible from the running object table (ie. clients + can connect to an already running instance of this class). This + attribute is only supported in out-of-process servers. + \row + \o MIME + \o The object can handle data and files of the format specified in the + value. The value has the format mime:extension:description. Multiple + formats are separated by a semicolon. + \row + \o CoClassAlias + \o The classname used in the generated IDL and in the registry. This is + esp. useful for C++ classes that live in a namespace - by default, + ActiveQt just removes the "::" to make the IDL compile. + \endtable + + Note that both keys and values are case sensitive. + + The following declares version 2.0 of a class that exposes only its + own API, and is available in the "Insert Objects" dialog of Microsoft + Office applications. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 15 + + \section2 Developing Licensed Components + + If you develop components you might want to control who is able to instantiate + those components. Since the server binary can be shipped to and registered on + any client machine it is possible for anybody to use those components in his + own software. + + Licensing components can be done using a variety of techniques, e.g. the code + creating the control can provide a license key, or the machine on which the + control is supposed to run needs to be licensed. + + To mark a Qt class as licensed specify a "LicenseKey" using the + Q_CLASSINFO() macro. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 16 + + The key is required to be able to create an instance of \c MyLicensedControl + on a machine that is not licensed itself. The licensed developer can now + redistributes the server binary with his application, which creates the control + using the value of "LicenseKey", while users of the application cannot create + the control without the license key. + + If a single license key for the control is not sufficient (ie. you want + differnet developers to receive different license keys) you can specify an + empty key to indicate that the control requires a license, and reimplement + \l QAxFactory::validateLicenseKey() to verify that a license exists on the + system (ie. through a license file). + + \section2 More Interfaces + + ActiveX controls provided by ActiveQt servers support a minimal set of COM + interfaces to implement the OLE specifications. When the ActiveX class inherits + from the QAxBindable class it can also implement additional COM interfaces. + + Create a new subclass of QAxAggregated and use multiple inheritance + to subclass additional COM interface classes. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 17 + + Reimplement the QAxAggregated::queryInterface() function to + support the additional COM interfaces. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 18 + + Since \c ISomeCOMInterface is a subclass of \c IUnknown you will + have to implement the \c QueryInterface(), \c AddRef(), and \c + Release() functions. Use the QAXAGG_IUNKNOWN macro in your + class definition to do that. If you implement the \c IUnknown + functions manually, delegate the calls to the interface pointer + returned by the QAxAggregated::controllingUnknown() function, + e.g. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 19 + + Do not support the \c IUnknown interface itself in your + \l{QAxAggregated::queryInterface()}{queryInterface()} + implementation. + + Implement the methods of the COM interfaces, and use QAxAggregated::object() + if you need to make calls to the QObject subclass implementing the control. + + In your QAxBindable subclass, implement + QAxBindable::createAggregate() to return a new object of the + QAxAggregated subclass. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 20 +*/ diff --git a/doc/src/frameworks-technologies/activeqt.qdoc b/doc/src/frameworks-technologies/activeqt.qdoc new file mode 100644 index 000000000..a0c009f6c --- /dev/null +++ b/doc/src/frameworks-technologies/activeqt.qdoc @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group activeqt-tools + \title Tools for ActiveQt + \brief Tools to help integrate Qt applications with ActiveX components. + + These tools provide support for integrating Qt with ActiveX components. + + \generatelist{related} + + \sa {ActiveQt Framework} +*/ + +/*! + \page activeqt.html + \title ActiveQt Framework + \brief An overview of Qt's ActiveX and COM integration on Windows. + + \ingroup platform-specific + \keyword ActiveQt + + Qt's ActiveX and COM support allows Qt for Windows developers to: + + \list 1 + \o Access and use ActiveX controls and COM objects provided by any + ActiveX server in their Qt applications. + \o Make their Qt applications available as COM servers, with + any number of Qt objects and widgets as COM objects and ActiveX + controls. + \endlist + + The ActiveQt framework consists of two modules: + + \list + \o The \l QAxContainer module is a static + library implementing QObject and QWidget subclasses, QAxObject and + QAxWidget, that act as containers for COM objects and ActiveX + controls. + \o The \l QAxServer module is a static library that implements + functionality for in-process and executable COM servers. This + module provides the QAxAggregated, QAxBindable and QAxFactory + classes. + \endlist + + To build the static libraries, change into the \c activeqt directory + (usually \c QTDIR/src/activeqt), and run \c qmake and your make + tool in both the \c container and the \c control subdirectory. + The libraries \c qaxcontainer.lib and \c qaxserver.lib will be linked + into \c QTDIR/lib. + + If you are using a shared configuration of Qt enter the \c plugin + subdirectory and run \c qmake and your make tool to build a + plugin that integrates the QAxContainer module into \l{Qt + Designer}. + + The ActiveQt modules are part of the \l{Qt Full Framework Edition} and + the \l{Open Source Versions of Qt}. + + \sa {QAxContainer Module}, {QAxServer Module} +*/ diff --git a/doc/src/frameworks-technologies/animation.qdoc b/doc/src/frameworks-technologies/animation.qdoc new file mode 100644 index 000000000..cd6e3046c --- /dev/null +++ b/doc/src/frameworks-technologies/animation.qdoc @@ -0,0 +1,377 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group animation + \title Animation Framework +*/ + +/*! + \page animation-overview.html + \title The Animation Framework + + \brief An overview of the Animation Framework + + \ingroup frameworks-technologies + + \keyword Animation + + The animation framework is part of the Kinetic project, and aims + to provide an easy way for creating animated and smooth GUI's. By + animating Qt properties, the framework provides great freedom for + animating widgets and other \l{QObject}s. The framework can also + be used with the Graphics View framework. + + In this overview, we explain the basics of its architecture. We + also show examples of the most common techniques that the + framework allows for animating QObjects and graphics items. + + \tableofcontents + + \section1 The Animation Architecture + + We will in this section take a high-level look at the animation + framework's architecture and how it is used to animate Qt + properties. The following diagram shows the most important classes + in the animation framework. + + \image animations-architecture.png + + The animation framework foundation consists of the base class + QAbstractAnimation, and its two subclasses QVariantAnimation and + QAnimationGroup. QAbstractAnimation is the ancestor of all + animations. It represents basic properties that are common for all + animations in the framework; notably, the ability to start, stop, + and pause an animation. It is also receives the time change + notifications. + + The animation framework further provides the QPropertyAnimation + class, which inherits QVariantAnimation and performs animation of + a Qt property, which is part of Qt's \l{Meta-Object + System}{meta-object system}. The class performs an interpolation + over the property using an easing curve. So when you want to + animate a value, you can declare it as a property and make your + class a QObject. Note that this gives us great freedom in + animating already existing widgets and other \l{QObject}s. + + Complex animations can be constructed by building a tree structure + of \l{QAbstractAnimation}s. The tree is built by using + \l{QAnimationGroup}s, which function as containers for other + animations. Note also that the groups are subclasses of + QAbstractAnimation, so groups can themselves contain other groups. + + The animation framework can be used on its own, but is also + designed to be part of the state machine framework (See the + \l{The State Machine Framework}{state machine framework} for an + introduction to the Qt state machine). The state machine provides + a special state that can play an animation. A QState can also set + properties when the state is entered or exited, and this special + animation state will interpolate between these values when given a + QPropertyAnimation. We will look more closely at this later. + + Behind the scenes, the animations are controlled by a global + timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to + all animations that are playing. + + For detailed descriptions of the classes' function and roles in + the framework, please look up their class descriptions. + + \section1 Classes in the Animation Framework + + These classes provide a framework for creating both simple and complex + animations. + + \annotatedlist animation + + \section1 Animating Qt Properties + + As mentioned in the previous section, the QPropertyAnimation class + can interpolate over Qt properties. It is this class that should + be used for animation of values; in fact, its superclass, + QVariantAnimation, is an abstract class, and cannot be used + directly. + + A major reason we chose to animate Qt properties is that it + presents us with freedom to animate already existing classes in + the Qt API. Notably, the QWidget class (which we can also embed in + a QGraphicsView) has properties for its bounds, colors, etc. + Let's look at a small example: + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation animation(&button, "geometry"); + animation.setDuration(10000); + animation.setStartValue(QRect(0, 0, 100, 30)); + animation.setEndValue(QRect(250, 250, 100, 30)); + + animation.start(); + \endcode + + This code will move \c button from the top left corner of the + screen to the position (250, 250) in 10 seconds (10000 milliseconds). + + The example above will do a linear interpolation between the + start and end value. It is also possible to set values + situated between the start and end value. The interpolation + will then go by these points. + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation animation(&button, "geometry"); + animation.setDuration(10000); + + animation.setKeyValueAt(0, QRect(0, 0, 100, 30)); + animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30)); + animation.setKeyValueAt(1, QRect(0, 0, 100, 30)); + + animation.start(); + \endcode + + In this example, the animation will take the button to (250, 250) + in 8 seconds, and then move it back to its original position in + the remaining 2 seconds. The movement will be linearly + interpolated between these points. + + You also have the possibility to animate values of a QObject + that is not declared as a Qt property. The only requirement is + that this value has a setter. You can then subclass the class + containing the value and declare a property that uses this setter. + Note that each Qt property requires a getter, so you will need to + provide a getter yourself if this is not defined. + + \code + class MyGraphicsRectItem : public QObject, public QGraphicsRectItem + { + Q_OBJECT + Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry) + }; + \endcode + + In the above code example, we subclass QGraphicsRectItem and + define a geometry property. We can now animate the widgets + geometry even if QGraphicsRectItem does not provide the geometry + property. + + For a general introduction to the Qt property system, see its + \l{Qt's Property System}{overview}. + + \section1 Animations and the Graphics View Framework + + When you want to animate \l{QGraphicsItem}s, you also use + QPropertyAnimation. However, QGraphicsItem does not inherit QObject. + A good solution is to subclass the graphics item you wish to animate. + This class will then also inherit QObject. + This way, QPropertyAnimation can be used for \l{QGraphicsItem}s. + The example below shows how this is done. Another possibility is + to inherit QGraphicsWidget, which already is a QObject. + + \code + class Pixmap : public QObject, public QGraphicsPixmapItem + { + Q_OBJECT + Q_PROPERTY(QPointF pos READ pos WRITE setPos) + ... + \endcode + + As described in the previous section, we need to define + properties that we wish to animate. + + Note that QObject must be the first class inherited as the + meta-object system demands this. + + \section1 Easing Curves + + As mentioned, QPropertyAnimation performs an interpolation between + the start and end property value. In addition to adding more key + values to the animation, you can also use an easing curve. Easing + curves describe a function that controls how the speed of the + interpolation between 0 and 1 should be, and are useful if you + want to control the speed of an animation without changing the + path of the interpolation. + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation animation(&button, "geometry"); + animation.setDuration(3000); + animation.setStartValue(QRect(0, 0, 100, 30)); + animation.setEndValue(QRect(250, 250, 100, 30)); + + animation.setEasingCurve(QEasingCurve::OutBounce); + + animation.start(); + \endcode + + Here the animation will follow a curve that makes it bounce like a + ball as if it was dropped from the start to the end position. + QEasingCurve has a large collection of curves for you to choose + from. These are defined by the QEasingCurve::Type enum. If you are + in need of another curve, you can also implement one yourself, and + register it with QEasingCurve. + + \omit Drop this for the first Lab release + (Example of custom easing curve (without the actual impl of + the function I expect) + \endomit + + \section1 Putting Animations Together + + An application will often contain more than one animation. For + instance, you might want to move more than one graphics item + simultaneously or move them in sequence after each other. + + The subclasses of QAnimationGroup (QSequentialAnimationGroup and + QParallelAnimationGroup) are containers for other animations so + that these animations can be animated either in sequence or + parallel. The QAnimationGroup is an example of an animation that + does not animate properties, but it gets notified of time changes + periodically. This enables it to forward those time changes to its + contained animations, and thereby controlling when its animations + are played. + + Let's look at code examples that use both + QSequentialAnimationGroup and QParallelAnimationGroup, starting + off with the latter. + + \code + QPushButton *bonnie = new QPushButton("Bonnie"); + bonnie->show(); + + QPushButton *clyde = new QPushButton("Clyde"); + clyde->show(); + + QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry"); + // Set up anim1 + + QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry"); + // Set up anim2 + + QParallelAnimationGroup *group = new QParallelAnimationGroup; + group->addAnimation(anim1); + group->addAnimation(anim2); + + group->start(); + \endcode + + A parallel group plays more than one animation at the same time. + Calling its \l{QAbstractAnimation::}{start()} function will start + all animations it governs. + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation anim1(&button, "geometry"); + anim1.setDuration(3000); + anim1.setStartValue(QRect(0, 0, 100, 30)); + anim1.setEndValue(QRect(500, 500, 100, 30)); + + QPropertyAnimation anim2(&button, "geometry"); + anim2.setDuration(3000); + anim2.setStartValue(QRect(500, 500, 100, 30)); + anim2.setEndValue(QRect(1000, 500, 100, 30)); + + QSequentialAnimationGroup group; + + group.addAnimation(&anim1); + group.addAnimation(&anim2); + + group.start(); + \endcode + + As you no doubt have guessed, QSequentialAnimationGroup plays + its animations in sequence. It starts the next animation in + the list after the previous is finished. + + Since an animation group is an animation itself, you can add + it to another group. This way, you can build a tree structure + of animations which specifies when the animations are played + in relation to each other. + + \section1 Animations and States + + When using a \l{The State Machine Framework}{state machine}, we + can associate one or more animations to a transition between states + using a QSignalTransition or QEventTransition class. These classes + are both derived from QAbstractTransition, which defines the + convenience function \l{QAbstractTransition::}{addAnimation()} that + enables the appending of one or more animations triggered when the + transition occurs. + + We also have the possibility to associate properties with the + states rather than setting the start and end values ourselves. + Below is a complete code example that animates the geometry of a + QPushButton. + + \code + QPushButton *button = new QPushButton("Animated Button"); + button->show(); + + QStateMachine *machine = new QStateMachine; + + QState *state1 = new QState(machine->rootState()); + state1->assignProperty(button, "geometry", QRect(0, 0, 100, 30)); + machine->setInitialState(state1); + + QState *state2 = new QState(machine->rootState()); + state2->assignProperty(button, "geometry", QRect(250, 250, 100, 30)); + + QSignalTransition *transition1 = state1->addTransition(button, + SIGNAL(clicked()), state2); + transition1->addAnimation(new QPropertyAnimation(button, "geometry")); + + QSignalTransition *transition2 = state2->addTransition(button, + SIGNAL(clicked()), state1); + transition2->addAnimation(new QPropertyAnimation(button, "geometry")); + + machine->start(); + \endcode + + For a more comprehensive example of how to use the state machine + framework for animations, see the states example (it lives in the + \c{examples/animation/states} directory). +*/ + diff --git a/doc/src/frameworks-technologies/containers.qdoc b/doc/src/frameworks-technologies/containers.qdoc new file mode 100644 index 000000000..0ac973208 --- /dev/null +++ b/doc/src/frameworks-technologies/containers.qdoc @@ -0,0 +1,813 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group tools + \title Non-GUI Classes + \ingroup groups + + \brief Collection classes such as list, queue, stack and string, along + with other classes that can be used without needing QApplication. + + The non-GUI classes are general-purpose collection and string classes + that may be used independently of the GUI classes. + + In particular, these classes do not depend on QApplication at all, + and so can be used in non-GUI programs. + +*/ + +/*! + \page containers.html + \title Generic Containers + \ingroup frameworks-technologies + \ingroup groups + \keyword container class + \keyword container classes + + \brief Qt's template-based container classes. + + \tableofcontents + + \section1 Introduction + + The Qt library provides a set of general purpose template-based + container classes. These classes can be used to store items of a + specified type. For example, if you need a resizable array of + \l{QString}s, use QVector<QString>. + + These container classes are designed to be lighter, safer, and + easier to use than the STL containers. If you are unfamiliar with + the STL, or prefer to do things the "Qt way", you can use these + classes instead of the STL classes. + + The container classes are \l{implicitly shared}, they are + \l{reentrant}, and they are optimized for speed, low memory + consumption, and minimal inline code expansion, resulting in + smaller executables. In addition, they are \l{thread-safe} + in situations where they are used as read-only containers + by all threads used to access them. + + For traversing the items stored in a container, you can use one + of two types of iterators: \l{Java-style iterators} and + \l{STL-style iterators}. The Java-style iterators are easier to + use and provide high-level functionality, whereas the STL-style + iterators are slightly more efficient and can be used together + with Qt's and STL's \l{generic algorithms}. + + Qt also offers a \l{foreach} keyword that make it very + easy to iterate over all the items stored in a container. + + \section1 The Container Classes + + Qt provides the following sequential containers: QList, + QLinkedList, QVector, QStack, and QQueue. For most + applications, QList is the best type to use. Although it is + implemented as an array-list, it provides very fast prepends and + appends. If you really need a linked-list, use QLinkedList; if you + want your items to occupy consecutive memory locations, use QVector. + QStack and QQueue are convenience classes that provide LIFO and + FIFO semantics. + + Qt also provides these associative containers: QMap, + QMultiMap, QHash, QMultiHash, and QSet. The "Multi" containers + conveniently support multiple values associated with a single + key. The "Hash" containers provide faster lookup by using a hash + function instead of a binary search on a sorted set. + + As special cases, the QCache and QContiguousCache classes provide + efficient hash-lookup of objects in a limited cache storage. + + \table + \header \o Class \o Summary + + \row \o \l{QList}<T> + \o This is by far the most commonly used container class. It + stores a list of values of a given type (T) that can be accessed + by index. Internally, the QList is implemented using an array, + ensuring that index-based access is very fast. + + Items can be added at either end of the list using + QList::append() and QList::prepend(), or they can be inserted in + the middle using QList::insert(). More than any other container + class, QList is highly optimized to expand to as little code as + possible in the executable. QStringList inherits from + QList<QString>. + + \row \o \l{QLinkedList}<T> + \o This is similar to QList, except that it uses + iterators rather than integer indexes to access items. It also + provides better performance than QList when inserting in the + middle of a huge list, and it has nicer iterator semantics. + (Iterators pointing to an item in a QLinkedList remain valid as + long as the item exists, whereas iterators to a QList can become + invalid after any insertion or removal.) + + \row \o \l{QVector}<T> + \o This stores an array of values of a given type at adjacent + positions in memory. Inserting at the front or in the middle of + a vector can be quite slow, because it can lead to large numbers + of items having to be moved by one position in memory. + + \row \o \l{QStack}<T> + \o This is a convenience subclass of QVector that provides + "last in, first out" (LIFO) semantics. It adds the following + functions to those already present in QVector: + \l{QStack::push()}{push()}, \l{QStack::pop()}{pop()}, + and \l{QStack::top()}{top()}. + + \row \o \l{QQueue}<T> + \o This is a convenience subclass of QList that provides + "first in, first out" (FIFO) semantics. It adds the following + functions to those already present in QList: + \l{QQueue::enqueue()}{enqueue()}, + \l{QQueue::dequeue()}{dequeue()}, and \l{QQueue::head()}{head()}. + + \row \o \l{QSet}<T> + \o This provides a single-valued mathematical set with fast + lookups. + + \row \o \l{QMap}<Key, T> + \o This provides a dictionary (associative array) that maps keys + of type Key to values of type T. Normally each key is associated + with a single value. QMap stores its data in Key order; if order + doesn't matter QHash is a faster alternative. + + \row \o \l{QMultiMap}<Key, T> + \o This is a convenience subclass of QMap that provides a nice + interface for multi-valued maps, i.e. maps where one key can be + associated with multiple values. + + \row \o \l{QHash}<Key, T> + \o This has almost the same API as QMap, but provides + significantly faster lookups. QHash stores its data in an + arbitrary order. + + \row \o \l{QMultiHash}<Key, T> + \o This is a convenience subclass of QHash that + provides a nice interface for multi-valued hashes. + + \endtable + + Containers can be nested. For example, it is perfectly possible + to use a QMap<QString, QList<int> >, where the key type is + QString and the value type QList<int>. The only pitfall is that + you must insert a space between the closing angle brackets (>); + otherwise the C++ compiler will misinterpret the two >'s as a + right-shift operator (>>) and report a syntax error. + + The containers are defined in individual header files with the + same name as the container (e.g., \c <QLinkedList>). For + convenience, the containers are forward declared in \c + <QtContainerFwd>. + + \keyword assignable data type + \keyword assignable data types + + The values stored in the various containers can be of any + \e{assignable data type}. To qualify, a type must provide a + default constructor, a copy constructor, and an assignment + operator. This covers most data types you are likely to want to + store in a container, including basic types such as \c int and \c + double, pointer types, and Qt data types such as QString, QDate, + and QTime, but it doesn't cover QObject or any QObject subclass + (QWidget, QDialog, QTimer, etc.). If you attempt to instantiate a + QList<QWidget>, the compiler will complain that QWidget's copy + constructor and assignment operators are disabled. If you want to + store these kinds of objects in a container, store them as + pointers, for example as QList<QWidget *>. + + Here's an example custom data type that meets the requirement of + an assignable data type: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 0 + + If we don't provide a copy constructor or an assignment operator, + C++ provides a default implementation that performs a + member-by-member copy. In the example above, that would have been + sufficient. Also, if you don't provide any constructors, C++ + provides a default constructor that initializes its member using + default constructors. Although it doesn't provide any + explicit constructors or assignment operator, the following data + type can be stored in a container: + + \snippet doc/src/snippets/streaming/main.cpp 0 + + Some containers have additional requirements for the data types + they can store. For example, the Key type of a QMap<Key, T> must + provide \c operator<(). Such special requirements are documented + in a class's detailed description. In some cases, specific + functions have special requirements; these are described on a + per-function basis. The compiler will always emit an error if a + requirement isn't met. + + Qt's containers provide operator<<() and operator>>() so that they + can easily be read and written using a QDataStream. This means + that the data types stored in the container must also support + operator<<() and operator>>(). Providing such support is + straightforward; here's how we could do it for the Movie struct + above: + + \snippet doc/src/snippets/streaming/main.cpp 1 + \codeline + \snippet doc/src/snippets/streaming/main.cpp 2 + + \keyword default-constructed values + + The documentation of certain container class functions refer to + \e{default-constructed values}; for example, QVector + automatically initializes its items with default-constructed + values, and QMap::value() returns a default-constructed value if + the specified key isn't in the map. For most value types, this + simply means that a value is created using the default + constructor (e.g. an empty string for QString). But for primitive + types like \c{int} and \c{double}, as well as for pointer types, + the C++ language doesn't specify any initialization; in those + cases, Qt's containers automatically initialize the value to 0. + + \section1 The Iterator Classes + + Iterators provide a uniform means to access items in a container. + Qt's container classes provide two types of iterators: Java-style + iterators and STL-style iterators. Iterators of both types are + invalidated when the data in the container is modified or detached + from \l{Implicit Sharing}{implicitly shared copies} due to a call + to a non-const member function. + + \section2 Java-Style Iterators + + The Java-style iterators are new in Qt 4 and are the standard + ones used in Qt applications. They are more convenient to use than + the STL-style iterators, at the price of being slightly less + efficient. Their API is modelled on Java's iterator classes. + + For each container class, there are two Java-style iterator data + types: one that provides read-only access and one that provides + read-write access. + + \table + \header \o Containers \o Read-only iterator + \o Read-write iterator + \row \o QList<T>, QQueue<T> \o QListIterator<T> + \o QMutableListIterator<T> + \row \o QLinkedList<T> \o QLinkedListIterator<T> + \o QMutableLinkedListIterator<T> + \row \o QVector<T>, QStack<T> \o QVectorIterator<T> + \o QMutableVectorIterator<T> + \row \o QSet<T> \o QSetIterator<T> + \o QMutableSetIterator<T> + \row \o QMap<Key, T>, QMultiMap<Key, T> \o QMapIterator<Key, T> + \o QMutableMapIterator<Key, T> + \row \o QHash<Key, T>, QMultiHash<Key, T> \o QHashIterator<Key, T> + \o QMutableHashIterator<Key, T> + \endtable + + In this discussion, we will concentrate on QList and QMap. The + iterator types for QLinkedList, QVector, and QSet have exactly + the same interface as QList's iterators; similarly, the iterator + types for QHash have the same interface as QMap's iterators. + + Unlike STL-style iterators (covered \l{STL-style + iterators}{below}), Java-style iterators point \e between items + rather than directly \e at items. For this reason, they are + either pointing to the very beginning of the container (before + the first item), at the very end of the container (after the last + item), or between two items. The diagram below shows the valid + iterator positions as red arrows for a list containing four + items: + + \img javaiterators1.png + + Here's a typical loop for iterating through all the elements of a + QList<QString> in order and printing them to the console: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 1 + + It works as follows: The QList to iterate over is passed to the + QListIterator constructor. At that point, the iterator is located + just in front of the first item in the list (before item "A"). + Then we call \l{QListIterator::hasNext()}{hasNext()} to + check whether there is an item after the iterator. If there is, we + call \l{QListIterator::next()}{next()} to jump over that + item. The next() function returns the item that it jumps over. For + a QList<QString>, that item is of type QString. + + Here's how to iterate backward in a QList: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 2 + + The code is symmetric with iterating forward, except that we + start by calling \l{QListIterator::toBack()}{toBack()} + to move the iterator after the last item in the list. + + The diagram below illustrates the effect of calling + \l{QListIterator::next()}{next()} and + \l{QListIterator::previous()}{previous()} on an iterator: + + \img javaiterators2.png + + The following table summarizes the QListIterator API: + + \table + \header \o Function \o Behavior + \row \o \l{QListIterator::toFront()}{toFront()} + \o Moves the iterator to the front of the list (before the first item) + \row \o \l{QListIterator::toBack()}{toBack()} + \o Moves the iterator to the back of the list (after the last item) + \row \o \l{QListIterator::hasNext()}{hasNext()} + \o Returns true if the iterator isn't at the back of the list + \row \o \l{QListIterator::next()}{next()} + \o Returns the next item and advances the iterator by one position + \row \o \l{QListIterator::peekNext()}{peekNext()} + \o Returns the next item without moving the iterator + \row \o \l{QListIterator::hasPrevious()}{hasPrevious()} + \o Returns true if the iterator isn't at the front of the list + \row \o \l{QListIterator::previous()}{previous()} + \o Returns the previous item and moves the iterator back by one position + \row \o \l{QListIterator::peekPrevious()}{peekPrevious()} + \o Returns the previous item without moving the iterator + \endtable + + QListIterator provides no functions to insert or remove items + from the list as we iterate. To accomplish this, you must use + QMutableListIterator. Here's an example where we remove all + odd numbers from a QList<int> using QMutableListIterator: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 3 + + The next() call in the loop is made every time. It jumps over the + next item in the list. The + \l{QMutableListIterator::remove()}{remove()} function removes the + last item that we jumped over from the list. The call to + \l{QMutableListIterator::remove()}{remove()} does not invalidate + the iterator, so it is safe to continue using it. This works just + as well when iterating backward: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 4 + + If we just want to modify the value of an existing item, we can + use \l{QMutableListIterator::setValue()}{setValue()}. In the code + below, we replace any value larger than 128 with 128: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 5 + + Just like \l{QMutableListIterator::remove()}{remove()}, + \l{QMutableListIterator::setValue()}{setValue()} operates on the + last item that we jumped over. If we iterate forward, this is the + item just before the iterator; if we iterate backward, this is + the item just after the iterator. + + The \l{QMutableListIterator::next()}{next()} function returns a + non-const reference to the item in the list. For simple + operations, we don't even need + \l{QMutableListIterator::setValue()}{setValue()}: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 6 + + As mentioned above, QLinkedList's, QVector's, and QSet's iterator + classes have exactly the same API as QList's. We will now turn to + QMapIterator, which is somewhat different because it iterates on + (key, value) pairs. + + Like QListIterator, QMapIterator provides + \l{QMapIterator::toFront()}{toFront()}, + \l{QMapIterator::toBack()}{toBack()}, + \l{QMapIterator::hasNext()}{hasNext()}, + \l{QMapIterator::next()}{next()}, + \l{QMapIterator::peekNext()}{peekNext()}, + \l{QMapIterator::hasPrevious()}{hasPrevious()}, + \l{QMapIterator::previous()}{previous()}, and + \l{QMapIterator::peekPrevious()}{peekPrevious()}. The key and + value components are extracted by calling key() and value() on + the object returned by next(), peekNext(), previous(), or + peekPrevious(). + + The following example removes all (capital, country) pairs where + the capital's name ends with "City": + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 7 + + QMapIterator also provides a key() and a value() function that + operate directly on the iterator and that return the key and + value of the last item that the iterator jumped above. For + example, the following code copies the contents of a QMap into a + QHash: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 8 + + If we want to iterate through all the items with the same + value, we can use \l{QMapIterator::findNext()}{findNext()} + or \l{QMapIterator::findPrevious()}{findPrevious()}. + Here's an example where we remove all the items with a particular + value: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 9 + + \section2 STL-Style Iterators + + STL-style iterators have been available since the release of Qt + 2.0. They are compatible with Qt's and STL's \l{generic + algorithms} and are optimized for speed. + + For each container class, there are two STL-style iterator types: + one that provides read-only access and one that provides + read-write access. Read-only iterators should be used wherever + possible because they are faster than read-write iterators. + + \table + \header \o Containers \o Read-only iterator + \o Read-write iterator + \row \o QList<T>, QQueue<T> \o QList<T>::const_iterator + \o QList<T>::iterator + \row \o QLinkedList<T> \o QLinkedList<T>::const_iterator + \o QLinkedList<T>::iterator + \row \o QVector<T>, QStack<T> \o QVector<T>::const_iterator + \o QVector<T>::iterator + \row \o QSet<T> \o QSet<T>::const_iterator + \o QSet<T>::iterator + \row \o QMap<Key, T>, QMultiMap<Key, T> \o QMap<Key, T>::const_iterator + \o QMap<Key, T>::iterator + \row \o QHash<Key, T>, QMultiHash<Key, T> \o QHash<Key, T>::const_iterator + \o QHash<Key, T>::iterator + \endtable + + The API of the STL iterators is modelled on pointers in an array. + For example, the \c ++ operator advances the iterator to the next + item, and the \c * operator returns the item that the iterator + points to. In fact, for QVector and QStack, which store their + items at adjacent memory positions, the + \l{QVector::iterator}{iterator} type is just a typedef for \c{T *}, + and the \l{QVector::iterator}{const_iterator} type is + just a typedef for \c{const T *}. + + In this discussion, we will concentrate on QList and QMap. The + iterator types for QLinkedList, QVector, and QSet have exactly + the same interface as QList's iterators; similarly, the iterator + types for QHash have the same interface as QMap's iterators. + + Here's a typical loop for iterating through all the elements of a + QList<QString> in order and converting them to lowercase: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 10 + + Unlike \l{Java-style iterators}, STL-style iterators point + directly at items. The begin() function of a container returns an + iterator that points to the first item in the container. The + end() function of a container returns an iterator to the + imaginary item one position past the last item in the container. + end() marks an invalid position; it must never be dereferenced. + It is typically used in a loop's break condition. If the list is + empty, begin() equals end(), so we never execute the loop. + + The diagram below shows the valid iterator positions as red + arrows for a vector containing four items: + + \img stliterators1.png + + Iterating backward with an STL-style iterator requires us to + decrement the iterator \e before we access the item. This + requires a \c while loop: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 11 + + In the code snippets so far, we used the unary \c * operator to + retrieve the item (of type QString) stored at a certain iterator + position, and we then called QString::toLower() on it. Most C++ + compilers also allow us to write \c{i->toLower()}, but some + don't. + + For read-only access, you can use const_iterator, constBegin(), + and constEnd(). For example: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 12 + + The following table summarizes the STL-style iterators' API: + + \table + \header \o Expression \o Behavior + \row \o \c{*i} \o Returns the current item + \row \o \c{++i} \o Advances the iterator to the next item + \row \o \c{i += n} \o Advances the iterator by \c n items + \row \o \c{--i} \o Moves the iterator back by one item + \row \o \c{i -= n} \o Moves the iterator back by \c n items + \row \o \c{i - j} \o Returns the number of items between iterators \c i and \c j + \endtable + + The \c{++} and \c{--} operators are available both as prefix + (\c{++i}, \c{--i}) and postfix (\c{i++}, \c{i--}) operators. The + prefix versions modify the iterators and return a reference to + the modified iterator; the postfix versions take a copy of the + iterator before they modify it, and return that copy. In + expressions where the return value is ignored, we recommend that + you use the prefix operators (\c{++i}, \c{--i}), as these are + slightly faster. + + For non-const iterator types, the return value of the unary \c{*} + operator can be used on the left side of the assignment operator. + + For QMap and QHash, the \c{*} operator returns the value + component of an item. If you want to retrieve the key, call key() + on the iterator. For symmetry, the iterator types also provide a + value() function to retrieve the value. For example, here's how + we would print all items in a QMap to the console: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 13 + + Thanks to \l{implicit sharing}, it is very inexpensive for a + function to return a container per value. The Qt API contains + dozens of functions that return a QList or QStringList per value + (e.g., QSplitter::sizes()). If you want to iterate over these + using an STL iterator, you should always take a copy of the + container and iterate over the copy. For example: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 14 + + This problem doesn't occur with functions that return a const or + non-const reference to a container. + + \l{Implicit sharing} has another consequence on STL-style + iterators: You must not take a copy of a container while + non-const iterators are active on that container. Java-style + iterators don't suffer from that limitation. + + \keyword foreach + \section1 The foreach Keyword + + If you just want to iterate over all the items in a container + in order, you can use Qt's \c foreach keyword. The keyword is a + Qt-specific addition to the C++ language, and is implemented + using the preprocessor. + + Its syntax is: \c foreach (\e variable, \e container) \e + statement. For example, here's how to use \c foreach to iterate + over a QLinkedList<QString>: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 15 + + The \c foreach code is significantly shorter than the equivalent + code that uses iterators: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 16 + + Unless the data type contains a comma (e.g., \c{QPair<int, + int>}), the variable used for iteration can be defined within the + \c foreach statement: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 17 + + And like any other C++ loop construct, you can use braces around + the body of a \c foreach loop, and you can use \c break to leave + the loop: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 18 + + With QMap and QHash, \c foreach accesses the value component of + the (key, value) pairs. If you want to iterate over both the keys + and the values, you can use iterators (which are fastest), or you + can write code like this: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 19 + + For a multi-valued map: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 20 + + Qt automatically takes a copy of the container when it enters a + \c foreach loop. If you modify the container as you are + iterating, that won't affect the loop. (If you don't modify the + container, the copy still takes place, but thanks to \l{implicit + sharing} copying a container is very fast.) Similarly, declaring + the variable to be a non-const reference, in order to modify the + current item in the list will not work either. + + In addition to \c foreach, Qt also provides a \c forever + pseudo-keyword for infinite loops: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 21 + + If you're worried about namespace pollution, you can disable + these macros by adding the following line to your \c .pro file: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 22 + + \section1 Other Container-Like Classes + + Qt includes three template classes that resemble containers in + some respects. These classes don't provide iterators and cannot + be used with the \c foreach keyword. + + \list + \o QVarLengthArray<T, Prealloc> provides a low-level + variable-length array. It can be used instead of QVector in + places where speed is particularly important. + + \o QCache<Key, T> provides a cache to store objects of a certain + type T associated with keys of type Key. + + \o QContiguousCache<T> provides an efficient way of caching data + that is typically accessed in a contiguous way. + + \o QPair<T1, T2> stores a pair of elements. + \endlist + + Additional non-template types that compete with Qt's template + containers are QBitArray, QByteArray, QString, and QStringList. + + \section1 Algorithmic Complexity + + Algorithmic complexity is concerned about how fast (or slow) each + function is as the number of items in the container grow. For + example, inserting an item in the middle of a QLinkedList is an + extremely fast operation, irrespective of the number of items + stored in the QLinkedList. On the other hand, inserting an item + in the middle of a QVector is potentially very expensive if the + QVector contains many items, since half of the items must be + moved one position in memory. + + To describe algorithmic complexity, we use the following + terminology, based on the "big Oh" notation: + + \keyword constant time + \keyword logarithmic time + \keyword linear time + \keyword linear-logarithmic time + \keyword quadratic time + + \list + \o \bold{Constant time:} O(1). A function is said to run in constant + time if it requires the same amount of time no matter how many + items are present in the container. One example is + QLinkedList::insert(). + + \o \bold{Logarithmic time:} O(log \e n). A function that runs in + logarithmic time is a function whose running time is + proportional to the logarithm of the number of items in the + container. One example is qBinaryFind(). + + \o \bold{Linear time:} O(\e n). A function that runs in linear time + will execute in a time directly proportional to the number of + items stored in the container. One example is + QVector::insert(). + + \o \bold{Linear-logarithmic time:} O(\e{n} log \e n). A function + that runs in linear-logarithmic time is asymptotically slower + than a linear-time function, but faster than a quadratic-time + function. + + \o \bold{Quadratic time:} O(\e{n}\unicode{178}). A quadratic-time function + executes in a time that is proportional to the square of the + number of items stored in the container. + \endlist + + The following table summarizes the algorithmic complexity of Qt's + sequential container classes: + + \table + \header \o \o Index lookup \o Insertion \o Prepending \o Appending + \row \o QLinkedList<T> \o O(\e n) \o O(1) \o O(1) \o O(1) + \row \o QList<T> \o O(1) \o O(n) \o Amort. O(1) \o Amort. O(1) + \row \o QVector<T> \o O(1) \o O(n) \o O(n) \o Amort. O(1) + \endtable + + In the table, "Amort." stands for "amortized behavior". For + example, "Amort. O(1)" means that if you call the function + only once, you might get O(\e n) behavior, but if you call it + multiple times (e.g., \e n times), the average behavior will be + O(1). + + The following table summarizes the algorithmic complexity of Qt's + associative containers and sets: + + \table + \header \o{1,2} \o{2,1} Key lookup \o{2,1} Insertion + \header \o Average \o Worst case \o Average \o Worst case + \row \o QMap<Key, T> \o O(log \e n) \o O(log \e n) \o O(log \e n) \o O(log \e n) + \row \o QMultiMap<Key, T> \o O(log \e n) \o O(log \e n) \o O(log \e n) \o O(log \e n) + \row \o QHash<Key, T> \o Amort. O(1) \o O(\e n) \o Amort. O(1) \o O(\e n) + \row \o QSet<Key> \o Amort. O(1) \o O(\e n) \o Amort. O(1) \o O(\e n) + \endtable + + With QVector, QHash, and QSet, the performance of appending items + is amortized O(log \e n). It can be brought down to O(1) by + calling QVector::reserve(), QHash::reserve(), or QSet::reserve() + with the expected number of items before you insert the items. + The next section discusses this topic in more depth. + + \section1 Growth Strategies + + QVector<T>, QString, and QByteArray store their items + contiguously in memory; QList<T> maintains an array of pointers + to the items it stores to provide fast index-based access (unless + T is a pointer type or a basic type of the size of a pointer, in + which case the value itself is stored in the array); QHash<Key, + T> keeps a hash table whose size is proportional to the number + of items in the hash. To avoid reallocating the data every single + time an item is added at the end of the container, these classes + typically allocate more memory than necessary. + + Consider the following code, which builds a QString from another + QString: + + \snippet doc/src/snippets/code/doc_src_containers.qdoc 23 + + We build the string \c out dynamically by appending one character + to it at a time. Let's assume that we append 15000 characters to + the QString string. Then the following 18 reallocations (out of a + possible 15000) occur when QString runs out of space: 4, 8, 12, + 16, 20, 52, 116, 244, 500, 1012, 2036, 4084, 6132, 8180, 10228, + 12276, 14324, 16372. At the end, the QString has 16372 Unicode + characters allocated, 15000 of which are occupied. + + The values above may seem a bit strange, but here are the guiding + principles: + \list + \o QString allocates 4 characters at a time until it reaches size 20. + \o From 20 to 4084, it advances by doubling the size each time. + More precisely, it advances to the next power of two, minus + 12. (Some memory allocators perform worst when requested exact + powers of two, because they use a few bytes per block for + book-keeping.) + \o From 4084 on, it advances by blocks of 2048 characters (4096 + bytes). This makes sense because modern operating systems + don't copy the entire data when reallocating a buffer; the + physical memory pages are simply reordered, and only the data + on the first and last pages actually needs to be copied. + \endlist + + QByteArray and QList<T> use more or less the same algorithm as + QString. + + QVector<T> also uses that algorithm for data types that can be + moved around in memory using memcpy() (including the basic C++ + types, the pointer types, and Qt's \l{shared classes}) but uses a + different algorithm for data types that can only be moved by + calling the copy constructor and a destructor. Since the cost of + reallocating is higher in that case, QVector<T> reduces the + number of reallocations by always doubling the memory when + running out of space. + + QHash<Key, T> is a totally different case. QHash's internal hash + table grows by powers of two, and each time it grows, the items + are relocated in a new bucket, computed as qHash(\e key) % + QHash::capacity() (the number of buckets). This remark applies to + QSet<T> and QCache<Key, T> as well. + + For most applications, the default growing algorithm provided by + Qt does the trick. If you need more control, QVector<T>, + QHash<Key, T>, QSet<T>, QString, and QByteArray provide a trio of + functions that allow you to check and specify how much memory to + use to store the items: + + \list + \o \l{QString::capacity()}{capacity()} returns the + number of items for which memory is allocated (for QHash and + QSet, the number of buckets in the hash table). + \o \l{QString::reserve()}{reserve}(\e size) explicitly + preallocates memory for \e size items. + \o \l{QString::squeeze()}{squeeze()} frees any memory + not required to store the items. + \endlist + + If you know approximately how many items you will store in a + container, you can start by calling reserve(), and when you are + done populating the container, you can call squeeze() to release + the extra preallocated memory. +*/ diff --git a/doc/src/frameworks-technologies/dbus-adaptors.qdoc b/doc/src/frameworks-technologies/dbus-adaptors.qdoc new file mode 100644 index 000000000..4c9d90976 --- /dev/null +++ b/doc/src/frameworks-technologies/dbus-adaptors.qdoc @@ -0,0 +1,494 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page usingadaptors.html + \title Using QtDBus Adaptors + + \ingroup best-practices + + Adaptors are special classes that are attached to any QObject-derived class + and provide the interface to the external world using D-Bus. Adaptors are + intended to be lightweight classes whose main purpose is to relay calls to + and from the real object, possibly validating or converting the input from + the external world and, thus, protecting the real object. + + Unlike multiple inheritance, adaptors can be added at any time to any object + (but not removed), which allows for greater flexibility when exporting + existing classes. Another advantage of adaptors is to provide similar but not + identical functionality in methods of the same name in different interfaces, + a case which can be quite common when adding a new version of a standard + interface to an object. + + In order to use an adaptor, one must create a class which inherits + QDBusAbstractAdaptor. Since that is a standard QObject-derived class, the + Q_OBJECT macro must appear in the declaration and the source file must be + processed with the \l {moc} tool. The class must also contain one + Q_CLASSINFO entry with the \c {"D-Bus Interface"} name, declaring which + interface it is exporting. Only one entry per class is supported. + + Any public slot in the class will be accessible through the bus over messages + of the MethodCall type. (See \l {Declaring Slots in D-Bus Adaptors} for more + information). Signals in the class will be automatically relayed over D-Bus. + However, not all types are allowed signals or slots' parameter lists: see + \l {The QtDBus Type System} for more information. + + Also, any property declared with Q_PROPERTY will be automatically exposed + over the Properties interface on D-Bus. Since the QObject property system + does not allow for non-readable properties, it is not possible to declare + write-only properties using adaptors. + + More information: + \list + \o \l{Declaring Slots in D-Bus Adaptors} + \o \l{Declaring Signals in D-Bus Adaptors} + \o \l{The QtDBus Type System} + \o \l{D-Bus Adaptor Example} + \endlist + + \sa QDBusAbstractAdaptor +*/ + +/*! + \page qdbusadaptorexample.html + \title D-Bus Adaptor Example + + \previouspage The QtDBus Type System + \contentspage Using QtDBus Adaptors + + The following example code shows how a D-Bus interface can be implemented + using an adaptor. + + A sample usage of QDBusAbstractAdaptor is as follows: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 0 + + The code above would create an interface that could be represented more or less in the following + canonical representation: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 1 + + This adaptor could be used in the application's main function as follows + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 2 + + Break-down analysis: + \tableofcontents + + \section1 The header + + The header of the example is: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 3 + + The code does the following: + \list + \o it declares the adaptor MainApplicationAdaptor, which descends from QDBusAbstractAdaptor + \o it declares the Qt meta-object data using the Q_OBJECT macro + \o it declares the name of the D-Bus interface it implements. + \endlist + + \section1 The properties + + The properties are declared as follows: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 4 + + And are implemented as follows: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 5 + + The code declares three properties: one of them is a read-write property called "caption" of + string type. The other two are read-only, also of the string type. + + The properties organizationName and organizationDomain are simple relays of the app object's + organizationName and organizationDomain properties. However, the caption property requires + verifying if the application has a main window associated with it: if there isn't any, the + caption property is empty. Note how it is possible to access data defined in other objects + through the getter/setter functions. + + \section1 The constructor + + The constructor: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 6 + + The constructor does the following: + \list + \o it initialises its base class (QDBusAbstractAdaptor) with the parent object it is related to. + \o it stores the app pointer in a member variable. Note that it would be possible to access the + same object using the QDBusAbstractAdaptor::object() function, but it would be necessary to + use \a static_cast<> to properly access the methods in QApplication that are not part of + QObject. + \o it connects the application's signal \a aboutToQuit to its own signal \a aboutToQuit. + \o it connects the application's signal \a focusChanged to a private slot to do some further + processing before emitting a D-Bus signal. + \endlist + + Note that there is no destructor in the example. An eventual destructor could be used to emit + one last signal before the object is destroyed, for instance. + + \section1 Slots/methods + + The public slots in the example (which will be exported as D-Bus methods) are the following: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 7 + + This snippet of code defines 4 methods with different properties each: + \list 1 + \o \c quit: this method takes no parameters and is defined to be asynchronous. That is, callers + are expected to use "fire-and-forget" mechanism when calling this method, since it provides no + useful reply. This is represented in D-Bus by the use of the + org.freedesktop.DBus.Method.NoReply annotation. See \l Q_NOREPLY for more information on + asynchronous methods + + \o \c reparseConfiguration: this simple method, with no input or output arguments simply relays + the call to the application's reparseConfiguration member function. + + \o \c mainWindowObject: this method takes no input parameter, but returns one string output + argument, containing the path to the main window object (if the application has a main + window), or an empty string if it has no main window. Note that this method could have also + been written: void mainWindowObject(QString &path). + + \o \c setSessionManagement: this method takes one input argument (a boolean) and, depending on + its value, it calls one function or another in the application. + \endlist + + See also: \l Q_NOREPLY. + + \section1 Signals + + The signals in this example are defined as follows: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 8 + + However, signal definition isn't enough: signals have to be emitted. One simple way of emitting + signals is to connect another signal to them, so that Qt's signal handling system chains them + automatically. This is what is done for the \a aboutToQuit signal. + + When this is the case, one can use the QDBusAbstractAdaptor::setAutoRelaySignals to + automatically connect every signal from the real object to the adaptor. + + When simple signal-to-signal connection isn't enough, one can use a private slot do do some + work. This is what was done for the mainWindowHasFocus signal: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 9 + + This private slot (which will not be exported as a method via D-Bus) was connected to the + \c focusChanged signal in the adaptor's constructor. It is therefore able to shape the + application's signal into what the interface expects it to be. +*/ + +/*! + \page qdbusdeclaringslots.html + \title Declaring Slots in D-Bus Adaptors + + \contentspage Using QtDBus Adaptors + \nextpage Declaring Signals in D-Bus Adaptors + + Slots in D-Bus adaptors are declared just like normal, public slots, but their + parameters must follow certain rules (see \l{The QtDBus Type System} for more + information). Slots whose parameters do not follow those rules or that are not + public will not be accessible via D-Bus. + + Slots can have one parameter of type \c{const QDBusMessage &}, which must + appear at the end of the input parameter list, before any output parameters. + This parameter, if present, will be initialized with a copy of the + current message being processed, which allows the callee to obtain + information about the caller, such as its connection name. + + Slots can be of three kinds: + \list 1 + \o Asynchronous + \o Input-only + \o Input-and-output + \endlist + + \section1 Asynchronous Slots + Asynchronous slots are those that do not normally return any reply to the + caller. For that reason, they cannot take any output parameters. In most + cases, by the time the first line of the slot is run, the caller function + has already resumed working. + + However, slots must not rely on that behavior. Scheduling and message-dispatching + issues could change the order in which the slot is run. Code intending to + synchronize with the caller should provide its own method of synchronization. + + Asynchronous slots are marked by the keyword \l Q_NOREPLY in the method + signature, before the \c void return type and the slot name. (See the + \c quit() slot in the \l{D-Bus Adaptor Example}). + + \section1 Input-Only Slots + + Input-only slots are normal slots that take parameters passed by value or + by constant reference. However, unlike asynchronous slots, the caller is + usually waiting for completion of the callee before resuming operation. + Therefore, non-asynchronous slots should not block or should state it its + documentation that they may do so. + + Input-only slots have no special marking in their signature, except that + they take only parameters passed by value or by constant reference. + Optionally, slots can take a QDBusMessage parameter as a last parameter, + which can be used to perform additional analysis of the method call message. + + \section1 Input and Output Slots + + Like input-only slots, input-and-output slots are those that the caller is + waiting for a reply. Unlike input-only ones, though, this reply will contain + data. Slots that output data may contain non-constant references and may + return a value as well. However, the output parameters must all appear at + the end of the argument list and may not have input arguments interleaved. + Optionally, a QDBusMessage argument may appear between the input and the + output arguments. + + \section1 Automatic Replies + + Method replies are generated automatically with the contents of the output + parameters (if there were any) by the QtDBus implementation. Slots need not + worry about constructing proper QDBusMessage objects and sending them over + the connection. + + However, the possibility of doing so remains there. Should the slot find out + it needs to send a special reply or even an error, it can do so by using + QDBusMessage::createReply() or QDBusMessage::createErrorReply() on the + QDBusMessage parameter and send it with QDBusConnection::send(). The + QtDBus implementation will not generate any reply if the slot did so. + + \warning When a caller places a method call and waits for a reply, it will + only wait for a limited amount of time. Slots intending to take a long time + to complete should make that fact clear in documentation so that callers + properly set higher timeouts. + + \section1 Delayed Replies + + In some circumstances, the called slot may not be able to process + the request immediately. This is frequently the case when the + request involves an I/O or networking operation which may block. + + If this is the case, the slot should return control to the + application's main loop to avoid freezing the user interface, and + resume the process later. To accomplish this, it should make use + of the extra \c QDBusMessage parameter at the end of the input + parameter list and request a delayed reply. + + We do this by writing a slot that stores the request data in a + persistent structure, indicating to the caller using + \l{QDBusMessage::setDelayedReply()}{QDBusMessage::setDelayedReply(true)} + that the response will be sent later. + + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 10 + + The use of + \l{QDBusConnection::send()}{QDBusConnection::sessionBus().send(data->reply)} + is needed to explicitly inform the caller that the response will be delayed. + In this case, the return value is unimportant; we return an arbitrary value + to satisfy the compiler. + + When the request is processed and a reply is available, it should be sent + using the \c QDBusMessage object that was obtained. In our example, the + reply code could be something as follows: + + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 11 + + As can be seen in the example, when a delayed reply is in place, + the return value(s) from the slot will be ignored by QtDBus. They + are used only to determine the slot's signature when communicating + the adaptor's description to remote applications, or in case the + code in the slot decides not to use a delayed reply. + + The delayed reply itself is requested from QtDBus by calling + QDBusMessage::reply() on the original message. It then becomes the + resposibility of the called code to eventually send a reply to the + caller. + + \warning When a caller places a method call and waits for a reply, it will + only wait for a limited amount of time. Slots intending to take a long time + to complete should make that fact clear in documentation so that callers + properly set higher timeouts. + + \sa {Using QtDBus Adaptors}, {Declaring Signals in D-Bus Adaptors}, + {The QtDBus Type System}, QDBusConnection, QDBusMessage +*/ + +/*! + \page qdbusdeclaringsignals.html + \title Declaring Signals in D-Bus Adaptors + + \previouspage Declaring Slots in D-Bus Adaptors + \contentspage Using QtDBus Adaptors + \nextpage The QtDBus Type System + + Any signal in a class derived from QDBusAbstractAdaptor will be automatically + relayed into D-Bus, provided that the signal's parameters conform to certain + rules (see \l{The QtDBus Type System} for more information). No special code + is necessary to make this relay. + + However, signals must still be emitted. The easiest way to emit an adaptor + signal is to connect another signal to it, so that Qt's signals and slots + mechanism automatically emits the adaptor signal, too. This can be done in + the adaptor's constructor, as has been done in the + \l{D-Bus Adaptor Example}{D-Bus Adaptor example}. + + The QDBusAbstractAdaptor::setAutoRelaySignals() convenience function can also + be used to make and break connections between signals in the real object and + the corresponding signals in the adaptor. It will inspect the list of signals + in both classes and connect those whose parameters match exactly. + + \sa {Using QtDBus Adaptors}, + {Declaring Slots in D-Bus Adaptors}, + {The QtDBus Type System}, QDBusAbstractAdaptor +*/ + +/*! + \page qdbustypesystem.html + \title The QtDBus Type System + + \previouspage Declaring Signals in D-Bus Adaptors + \contentspage Using QtDBus Adaptors + \nextpage D-Bus Adaptor Example + + D-Bus has an extensible type system based on a few primitives and + composition of the primitives in arrays and structures. QtDBus + implements the interface to that type system through the + QDBusArgument class, allowing user programs to send and receive + practically every C++ type over the bus. + + \section1 Primitive Types + + The primitive types are supported natively by QDBusArgument and + need no special customization to be sent or received. They are + listed below, along with the C++ class they relate to: + + \table + \header + \o Qt type + \o D-Bus equivalent type + \row + \o uchar + \o BYTE + \row + \o bool + \o BOOLEAN + \row + \o short + \o INT16 + \row + \o ushort + \o UINT16 + \row + \o int + \o INT32 + \row + \o uint + \o UINT32 + \row + \o qlonglong + \o INT64 + \row + \o qulonglong + \o UINT64 + \row + \o double + \o DOUBLE + \row + \o QString + \o STRING + \row + \o QDBusVariant + \o VARIANT + \row + \o QDBusObjectPath + \o OBJECT_PATH + \row + \o QDBusSignature + \o SIGNATURE + \endtable + + Aside from the primitive types, QDBusArgument also supports two + non-primitive types natively, due to their widespread use in Qt + applications: QStringList and QByteArray. + + \section1 Compound Types + + D-Bus specifies three types of aggregations of primitive types + that allow one to create compound types. They are \c ARRAY, \c + STRUCT and maps/dictionaries. + + Arrays are sets of zero or more elements of the same type, while + structures are a set of a fixed number of elements, each of any + type. Maps or dictionaries are implemented as arrays of a pair of + elements, so there can be zero or more elements in one map. + + \section1 Extending the Type System + + In order to use one's own type with QtDBus, the type has to be + declared as a Qt meta-type with the Q_DECLARE_METATYPE() macro and + registered with the qDBusRegisterMetaType() function. The + streaming operators \c{operator>>} and \c{operator<<} will be + automatically found by the registration system. + + QtDBus provides template specializations for arrays and maps for + use with Qt's \l{Container classes}{container classes}, such as + QMap and QList, so it is not necessary to write the streaming + operator functions for those. For other types, and specially for + types implementing structures, the operators have to be explicitly + implemented. + + See the documentation for QDBusArgument for examples for + structures, arrays and maps. + + \section1 The Type System in Use + + All of the QtDBus types (primitives and user-defined alike) can be + used to send and receive messages of all types over the bus. + + \warning You may not use any type that is not on the list above, + including \a typedefs to the types listed. This also includes + QList<QVariant> and QMap<QString,QVariant>. +*/ + +/*! + \macro Q_NOREPLY + \relates QDBusAbstractAdaptor + \since 4.2 + + The Q_NOREPLY macro can be used to mark a method to be called and not wait for it to finish + processing before returning from QDBusInterface::call(). The called method cannot return any + output arguments and, if it does, any such arguments will be discarded. + + You can use this macro in your own adaptors by placing it before your method's return value + (which must be "void") in the class declaration, as shown in the example: + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 12 + + Its presence in the method implementation (outside the class declaration) is optional. + + \sa {Using QtDBus Adaptors} +*/ diff --git a/doc/src/frameworks-technologies/dbus-intro.qdoc b/doc/src/frameworks-technologies/dbus-intro.qdoc new file mode 100644 index 000000000..cc32a65d5 --- /dev/null +++ b/doc/src/frameworks-technologies/dbus-intro.qdoc @@ -0,0 +1,229 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page intro-to-dbus.html + \title Introduction to D-Bus + \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus. + + \keyword QtDBus + \ingroup frameworks-technologies + + \section1 Introduction + + D-Bus is an Inter-Process Communication (IPC) and Remote Procedure + Calling (RPC) mechanism originally developed for Linux to replace + existing and competing IPC solutions with one unified protocol. It + has also been designed to allow communication between system-level + processes (such as printer and hardware driver services) and + normal user processes. + + It uses a fast, binary message-passing protocol, which is suitable + for same-machine communication due to its low latency and low + overhead. Its specification is currently defined by the + \tt{freedesktop.org} project, and is available to all parties. + + Communication in general happens through a central server + application, called the "bus" (hence the name), but direct + application-to-application communication is also possible. When + communicating on a bus, applications can query which other + applications and services are available, as well as activate one + on demand. + + \section1 The Buses + + D-Bus buses are used to when many-to-many communication is + desired. In order to achieve that, a central server is launched + before any applications can connect to the bus: this server is + responsible for keeping track of the applications that are + connected and for properly routing messages from their source to + their destination. + + In addition, D-Bus defines two well-known buses, called the + system bus and the session bus. These buses are special in the + sense that they have well-defined semantics: some services are + defined to be found in one or both of these buses. + + For example, an application wishing to query the list of hardware + devices attached to the computer will probably communicate to a + service available on the system bus, while the service providing + opening of the user's web browser will be probably found on the + session bus. + + On the system bus, one can also expect to find restrictions on + what services each application is allowed to offer. Therefore, one + can be reasonably certain that, if a certain service is present, + it is being offered by a trusted application. + + \section1 Concepts + + \section2 Messages + + On the low level, applications communicate over D-Bus by sending + messages to one another. Messages are used to relay the remote + procedure calls as well as the replies and errors associated + with them. When used over a bus, messages have a destination, + which means they are routed only to the interested parties, + avoiding congestion due to "swarming" or broadcasting. + + A special kind of message called a "signal message" + (a concept based on Qt's \l {Signals and Slots} mechanism), + however, does not have a pre-defined destination. Since its + purpose is to be used in a one-to-many context, signal messages + are designed to work over an "opt-in" mechanism. + + The QtDBus module fully encapsulates the low-level concept of + messages into a simpler, object-oriented approach familiar to Qt + developers. In most cases, the developer need not worry about + sending or receiving messages. + + \section2 Service Names + + When communicating over a bus, applications obtain what is + called a "service name": it is how that application chooses to be + known by other applications on the same bus. The service names + are brokered by the D-Bus bus daemon and are used to + route messages from one application to another. An analogous + concept to service names are IP addresses and hostnames: a + computer normally has one IP address and may have one or more + hostnames associated with it, according to the services that it + provides to the network. + + On the other hand, if a bus is not used, service names are also + not used. If we compare this to a computer network again, this + would equate to a point-to-point network: since the peer is + known, there is no need to use hostnames to find it or its IP + address. + + The format of a D-Bus service name is in fact very similar to a + host name: it is a dot-separated sequence of letters and + digits. The common practice is even to name one's service name + according to the domain name of the organization that defined + that service. + + For example, the D-Bus service is defined by + \tt{freedesktop.org} and can be found on the bus under the + service name: + + \snippet doc/src/snippets/code/doc_src_introtodbus.qdoc 0 + + \section2 Object Paths + + Like network hosts, applications provide specific services to + other applications by exporting objects. Those objects are + hierarchically organised, much like the parent-child + relationship that classes derived from QObject possess. One + difference, however, is that there is the concept of "root + object", that all objects have as ultimate parent. + + If we continue our analogy with Web services, object paths + equate to the path part of a URL: + + \img qurl-ftppath.png + + Like them, object paths in D-Bus are formed resembling path + names on the filesystem: they are slash-separated labels, each + consisting of letters, digits and the underscore character + ("_"). They must always start with a slash and must not end with + one. + + \section2 Interfaces + + Interfaces are similar to C++ abstract classes and Java's + \c interface keyword and declare the "contract" that is + established between caller and callee. That is, they establish + the names of the methods, signals and properties that are + available as well as the behavior that is expected from either + side when communication is established. + + Qt uses a very similar mechanism in its \l {How to Create Qt + Plugins}{Plugin system}: Base classes in C++ are associated + with a unique identifier by way of the Q_DECLARE_INTERFACE() + macro. + + D-Bus interface names are, in fact, named in a manner similar to + what is suggested by the Qt Plugin System: an identifier usually + constructed from the domain name of the entity that defined that + interface. + + \section2 Cheat Sheet + + To facilitate remembering of the naming formats and their + purposes, the following table can be used: + + \table 90% + \header \o D-Bus Concept \o Analogy \o Name format + \row \o Service name \o Network hostnames \o Dot-separated + ("looks like a hostname") + \row \o Object path \o URL path component \o Slash-separated + ("looks like a path") + \row \o Interface \o Plugin identifier \o Dot-separated + \endtable + + \section1 Debugging + + When developing applications that use D-Bus, it is sometimes useful to be able + to see information about the messages that are sent and received across the + bus by each application. + + This feature can be enabled on a per-application basis by setting the + \c QDBUS_DEBUG environment variable before running each application. + For example, we can enable debugging only for the car in the + \l{D-Bus Remote Controlled Car Example} by running the controller and the + car in the following way: + + \snippet doc/src/snippets/code/doc_src_introtodbus.qdoc QDBUS_DEBUG + + Information about the messages will be written to the console the application + was launched from. + + \section1 Further Reading + + The following documents contain information about Qt's D-Bus integration + features, and provide details about the mechanisms used to send and receive + type information over the bus: + + \list + \o \l{Using QtDBus Adaptors} + \o \l{The QtDBus Type System} + \o \l{QtDBus XML compiler (qdbusxml2cpp)} + \endlist +*/ diff --git a/doc/src/frameworks-technologies/desktop-integration.qdoc b/doc/src/frameworks-technologies/desktop-integration.qdoc new file mode 100644 index 000000000..9faf1a51c --- /dev/null +++ b/doc/src/frameworks-technologies/desktop-integration.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group desktop + \title Desktop Integration Classes +*/ + +/*! + \page desktop-integration.html + \title Desktop Integration + \brief Integrating with the user's desktop environment. + + \ingroup best-practices + + Qt applications behave well in the user's desktop environment, but certain + integrations require additional, and sometimes platform specific, techniques. + + \tableofcontents + + \section1 Useful Classes + + Various classes in Qt are designed to help developers integrate applications into + users' desktop environments. These classes enable developers to take advantage + of native services while still using a cross-platform API. + + \annotatedlist desktop + + \section1 Setting the Application Icon + + 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 {1 Setting the Application Icon} + + \section1 Opening External Resources + + Although Qt provides facilities to handle and display resources, such as + \l{QImageIOHandler}{common image formats} and \l{QTextDocument}{HTML}, + it is sometimes necessary to open files and external resources using external + applications. + + QDesktopServices provides an interface to services offered by the user's desktop + environment. In particular, the \l{QDesktopServices::}{openUrl()} function is + used to open resources using the appropriate application, which may have been + specifically configured by the user. + + \section1 System Tray Icons + + Many modern desktop environments feature docks or panels with \e{system trays} + in which applications can install icons. Applications often use system tray icons + to display status information, either by updating the icon itself or by showing + information in "balloon messages". Additionally, many applications provide + pop-up menus that can be accessed via their system tray icons. + + The QSystemTrayIcon class exposes all of the above features via an intuitive + Qt-style API that can be used on all desktop platforms. + + \section1 Desktop Widgets + + On systems where the user's desktop is displayed using more than one screen, + certain types of applications may need to obtain information about the + configuration of the user's workspace to ensure that new windows and dialogs + are opened in appropriate locations. + + The QDesktopWidget class can be used to monitor the positions of widgets and + notify applications about changes to the way the desktop is split over the + available screens. This enables applications to implement policies for + positioning new windows so that, for example, they do not distract a user + who is working on a specific task. +*/ diff --git a/doc/src/frameworks-technologies/dnd.qdoc b/doc/src/frameworks-technologies/dnd.qdoc new file mode 100644 index 000000000..a7b1622bc --- /dev/null +++ b/doc/src/frameworks-technologies/dnd.qdoc @@ -0,0 +1,449 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group draganddrop + \title Drag And Drop Classes + + \brief Classes dealing with drag and drop and mime type encoding and decoding. +*/ + +/*! + \page dnd.html + \title Drag and Drop + \brief An overview of the drag and drop system provided by Qt. + + \ingroup frameworks-technologies + + Drag and drop provides a simple visual mechanism which users can use + to transfer information between and within applications. (In the + literature this is referred to as a "direct manipulation model".) Drag + and drop is similar in function to the clipboard's cut and paste + mechanism. + + \tableofcontents + + This document describes the basic drag and drop mechanism and + outlines the approach used to enable it in custom widgets. Drag + and drop operations are also supported by Qt's item views and by + the graphics view framework; more information is available in the + \l{Using Drag and Drop with Item Views} and \l{The Graphics View + Framework} documents. + + \section1 Drag and Drop Classes + + These classes deal with drag and drop and the necessary mime type + encoding and decoding. + + \annotatedlist draganddrop + + \section1 Configuration + + The QApplication object provides some properties that are related + to drag and drop operations: + + \list + \i \l{QApplication::startDragTime} describes the amount of time in + milliseconds that the user must hold down a mouse button over an + object before a drag will begin. + \i \l{QApplication::startDragDistance} indicates how far the user has to + move the mouse while holding down a mouse button before the movement + will be interpreted as dragging. Use of high values for this quantity + prevents accidental dragging when the user only meant to click on an + object. + \endlist + + These quantities provide sensible default values for you to use if you + provide drag and drop support in your widgets. + + \section1 Dragging + + To start a drag, create a QDrag object, and call its + exec() function. In most applications, it is a good idea to begin a drag + and drop operation only after a mouse button has been pressed and the + cursor has been moved a certain distance. However, the simplest way to + enable dragging from a widget is to reimplement the widget's + \l{QWidget::mousePressEvent()}{mousePressEvent()} and start a drag + and drop operation: + + \snippet doc/src/snippets/dragging/mainwindow.cpp 0 + \dots 8 + \snippet doc/src/snippets/dragging/mainwindow.cpp 2 + + Although the user may take some time to complete the dragging operation, + as far as the application is concerned the exec() function is a blocking + function that returns with \l{Qt::DropActions}{one of several values}. + These indicate how the operation ended, and are described in more detail + below. + + Note that the exec() function does not block the main event loop. + + For widgets that need to distinguish between mouse clicks and drags, it + is useful to reimplement the widget's + \l{QWidget::mousePressEvent()}{mousePressEvent()} function to record to + start position of the drag: + + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 6 + + Later, in \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()}, we can determine + whether a drag should begin, and construct a drag object to handle the + operation: + + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 7 + \dots + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 8 + + This particular approach uses the \l QPoint::manhattanLength() function + to get a rough estimate of the distance between where the mouse click + occurred and the current cursor position. This function trades accuracy + for speed, and is usually suitable for this purpose. + + \section1 Dropping + + To be able to receive media dropped on a widget, call + \l{QWidget::setAcceptDrops()}{setAcceptDrops(true)} for the widget, + and reimplement the \l{QWidget::dragEnterEvent()}{dragEnterEvent()} and + \l{QWidget::dropEvent()}{dropEvent()} event handler functions. + + For example, the following code enables drop events in the constructor of + a QWidget subclass, making it possible to usefully implement drop event + handlers: + + \snippet doc/src/snippets/dropevents/window.cpp 0 + \dots + \snippet doc/src/snippets/dropevents/window.cpp 1 + \snippet doc/src/snippets/dropevents/window.cpp 2 + + The dragEnterEvent() function is typically used to inform Qt about the + types of data that the widget accepts. + You must reimplement this function if you want to receive either + QDragMoveEvent or QDropEvent in your reimplementations of + \l{QWidget::dragMoveEvent()}{dragMoveEvent()} and + \l{QWidget::dropEvent()}{dropEvent()}. + + The following code shows how \l{QWidget::dragEnterEvent()}{dragEnterEvent()} + can be reimplemented to + tell the drag and drop system that we can only handle plain text: + + \snippet doc/src/snippets/dropevents/window.cpp 3 + + The \l{QWidget::dropEvent()}{dropEvent()} is used to unpack dropped data + and handle it in way that is suitable for your application. + + In the following code, the text supplied in the event is passed to a + QTextBrowser and a QComboBox is filled with the list of MIME types that + are used to describe the data: + + \snippet doc/src/snippets/dropevents/window.cpp 4 + + In this case, we accept the proposed action without checking what it is. + In a real world application, it may be necessary to return from the + \l{QWidget::dropEvent()}{dropEvent()} function without accepting the + proposed action or handling + the data if the action is not relevant. For example, we may choose to + ignore Qt::LinkAction actions if we do not support + links to external sources in our application. + + \section2 Overriding Proposed Actions + + We may also ignore the proposed action, and perform some other action on + the data. To do this, we would call the event object's + \l{QDropEvent::setDropAction()}{setDropAction()} with the preferred + action from Qt::DropAction before calling \l{QEvent::}{accept()}. + This ensures that the replacement drop action is used instead of the + proposed action. + + For more sophisticated applications, reimplementing + \l{QWidget::dragMoveEvent()}{dragMoveEvent()} and + \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} will let you make + certain parts of your widgets sensitive to drop events, and give you more + control over drag and drop in your application. + + \section2 Subclassing Complex Widgets + + Certain standard Qt widgets provide their own support for drag and drop. + When subclassing these widgets, it may be necessary to reimplement + \l{QWidget::dragMoveEvent()}{dragMoveEvent()} in addition to + \l{QWidget::dragEnterEvent()}{dragEnterEvent()} and + \l{QWidget::dropEvent()}{dropEvent()} to prevent the base class from + providing default drag and drop handling, and to handle any special + cases you are interested in. + + \section1 Drag and Drop Actions + + In the simplest case, the target of a drag and drop action receives a + copy of the data being dragged, and the source decides whether to + delete the original. This is described by the \c CopyAction action. + The target may also choose to handle other actions, specifically the + \c MoveAction and \c LinkAction actions. If the source calls + QDrag::exec(), and it returns \c MoveAction, the source is responsible + for deleting any original data if it chooses to do so. The QMimeData + and QDrag objects created by the source widget \e{should not be deleted} + - they will be destroyed by Qt. The target is responsible for taking + ownership of the data sent in the drag and drop operation; this is + usually done by keeping references to the data. + + If the target understands the \c LinkAction action, it should + store its own reference to the original information; the source + does not need to perform any further processing on the data. The + most common use of drag and drop actions is when performing a + Move within the same widget; see the section on \l{Drop Actions} + for more information about this feature. + + The other major use of drag actions is when using a reference type + such as text/uri-list, where the dragged data are actually references + to files or objects. + + \section1 Adding New Drag and Drop Types + + Drag and drop is not limited to text and images. Any type of information + can be transferred in a drag and drop operation. To drag information + between applications, the applications must be able to indicate to each + other which data formats they can accept and which they can produce. + This is achieved using + \l{http://www.rfc-editor.org/rfc/rfc1341.txt}{MIME types}. The QDrag + object constructed by the source contains a list of MIME types that it + uses to represent the data (ordered from most appropriate to least + appropriate), and the drop target uses one of these to access the data. + For common data types, the convenience functions handle the MIME types + used transparently but, for custom data types, it is necessary to + state them explicitly. + + To implement drag and drop actions for a type of information that is + not covered by the QDrag convenience functions, the first and most + important step is to look for existing formats that are appropriate: + The Internet Assigned Numbers Authority (\l{http://www.iana.org}{IANA}) + provides a + \l{http://www.iana.org/assignments/media-types/}{hierarchical + list of MIME media types} at the Information Sciences Institute + (\l{http://www.isi.edu}{ISI}). + Using standard MIME types maximizes the interoperability of + your application with other software now and in the future. + + To support an additional media type, simply set the data in the QMimeData + object with the \l{QMimeData::setData()}{setData()} function, supplying + the full MIME type and a QByteArray containing the data in the appropriate + format. The following code takes a pixmap from a label and stores it + as a Portable Network Graphics (PNG) file in a QMimeData object: + + \snippet doc/src/snippets/separations/finalwidget.cpp 0 + + Of course, for this case we could have simply used + \l{QMimeData::setImageData()}{setImageData()} instead to supply image data + in a variety of formats: + + \snippet doc/src/snippets/separations/finalwidget.cpp 1 + + The QByteArray approach is still useful in this case because it provides + greater control over the amount of data stored in the QMimeData object. + + Note that custom datatypes used in item views must be declared as + \l{QMetaObject}{meta objects} and that stream operators for them + must be implemented. + + \section1 Drop Actions + + In the clipboard model, the user can \e cut or \e copy the source + information, then later paste it. Similarly in the drag and drop + model, the user can drag a \e copy of the information or they can drag + the information itself to a new place (\e moving it). The + drag and drop model has an additional complication for the programmer: + The program doesn't know whether the user wants to cut or copy the + information until the operation is complete. This often makes no + difference when dragging information between applications, but within + an application it is important to check which drop action was used. + + We can reimplement the mouseMoveEvent() for a widget, and start a drag + and drop operation with a combination of possible drop actions. For + example, we may want to ensure that dragging always moves objects in + the widget: + + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 7 + \dots + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 8 + + The action returned by the exec() function may default to a + \c CopyAction if the information is dropped into another application + but, if it is dropped in another widget in the same application, we + may obtain a different drop action. + + The proposed drop actions can be filtered in a widget's dragMoveEvent() + function. However, it is possible to accept all proposed actions in + the dragEnterEvent() and let the user decide which they want to accept + later: + + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 0 + + When a drop occurs in the widget, the dropEvent() handler function is + called, and we can deal with each possible action in turn. First, we + deal with drag and drop operations within the same widget: + + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 1 + + In this case, we refuse to deal with move operations. Each type of drop + action that we accept is checked and dealt with accordingly: + + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 2 + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 3 + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 4 + \dots + \snippet doc/src/snippets/draganddrop/dragwidget.cpp 5 + + Note that we checked for individual drop actions in the above code. + As mentioned above in the section on + \l{#Overriding Proposed Actions}{Overriding Proposed Actions}, it is + sometimes necessary to override the proposed drop action and choose a + different one from the selection of possible drop actions. + To do this, you need to check for the presence of each action in the value + supplied by the event's \l{QDropEvent::}{possibleActions()}, set the drop + action with \l{QDropEvent::}{setDropAction()}, and call + \l{QEvent::}{accept()}. + + \section1 Drop Rectangles + + The widget's dragMoveEvent() can be used to restrict drops to certain parts + of the widget by only accepting the proposed drop actions when the cursor + is within those areas. For example, the following code accepts any proposed + drop actions when the cursor is over a child widget (\c dropFrame): + + \snippet doc/src/snippets/droprectangle/window.cpp 0 + + The dragMoveEvent() can also be used if you need to give visual + feedback during a drag and drop operation, to scroll the window, or + whatever is appropriate. + + \section1 The Clipboard + + Applications can also communicate with each other by putting data on + the clipboard. To access this, you need to obtain a QClipboard object + from the QApplication object: + + \snippet examples/widgets/charactermap/mainwindow.cpp 3 + + The QMimeData class is used to represent data that is transferred to and + from the clipboard. To put data on the clipboard, you can use the + setText(), setImage(), and setPixmap() convenience functions for common + data types. These functions are similar to those found in the QMimeData + class, except that they also take an additional argument that controls + where the data is stored: If \l{QClipboard::Mode}{Clipboard} is + specified, the data is placed on the clipboard; if + \l{QClipboard::Mode}{Selection} is specified, the data is placed in the + mouse selection (on X11 only). By default, data is put on the clipboard. + + For example, we can copy the contents of a QLineEdit to the clipboard + with the following code: + + \snippet examples/widgets/charactermap/mainwindow.cpp 11 + + Data with different MIME types can also be put on the clipboard. + Construct a QMimeData object and set data with setData() function in + the way described in the previous section; this object can then be + put on the clipboard with the + \l{QClipboard::setMimeData()}{setMimeData()} function. + + The QClipboard class can notify the application about changes to the + data it contains via its \l{QClipboard::dataChanged()}{dataChanged()} + signal. For example, we can monitor the clipboard by connecting this + signal to a slot in a widget: + + \snippet doc/src/snippets/clipboard/clipwindow.cpp 0 + + The slot connected to this signal can read the data on the clipboard + using one of the MIME types that can be used to represent it: + + \snippet doc/src/snippets/clipboard/clipwindow.cpp 1 + \dots + \snippet doc/src/snippets/clipboard/clipwindow.cpp 2 + + The \l{QClipboard::selectionChanged()}{selectionChanged()} signal can + be used on X11 to monitor the mouse selection. + + \section1 Examples + + \list + \o \l{draganddrop/draggableicons}{Draggable Icons} + \o \l{draganddrop/draggabletext}{Draggable Text} + \o \l{draganddrop/dropsite}{Drop Site} + \o \l{draganddrop/fridgemagnets}{Fridge Magnets} + \o \l{draganddrop/puzzle}{Drag and Drop Puzzle} + \endlist + + \section1 Interoperating with Other Applications + + On X11, the public \l{http://www.newplanetsoftware.com/xdnd/}{XDND + protocol} is used, while on Windows Qt uses the OLE standard, and + Qt for Mac OS X uses the Carbon Drag Manager. On X11, XDND uses MIME, + so no translation is necessary. The Qt API is the same regardless of + the platform. On Windows, MIME-aware applications can communicate by + using clipboard format names that are MIME types. Already some + Windows applications use MIME naming conventions for their + clipboard formats. Internally, Qt uses QWindowsMime and + QMacPasteboardMime for translating proprietary clipboard formats + to and from MIME types. + + On X11, Qt also supports drops via the Motif Drag & Drop Protocol. The + implementation incorporates some code that was originally written by + Daniel Dardailler, and adapted for Qt by Matt Koss <koss@napri.sk> + and Nokia. Here is the original copyright notice: + + \legalese + Copyright 1996 Daniel Dardailler. + + Permission to use, copy, modify, distribute, and sell this software + for any purpose is hereby granted without fee, provided that the above + copyright notice appear in all copies and that both that copyright + notice and this permission notice appear in supporting documentation, + and that the name of Daniel Dardailler not be used in advertising or + publicity pertaining to distribution of the software without specific, + written prior permission. Daniel Dardailler makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + + Modifications Copyright 1999 Matt Koss, under the same license as + above. + \endlegalese + \omit NOTE: The copyright notice is from qmotifdnd_x11.cpp. \endomit + + Note: The Motif Drag \& Drop Protocol only allows receivers to + request data in response to a QDropEvent. If you attempt to + request data in response to e.g. a QDragMoveEvent, an empty + QByteArray is returned. +*/ diff --git a/doc/src/frameworks-technologies/eventsandfilters.qdoc b/doc/src/frameworks-technologies/eventsandfilters.qdoc new file mode 100644 index 000000000..52d596a16 --- /dev/null +++ b/doc/src/frameworks-technologies/eventsandfilters.qdoc @@ -0,0 +1,235 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group events + \title Event Classes + \ingroup groups + + \brief Classes used to create and handle events. + + These classes are used to create and handle events. + + For more information see the \link object.html Object model\endlink + and \link signalsandslots.html Signals and Slots\endlink. +*/ + +/*! + \page eventsandfilters.html + \title Events and Event Filters + \brief A guide to event handling in Qt. + + \ingroup frameworks-technologies + + In Qt, events are objects, derived from the abstract QEvent class, + that represent things that have happened either within an application + or as a result of outside activity that the application needs to know + about. Events can be received and handled by any instance of a + QObject subclass, but they are especially relevant to widgets. This + document describes how events are delivered and handled in a typical + application. + + \tableofcontents + + \section1 How Events are Delivered + + When an event occurs, Qt creates an event object to represent it by + constructing an instance of the appropriate QEvent subclass, and + delivers it to a particular instance of QObject (or one of its + subclasses) by calling its \l{QObject::}{event()} function. + + This function does not handle the event itself; based on the type + of event delivered, it calls an event handler for that specific + type of event, and sends a response based on whether the event + was accepted or ignored. + + \omit + Event delivery means that an + event has occurred, the QEvent indicates precisely what, and the + QObject needs to respond. Most events are specific to QWidget and its + subclasses, but there are important events that aren't related to + graphics (e.g., \l{QTimer}{timer events}). + \endomit + + Some events, such as QMouseEvent and QKeyEvent, come from the + window system; some, such as QTimerEvent, come from other sources; + some come from the application itself. + + \section1 Event Types + + Most events types have special classes, notably QResizeEvent, + QPaintEvent, QMouseEvent, QKeyEvent, and QCloseEvent. Each class + subclasses QEvent and adds event-specific functions. For example, + QResizeEvent adds \l{QResizeEvent::}{size()} and + \l{QResizeEvent::}{oldSize()} to enable widgets to discover how + their dimensions have been changed. + + Some classes support more than one actual event type. QMouseEvent + supports mouse button presses, double-clicks, moves, and other + related operations. + + Each event has an associated type, defined in QEvent::Type, and this + can be used as a convenient source of run-time type information to + quickly determine which subclass a given event object was constructed + from. + + Since programs need to react in varied and complex ways, Qt's + event delivery mechanisms are flexible. The documentation for + QCoreApplication::notify() concisely tells the whole story; the + \e{Qt Quarterly} article + \l{http://qt.nokia.com/doc/qq/qq11-events.html}{Another Look at Events} + rehashes it less concisely. Here we will explain enough for 95% + of applications. + + \section1 Event Handlers + + The normal way for an event to be delivered is by calling a virtual + function. For example, QPaintEvent is delivered by calling + QWidget::paintEvent(). This virtual function is responsible for + reacting appropriately, normally by repainting the widget. If you + do not perform all the necessary work in your implementation of the + virtual function, you may need to call the base class's implementation. + + For example, the following code handles left mouse button clicks on + a custom checkbox widget while passing all other button clicks to the + base QCheckBox class: + + \snippet doc/src/snippets/events/events.cpp 0 + + If you want to replace the base class's function, you must + implement everything yourself. However, if you only want to extend + the base class's functionality, then you implement what you want and + call the base class to obtain the default behavior for any cases you + do not want to handle. + + Occasionally, there isn't such an event-specific function, or the + event-specific function isn't sufficient. The most common example + involves \key Tab key presses. Normally, QWidget intercepts these to + move the keyboard focus, but a few widgets need the \key{Tab} key for + themselves. + + These objects can reimplement QObject::event(), the general event + handler, and either do their event handling before or after the usual + handling, or they can replace the function completely. A very unusual + widget that both interprets \key Tab and has an application-specific + custom event might contain the following \l{QObject::event()}{event()} + function: + + \snippet doc/src/snippets/events/events.cpp 1 + + Note that QWidget::event() is still called for all of the cases not + handled, and that the return value indicates whether an event was + dealt with; a \c true value prevents the event from being sent on + to other objects. + + \section1 Event Filters + + Sometimes an object needs to look at, and possibly intercept, the + events that are delivered to another object. For example, dialogs + commonly want to filter key presses for some widgets; for example, + to modify \key{Return}-key handling. + + The QObject::installEventFilter() function enables this by setting + up an \e{event filter}, causing a nominated filter object to receive + the events for a target object in its QObject::eventFilter() + function. An event filter gets to process events before the target + object does, allowing it to inspect and discard the events as + required. An existing event filter can be removed using the + QObject::removeEventFilter() function. + + When the filter object's \l{QObject::}{eventFilter()} implementation + is called, it can accept or reject the event, and allow or deny + further processing of the event. If all the event filters allow + further processing of an event (by each returning \c false), the event + is sent to the target object itself. If one of them stops processing + (by returning \c true), the target and any later event filters do not + get to see the event at all. + + \snippet doc/src/snippets/eventfilters/filterobject.cpp 0 + + The above code shows another way to intercept \key{Tab} key press + events sent to a particular target widget. In this case, the filter + handles the relevant events and returns \c true to stop them from + being processed any further. All other events are ignored, and the + filter returns \c false to allow them to be sent on to the target + widget, via any other event filters that are installed on it. + + It is also possible to filter \e all events for the entire application, + by installing an event filter on the QApplication or QCoreApplication + object. Such global event filters are called before the object-specific + filters. This is very powerful, but it also slows down event delivery + of every single event in the entire application; the other techniques + discussed should generally be used instead. + + \section1 Sending Events + + Many applications want to create and send their own events. You can + send events in exactly the same ways as Qt's own event loop by + constructing suitable event objects and sending them with + QCoreApplication::sendEvent() and QCoreApplication::postEvent(). + + \l{QCoreApplication::}{sendEvent()} processes the event immediately. + When it returns, the event filters and/or the object itself have + already processed the event. For many event classes there is a function + called isAccepted() that tells you whether the event was accepted + or rejected by the last handler that was called. + + \l{QCoreApplication::}{postEvent()} posts the event on a queue for + later dispatch. The next time Qt's main event loop runs, it dispatches + all posted events, with some optimization. For example, if there are + several resize events, they are compressed into one. The same + applies to paint events: QWidget::update() calls + \l{QCoreApplication::}{postEvent()}, which eliminates flickering and + increases speed by avoiding multiple repaints. + + \l{QCoreApplication::}{postEvent()} is also used during object + initialization, since the posted event will typically be dispatched + very soon after the initialization of the object is complete. + When implementing a widget, it is important to realise that events + can be delivered very early in its lifetime so, in its constructor, + be sure to initialize member variables early on, before there's any + chance that it might receive an event. + + To create events of a custom type, you need to define an event + number, which must be greater than QEvent::User, and you may need to + subclass QEvent in order to pass specific information about your + custom event. See the QEvent documentation for further details. +*/ diff --git a/doc/src/frameworks-technologies/gestures.qdoc b/doc/src/frameworks-technologies/gestures.qdoc new file mode 100644 index 000000000..2fa8dabe9 --- /dev/null +++ b/doc/src/frameworks-technologies/gestures.qdoc @@ -0,0 +1,173 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gestures-overview.html + \title Gestures Programming + \ingroup frameworks-technologies + \startpage index.html Qt Reference Documentation + + \brief An overview of the Qt support for Gesture programming. + + Qt includes a framework for gesture programming that gives has the ability + to form gestures from a series of events, independently of the input methods + used. A gesture could be a particular movement of a mouse, a touch screen + action, or a series of events from some other source. The nature of the input, + the interpretation of the gesture and the action taken are the choice of the + developer. + + \tableofcontents + + \section1 Overview + + QGesture is the central class in Qt's gesture framework, providing a container + for information about gestures performed by the user. QGesture exposes + properties that give general information that is common to all gestures, and + these can be extended to provide additional gesture-specific information. + Common panning, pinching and swiping gestures are represented by specialized + classes: QPanGesture, QPinchGesture and QSwipeGesture. + + Developers can also implement new gestures by subclassing and extending the + QGestureRecognizer class. Adding support for a new gesture involves implementing + code to recognize the gesture from input events. This is described in the + \l{Creating Your Own Gesture Recognizer} section. + + \section1 Using Standard Gestures with Widgets + + Gestures can be enabled for instances of QWidget and QGraphicsObject subclasses. + An object that accepts gesture input is referred to as a \e{target object}. + + To enable a gesture for a target object, call its QWidget::grabGesture() or + QGraphicsObject::grabGesture() function with an argument describing the + required gesture type. The standard types are defined by the Qt::GestureType + enum and include many commonly used gestures. + + \snippet examples/gestures/imagegestures/imagewidget.cpp enable gestures + + In the above code, the gesture is set up in the constructor of the target object + itself. + + When the user performs a gesture, QGestureEvent events will be delivered to the + target object, and these can be handled by reimplementing the QWidget::event() + handler function for widgets or QGraphicsItem::sceneEvent() for graphics objects. + + For convenience, the \l{Image Gestures Example} reimplements the general + \l{QWidget::}{event()} handler function and delegates gesture events to a + specialized gestureEvent() function: + + \snippet examples/gestures/imagegestures/imagewidget.cpp event handler + + The gesture events delivered to the target object can be examined individually + and dealt with appropriately: + + \snippet examples/gestures/imagegestures/imagewidget.cpp gesture event handler + + Responding to a gesture is simply a matter of obtaining the QGesture object + delivered in the QGestureEvent sent to the target object and examining the + information it contains. + + \snippet examples/gestures/imagegestures/imagewidget.cpp swipe function + + Here, we examine the direction in which the user swiped the widget and modify + its contents accordingly. + + + \section1 Creating Your Own Gesture Recognizer + + Adding support for a new gesture involves creating and registering a new gesture + recognizer. Depending on the recognition process for the gesture, it may also + involve creating a new gesture object. + + To create a new recognizer, you need to subclass QGestureRecognizer to create a + custom recognizer class. There is one virtual function that you must reimplement + and two others that can be reimplemented as required. + + \section2 Filtering Input Events + + The \l{QGestureRecognizer::}{recognize()} function must be reimplemented. + This function handles and filters the incoming input events for the target objects + and determines whether or not they correspond to the gesture the recognizer is + looking for. + + Although the logic for gesture recognition is implemented in this function, + possibly using a state machine based on the Qt::GestureState enums, you can store + persistent information about the state of the recognition process in the QGesture + object supplied. + + Your \l{QGestureRecognizer::}{recognize()} function must return a value of + QGestureRecognizer::Result that indicates the state of recognition for a given gesture and + target object. This determines whether or not a gesture event will be delivered + to a target object. + + \section2 Custom Gestures + + If you choose to represent a gesture by a custom QGesture subclass, you will need to + reimplement the \l{QGestureRecognizer::}{create()} function to construct + instances of your gesture class instead of standard QGesture instances. Alternatively, + you may want to use standard QGesture instances, but add additional dynamic properties + to them to express specific details of the gesture you want to handle. + + \section2 Resetting Gestures + + If you use custom gesture objects that need to be reset or otherwise specially + handled when a gesture is canceled, you need to reimplement the + \l{QGestureRecognizer::}{reset()} function to perform these special tasks. + + Note that QGesture objects are only created once for each combination of target object + and gesture type, and they might be reused every time the user attempts to perform the + same gesture type on the target object. As a result, it can be useful to reimplement + the \l{QGestureRecognizer::}{reset()} function to clean up after each previous attempt + at recognizing a gesture. + + + \section1 Using a New Gesture Recognizer + + To use a gesture recognizer, construct an instance of your QGestureRecognizer + subclass, and register it with the application with + QGestureRecognizer::registerRecognizer(). A recognizer for a given type of + gesture can be removed with QGestureRecognizer::unregisterRecognizer(). + + + \section1 Further Reading + + The \l{gestures/imagegestures}{Image Gestures Example} shows how to enable + gestures for a widget in a simple image viewer application. +*/ diff --git a/doc/src/frameworks-technologies/graphicsview.qdoc b/doc/src/frameworks-technologies/graphicsview.qdoc new file mode 100644 index 000000000..ba89c7d80 --- /dev/null +++ b/doc/src/frameworks-technologies/graphicsview.qdoc @@ -0,0 +1,568 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group graphicsview-api + \title Graphics View Classes +*/ + +/*! + \page graphicsview.html + \title The Graphics View Framework + \brief An overview of the Graphics View framework for interactive 2D + graphics. + + \ingroup frameworks-technologies + + \keyword Graphics View + \keyword GraphicsView + \keyword Graphics + \keyword Canvas + \since 4.2 + + Graphics View provides a surface for managing and interacting with a large + number of custom-made 2D graphical items, and a view widget for + visualizing the items, with support for zooming and rotation. + + The framework includes an event propagation architecture that allows + precise double-precision interaction capabilities for the items on the + scene. Items can handle key events, mouse press, move, release and + double click events, and they can also track mouse movement. + + Graphics View uses a BSP (Binary Space Partitioning) tree to provide very + fast item discovery, and as a result of this, it can visualize large + scenes in real-time, even with millions of items. + + Graphics View was introduced in Qt 4.2, replacing its predecessor, + QCanvas. If you are porting from QCanvas, see \l{Porting to Graphics + View}. + + Topics: + + \tableofcontents + + \section1 The Graphics View Architecture + + Graphics View provides an item-based approach to model-view programming, + much like InterView's convenience classes QTableView, QTreeView and + QListView. Several views can observe a single scene, and the scene + contains items of varying geometric shapes. + + \section2 The Scene + + QGraphicsScene provides the Graphics View scene. The scene has the + following responsibilities: + + \list + \o Providing a fast interface for managing a large number of items + \o Propagating events to each item + \o Managing item state, such as selection and focus handling + \o Providing untransformed rendering functionality; mainly for printing + \endlist + + The scene serves as a container for QGraphicsItem objects. Items are + added to the scene by calling QGraphicsScene::addItem(), and then + retrieved by calling one of the many item discovery functions. + QGraphicsScene::items() and its overloads return all items contained + by or intersecting with a point, a rectangle, a polygon or a general + vector path. QGraphicsScene::itemAt() returns the topmost item at a + particular point. All item discovery functions return the items in + descending stacking order (i.e., the first returned item is topmost, + and the last item is bottom-most). + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 0 + + QGraphicsScene's event propagation architecture schedules scene events + for delivery to items, and also manages propagation between items. If + the scene receives a mouse press event at a certain position, the + scene passes the event on to whichever item is at that position. + + QGraphicsScene also manages certain item states, such as item + selection and focus. You can select items on the scene by calling + QGraphicsScene::setSelectionArea(), passing an arbitrary shape. This + functionality is also used as a basis for rubberband selection in + QGraphicsView. To get the list of all currently selected items, call + QGraphicsScene::selectedItems(). Another state handled by + QGraphicsScene is whether or not an item has keyboard input focus. You + can set focus on an item by calling QGraphicsScene::setFocusItem() or + QGraphicsItem::setFocus(), or get the current focus item by calling + QGraphicsScene::focusItem(). + + Finally, QGraphicsScene allows you to render parts of the scene into a + paint device through the QGraphicsScene::render() function. You can + read more about this in the Printing section later in this document. + + \section2 The View + + QGraphicsView provides the view widget, which visualizes the contents + of a scene. You can attach several views to the same scene, to provide + several viewports into the same data set. The view widget is a scroll + area, and provides scroll bars for navigating through large scenes. To + enable OpenGL support, you can set a QGLWidget as the viewport by + calling QGraphicsView::setViewport(). + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 1 + + The view receives input events from the keyboard and mouse, and + translates these to scene events (converting the coordinates used + to scene coordinates where appropriate), before sending the events + to the visualized scene. + + Using its transformation matrix, QGraphicsView::transform(), the view can + \e transform the scene's coordinate system. This allows advanced + navigation features such as zooming and rotation. For convenience, + QGraphicsView also provides functions for translating between view and + scene coordinates: QGraphicsView::mapToScene() and + QGraphicsView::mapFromScene(). + + \img graphicsview-view.png + + \section2 The Item + + QGraphicsItem is the base class for graphical items in a + scene. Graphics View provides several standard items for typical + shapes, such as rectangles (QGraphicsRectItem), ellipses + (QGraphicsEllipseItem) and text items (QGraphicsTextItem), but the + most powerful QGraphicsItem features are available when you write a + custom item. Among other things, QGraphicsItem supports the following + features: + + \list + \o Mouse press, move, release and double click events, as well as mouse + hover events, wheel events, and context menu events. + \o Keyboard input focus, and key events + \o Drag and drop + \o Grouping, both through parent-child relationships, and with + QGraphicsItemGroup + \o Collision detection + \endlist + + Items live in a local coordinate system, and like QGraphicsView, it + also provides many functions for mapping coordinates between the item + and the scene, and from item to item. Also, like QGraphicsView, it can + transform its coordinate system using a matrix: + QGraphicsItem::transform(). This is useful for rotating and scaling + individual items. + + Items can contain other items (children). Parent items' + transformations are inherited by all its children. Regardless of an + item's accumulated transformation, though, all its functions (e.g., + QGraphicsItem::contains(), QGraphicsItem::boundingRect(), + QGraphicsItem::collidesWith()) still operate in local coordinates. + + QGraphicsItem supports collision detection through the + QGraphicsItem::shape() function, and QGraphicsItem::collidesWith(), + which are both virtual functions. By returning your item's shape as a + local coordinate QPainterPath from QGraphicsItem::shape(), + QGraphicsItem will handle all collision detection for you. If you want + to provide your own collision detection, however, you can reimplement + QGraphicsItem::collidesWith(). + + \img graphicsview-items.png + + \section1 Classes in the Graphics View Framework + + These classes provide a framework for creating interactive applications. + + \annotatedlist graphicsview-api + + \section1 The Graphics View Coordinate System + + Graphics View is based on the Cartesian coordinate system; items' + position and geometry on the scene are represented by sets of two + numbers: the x-coordinate, and the y-coordinate. When observing a scene + using an untransformed view, one unit on the scene is represented by + one pixel on the screen. + + \note The inverted Y-axis coordinate system (where \c y grows upwards) + is unsupported as Graphics Views uses Qt's coordinate system. + + There are three effective coordinate systems in play in Graphics View: + Item coordinates, scene coordinates, and view coordinates. To simplify + your implementation, Graphics View provides convenience functions that + allow you to map between the three coordinate systems. + + When rendering, Graphics View's scene coordinates correspond to + QPainter's \e logical coordinates, and view coordinates are the same as + \e device coordinates. In \l{The Coordinate System}, you can read about + the relationship between logical coordinates and device coordinates. + + \img graphicsview-parentchild.png + + \section2 Item Coordinates + + Items live in their own local coordinate system. Their coordinates + are usually centered around its center point (0, 0), and this is + also the center for all transformations. Geometric primitives in the + item coordinate system are often referred to as item points, item + lines, or item rectangles. + + When creating a custom item, item coordinates are all you need to + worry about; QGraphicsScene and QGraphicsView will perform all + transformations for you. This makes it very easy to implement custom + items. For example, if you receive a mouse press or a drag enter + event, the event position is given in item coordinates. The + QGraphicsItem::contains() virtual function, which returns true if a + certain point is inside your item, and false otherwise, takes a + point argument in item coordinates. Similarly, an item's bounding + rect and shape are in item coordinates. + + At item's \e position is the coordinate of the item's center point + in its parent's coordinate system; sometimes referred to as \e + parent coordinates. The scene is in this sense regarded as all + parent-less items' "parent". Top level items' position are in scene + coordinates. + + Child coordinates are relative to the parent's coordinates. If the + child is untransformed, the difference between a child coordinate + and a parent coordinate is the same as the distance between the + items in parent coordinates. For example: If an untransformed child + item is positioned precisely in its parent's center point, then the + two items' coordinate systems will be identical. If the child's + position is (10, 0), however, the child's (0, 10) point will + correspond to its parent's (10, 10) point. + + Because items' position and transformation are relative to the + parent, child items' coordinates are unaffected by the parent's + transformation, although the parent's transformation implicitly + transforms the child. In the above example, even if the parent is + rotated and scaled, the child's (0, 10) point will still correspond + to the parent's (10, 10) point. Relative to the scene, however, the + child will follow the parent's transformation and position. If the + parent is scaled (2x, 2x), the child's position will be at scene + coordinate (20, 0), and its (10, 0) point will correspond to the + point (40, 0) on the scene. + + With QGraphicsItem::pos() being one of the few exceptions, + QGraphicsItem's functions operate in item coordinates, regardless of + the item, or any of its parents' transformation. For example, an + item's bounding rect (i.e. QGraphicsItem::boundingRect()) is always + given in item coordinates. + + \section2 Scene Coordinates + + The scene represents the base coordinate system for all its items. + The scene coordinate system describes the position of each top-level + item, and also forms the basis for all scene events delivered to the + scene from the view. Each item on the scene has a scene position + and bounding rectangle (QGraphicsItem::scenePos(), + QGraphicsItem::sceneBoundingRect()), in addition to its local item + pos and bounding rectangle. The scene position describes the item's + position in scene coordinates, and its scene bounding rect forms the + basis for how QGraphicsScene determines what areas of the scene have + changed. Changes in the scene are communicated through the + QGraphicsScene::changed() signal, and the argument is a list of + scene rectangles. + + \section2 View Coordinates + + View coordinates are the coordinates of the widget. Each unit in + view coordinates corresponds to one pixel. What's special about this + coordinate system is that it is relative to the widget, or viewport, + and unaffected by the observed scene. The top left corner of + QGraphicsView's viewport is always (0, 0), and the bottom right + corner is always (viewport width, viewport height). All mouse events + and drag and drop events are originally received as view + coordinates, and you need to map these coordinates to the scene in + order to interact with items. + + \section2 Coordinate Mapping + + Often when dealing with items in a scene, it can be useful to map + coordinates and arbitrary shapes from the scene to an item, from + item to item, or from the view to the scene. For example, when you + click your mouse in QGraphicsView's viewport, you can ask the scene + what item is under the cursor by calling + QGraphicsView::mapToScene(), followed by + QGraphicsScene::itemAt(). If you want to know where in the viewport + an item is located, you can call QGraphicsItem::mapToScene() on the + item, then QGraphicsView::mapFromScene() on the view. Finally, if + you use want to find what items are inside a view ellipse, you can + pass a QPainterPath to mapToScene(), and then pass the mapped path + to QGraphicsScene::items(). + + You can map coordinates and shapes to and from and item's scene by + calling QGraphicsItem::mapToScene() and + QGraphicsItem::mapFromScene(). You can also map to an item's parent + item by calling QGraphicsItem::mapToParent() and + QGraphicsItem::mapFromParent(), or between items by calling + QGraphicsItem::mapToItem() and QGraphicsItem::mapFromItem(). All + mapping functions can map both points, rectangles, polygons and + paths. + + The same mapping functions are available in the view, for mapping to + and from the scene. QGraphicsView::mapFromScene() and + QGraphicsView::mapToScene(). To map from a view to an item, you + first map to the scene, and then map from the scene to the item. + + \section1 Key Features + + \section2 Zooming and rotating + + QGraphicsView supports the same affine transformations as QPainter + does through QGraphicsView::setMatrix(). By applying a transformation + to the view, you can easily add support for common navigation features + such as zooming and rotating. + + Here is an example of how to implement zoom and rotate slots in a + subclass of QGraphicsView: + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 2 + + The slots could be connected to \l{QToolButton}{QToolButtons} with + \l{QAbstractButton::autoRepeat}{autoRepeat} enabled. + + QGraphicsView keeps the center of the view aligned when you transform + the view. + + See also the \l{Elastic Nodes Example}{Elastic Nodes} example for + code that shows how to implement basic zooming features. + + \section2 Printing + + Graphics View provides single-line printing through its rendering + functions, QGraphicsScene::render() and QGraphicsView::render(). The + functions provide the same API: You can have the scene or the view + render all or parts of their contents into any paint device by passing + a QPainter to either of the rendering functions. This example shows + how to print the whole scene into a full page, using QPrinter. + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 3 + + The difference between the scene and view rendering functions is that + one operates in scene coordinates, and the other in view coordinates. + QGraphicsScene::render() is often preferred for printing whole + segments of a scene untransformed, such as for plotting geometrical + data, or for printing a text document. QGraphicsView::render(), on the + other hand, is suitable for taking screenshots; its default behavior + is to render the exact contents of the viewport using the provided + painter. + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 4 + + When the source and target areas' sizes do not match, the source + contents are stretched to fit into the target area. By passing a + Qt::AspectRatioMode to the rendering function you are using, you can + choose to maintain or ignore the aspect ratio of the scene when the + contents are stretched. + + \section2 Drag and Drop + + Because QGraphicsView inherits QWidget indirectly, it already provides + the same drag and drop functionality that QWidget provides. In + addition, as a convenience, the Graphics View framework provides drag + and drop support for the scene, and for each and every item. As the + view receives a drag, it translates the drag and drop events into a + QGraphicsSceneDragDropEvent, which is then forwarded to the scene. The + scene takes over scheduling of this event, and sends it to the first + item under the mouse cursor that accepts drops. + + To start a drag from an item, create a QDrag object, passing a pointer + to the widget that starts the drag. Items can be observed by many + views at the same time, but only one view can start the drag. Drags + are in most cases started as a result of pressing or moving the mouse, + so in mousePressEvent() or mouseMoveEvent(), you can get the + originating widget pointer from the event. For example: + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 5 + + To intercept drag and drop events for the scene, you reimplement + QGraphicsScene::dragEnterEvent() and whichever event handlers your + particular scene needs, in a QGraphicsItem subclass. You can read more + about drag and drop in Graphics View in the documentation for each of + QGraphicsScene's event handlers. + + Items can enable drag and drop support by calling + QGraphicsItem::setAcceptDrops(). To handle the incoming drag, + reimplement QGraphicsItem::dragEnterEvent(), + QGraphicsItem::dragMoveEvent(), QGraphicsItem::dragLeaveEvent(), and + QGraphicsItem::dropEvent(). + + See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot} example + for a demonstration of Graphics View's support for drag and drop + operations. + + \section2 Cursors and Tooltips + + Like QWidget, QGraphicsItem also supports cursors + (QGraphicsItem::setCursor()), and tooltips + (QGraphicsItem::setToolTip()). The cursors and tooltips are activated + by QGraphicsView as the mouse cursor enters the item's area (detected + by calling QGraphicsItem::contains()). + + You can also set a default cursor directly on the view by calling + QGraphicsView::setCursor(). + + See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot} + example for code that implements tooltips and cursor shape handling. + + \section2 Animation + + Graphics View supports animation at several levels. You can easily + assemble animation by using the Animation Framework. For that you'll + need your items to inherit from QGraphicsObject and associate + QPropertyAnimation with them. QPropertyAnimation allows to animate any + QObject property. + + Another option is to create a custom item that inherits from QObject + and QGraphicsItem. The item can the set up its own timers, and control + animations with incremental steps in QObject::timerEvent(). + + A third option, which is mostly available for compatibility with + QCanvas in Qt 3, is to \e advance the scene by calling + QGraphicsScene::advance(), which in turn calls + QGraphicsItem::advance(). + + \section2 OpenGL Rendering + + To enable OpenGL rendering, you simply set a new QGLWidget as the + viewport of QGraphicsView by calling QGraphicsView::setViewport(). If + you want OpenGL with antialiasing, you need OpenGL sample buffer + support (see QGLFormat::sampleBuffers()). + + Example: + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 6 + + \section2 Item Groups + + By making an item a child of another, you can achieve the most + essential feature of item grouping: the items will move together, and + all transformations are propagated from parent to child. + + In addition, QGraphicsItemGroup is a special item that combines child + event handling with a useful interface for adding and removing items + to and from a group. Adding an item to a QGraphicsItemGroup will keep + the item's original position and transformation, whereas reparenting + items in general will cause the child to reposition itself relative to + its new parent. For convenience, you can create + \l{QGraphicsItemGroup}s through the scene by calling + QGraphicsScene::createItemGroup(). + + \section2 Widgets and Layouts + + Qt 4.4 introduced support for geometry and layout-aware items through + QGraphicsWidget. This special base item is similar to QWidget, but + unlike QWidget, it doesn't inherit from QPaintDevice; rather from + QGraphicsItem instead. This allows you to write complete widgets with + events, signals & slots, size hints and policies, and you can also + manage your widgets geometries in layouts through + QGraphicsLinearLayout and QGraphicsGridLayout. + + \section3 QGraphicsWidget + + Building on top of QGraphicsItem's capabilities and lean footprint, + QGraphicsWidget provides the best of both worlds: extra + functionality from QWidget, such as the style, font, palette, layout + direction, and its geometry, and resolution independence and + transformation support from QGraphicsItem. Because Graphics View + uses real coordinates instead of integers, QGraphicsWidget's + geometry functions also operate on QRectF and QPointF. This also + applies to frame rects, margins and spacing. With QGraphicsWidget + it's not uncommon to specify contents margins of (0.5, 0.5, 0.5, + 0.5), for example. You can create both subwidgets and "top-level" + windows; in some cases you can now use Graphics View for advanced + MDI applications. + + Some of QWidget's properties are supported, including window flags + and attributes, but not all. You should refer to QGraphicsWidget's + class documentation for a complete overview of what is and what is + not supported. For example, you can create decorated windows by + passing the Qt::Window window flag to QGraphicsWidget's constructor, + but Graphics View currently doesn't support the Qt::Sheet and + Qt::Drawer flags that are common on Mac OS X. + + The capabilities of QGraphicsWidget are expected to grow depending + on community feedback. + + \section3 QGraphicsLayout + + QGraphicsLayout is part of a second-generation layout framework + designed specifically for QGraphicsWidget. Its API is very similar + to that of QLayout. You can manage widgets and sublayouts inside + either QGraphicsLinearLayout and QGraphicsGridLayout. You can also + easily write your own layout by subclassing QGraphicsLayout + yourself, or add your own QGraphicsItem items to the layout by + writing an adaptor subclass of QGraphicsLayoutItem. + + \section2 Embedded Widget Support + + Graphics View provides seamless support for embedding any widget + into the scene. You can embed simple widgets, such as QLineEdit or + QPushButton, complex widgets such as QTabWidget, and even complete + main windows. To embed your widget to the scene, simply call + QGraphicsScene::addWidget(), or create an instance of + QGraphicsProxyWidget to embed your widget manually. + + Through QGraphicsProxyWidget, Graphics View is able to deeply + integrate the client widget features including its cursors, + tooltips, mouse, tablet and keyboard events, child widgets, + animations, pop-ups (e.g., QComboBox or QCompleter), and the widget's + input focus and activation. QGraphicsProxyWidget even integrates the + embedded widget's tab order so that you can tab in and out of + embedded widgets. You can even embed a new QGraphicsView into your + scene to provide complex nested scenes. + + When transforming an embedded widget, Graphics View makes sure that + the widget is transformed resolution independently, allowing the + fonts and style to stay crisp when zoomed in. (Note that the effect + of resolution independence depends on the style.) + + \section1 Performance + + \section2 Floating Point Instructions + + In order to accurately and quickly apply transformations and effects to + items, Graphics View is built with the assumption that the user's hardware + is able to provide reasonable performance for floating point instructions. + + Many workstations and desktop computers are equipped with suitable hardware + to accelerate this kind of computation, but some embedded devices may only + provide libraries to handle mathematical operations or emulate floating + point instructions in software. + + As a result, certain kinds of effects may be slower than expected on certain + devices. It may be possible to compensate for this performance hit by making + optimizations in other areas; for example, by using \l{#OpenGL Rendering}{OpenGL} + to render a scene. However, any such optimizations may themselves cause a + reduction in performance if they also rely on the presence of floating point + hardware. +*/ diff --git a/doc/src/frameworks-technologies/implicit-sharing.qdoc b/doc/src/frameworks-technologies/implicit-sharing.qdoc new file mode 100644 index 000000000..a87595fa3 --- /dev/null +++ b/doc/src/frameworks-technologies/implicit-sharing.qdoc @@ -0,0 +1,152 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* TODO: Move some of the documentation from QSharedDataPointer into this + document. */ + +/*! + \group shared + \title Implicitly Shared Classes +*/ + +/*! + \page implicit-sharing.html + \title Implicit Sharing + \ingroup frameworks-technologies + + \brief Reference counting for fast copying. + + \keyword implicit data sharing + \keyword implicit sharing + \keyword implicitly shared + \keyword reference counting + \keyword shared implicitly + \keyword shared classes + + Many C++ classes in Qt use implicit data sharing to maximize + resource usage and minimize copying. Implicitly shared classes are + both safe and efficient when passed as arguments, because only a + pointer to the data is passed around, and the data is copied only + if and when a function writes to it, i.e., \e {copy-on-write}. + + \tableofcontents + + \section1 Overview + + A shared class consists of a pointer to a shared data block that + contains a reference count and the data. + + When a shared object is created, it sets the reference count to 1. The + reference count is incremented whenever a new object references the + shared data, and decremented when the object dereferences the shared + data. The shared data is deleted when the reference count becomes + zero. + + \keyword deep copy + \keyword shallow copy + + When dealing with shared objects, there are two ways of copying an + object. We usually speak about \e deep and \e shallow copies. A deep + copy implies duplicating an object. A shallow copy is a reference + copy, i.e. just a pointer to a shared data block. Making a deep copy + can be expensive in terms of memory and CPU. Making a shallow copy is + very fast, because it only involves setting a pointer and incrementing + the reference count. + + Object assignment (with operator=()) for implicitly shared objects is + implemented using shallow copies. + + The benefit of sharing is that a program does not need to duplicate + data unnecessarily, which results in lower memory use and less copying + of data. Objects can easily be assigned, sent as function arguments, + and returned from functions. + + Implicit sharing takes place behind the scenes; the programmer + does not need to worry about it. Even in multithreaded + applications, implicit sharing takes place, as explained in + \l{Thread-Support in Qt Modules#Threads and Implicitly Shared Classes} + {Threads and Implicitly Shared Classes}. + + When implementing your own implicitly shared classes, use the + QSharedData and QSharedDataPointer classes. + + \section1 Implicit Sharing in Detail + + Implicit sharing automatically detaches the object from a shared + block if the object is about to change and the reference count is + greater than one. (This is often called \e {copy-on-write} or + \e {value semantics}.) + + An implicitly shared class has total control of its internal data. In + any member functions that modify its data, it automatically detaches + before modifying the data. + + The QPen class, which uses implicit sharing, detaches from the shared + data in all member functions that change the internal data. + + Code fragment: + \snippet doc/src/snippets/code/doc_src_groups.qdoc 0 + + + \section1 List of Classes + + The classes listed below automatically detach from common data if + an object is about to be changed. The programmer will not even + notice that the objects are shared. Thus you should treat + separate instances of them as separate objects. They will always + behave as separate objects but with the added benefit of sharing + data whenever possible. For this reason, you can pass instances + of these classes as arguments to functions by value without + concern for the copying overhead. + + Example: + \snippet doc/src/snippets/code/doc_src_groups.qdoc 1 + + In this example, \c p1 and \c p2 share data until QPainter::begin() + is called for \c p2, because painting a pixmap will modify it. + + \warning Do not copy an implicitly shared container (QMap, + QVector, etc.) while you are iterating over it using an non-const + \l{STL-style iterator}. + + \keyword implicitly shared classes + \annotatedlist shared +*/ diff --git a/doc/src/frameworks-technologies/ipc.qdoc b/doc/src/frameworks-technologies/ipc.qdoc new file mode 100644 index 000000000..0402237fc --- /dev/null +++ b/doc/src/frameworks-technologies/ipc.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page ipc.html + \title Inter-Process Communication in Qt + \brief Inter-Process communication in Qt applications. + + \ingroup frameworks-technologies + + Qt provides several ways to implement Inter-Process Communication + (IPC) in Qt applications. + + \section1 TCP/IP + + The cross-platform \l{QtNetwork} module provides classes that make + network programming portable and easy. It offers high-level + classes (e.g., QNetworkAccessManager, QFtp) that communicate using + specific application-level protocols, and lower-level classes + (e.g., QTcpSocket, QTcpServer, QSslSocket) for implementing + protocols. + + \section1 Shared Memory + + The cross-platform shared memory class, QSharedMemory, provides + access to the operating system's shared memory implementation. + It allows safe access to shared memory segments by multiple threads + and processes. Additionally, QSystemSemaphore can be used to control + access to resources shared by the system, as well as to communicate + between processes. + + \section1 D-Bus + + The \l{QtDBus} module is a Unix-only library + you can use to implement IPC using the D-Bus protocol. It extends + Qt's \l{signalsandslots.html} {Signals and Slots} mechanism to the + IPC level, allowing a signal emitted by one process to be + connected to a slot in another process. This \l {Introduction to + D-Bus} page has detailed information on how to use the \l{QtDBus} + module. + + \section1 Qt COmmunications Protocol (QCOP) + + The QCopChannel class implements a protocol for transferring messages + between client processes across named channels. QCopChannel is + only available in \l{Qt for Embedded Linux}. Like the \l{QtDBus} + module, QCOP extends Qt's \l{Signals and Slots} mechanism to the + IPC level, allowing a signal emitted by one process to be + connected to a slot in another process, but unlike QtDBus, QCOP + does not depend on a third party library. +*/ diff --git a/doc/src/frameworks-technologies/model-view-programming.qdoc b/doc/src/frameworks-technologies/model-view-programming.qdoc new file mode 100644 index 000000000..f0f20b48d --- /dev/null +++ b/doc/src/frameworks-technologies/model-view-programming.qdoc @@ -0,0 +1,2501 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group model-view + \title Model/View Classes +*/ + +/*! + \page model-view-programming.html + \nextpage An Introduction to Model/View Programming + \startpage index.html Qt Reference Documentation + + \title Model/View Programming + \brief A guide to the extensible model/view architecture used by Qt's + item view classes. + + \ingroup frameworks-technologies + + \list + \o \l{An Introduction to Model/View Programming} + \tableofcontents{1 An Introduction to Model/View Programming} + \o \l{Using Models and Views} + \tableofcontents{1 Using Models and Views} + \o \l{Model Classes} + \tableofcontents{1 Model Classes} + \o \l{Creating New Models} + \tableofcontents{1 Creating New Models} + \o \l{View Classes} + \tableofcontents{1 View Classes} + \o \l{Handling Selections in Item Views} + \tableofcontents{1 Handling Selections in Item Views} + \o \l{Delegate Classes} + \tableofcontents{1 Delegate Classes} + \o \l{Item View Convenience Classes} + \tableofcontents{1 Item View Convenience Classes} + \o \l{Using Drag and Drop with Item Views} + \tableofcontents{1 Using Drag and Drop with Item Views} + \o \l{Proxy Models} + \tableofcontents{1 Proxy Models} + \o \l{Model Subclassing Reference} + \tableofcontents{1 Model Subclassing Reference} + \endlist + + \keyword Model/View Classes + \section1 All Model/View Classes + + These classes use the model/view design pattern in which the + underlying data (in the model) is kept separate from the way the data + is presented and manipulated by the user (in the view). + + \annotatedlist model-view + + \section1 Related Examples + + \list + \o \l{itemviews/dirview}{Dir View} + \o \l{itemviews/spinboxdelegate}{Spin Box Delegate} + \o \l{itemviews/pixelator}{Pixelator} + \o \l{itemviews/simpletreemodel}{Simple Tree Model} + \o \l{itemviews/chart}{Chart} + \endlist +*/ + +/*! + \page model-view-introduction.html + \previouspage Model/View Programming + \nextpage Using Models and Views + \startpage index.html Qt Reference Documentation + + \title An Introduction to Model/View Programming + + \tableofcontents + + Qt 4 introduces a new set of item view classes that use a model/view + architecture to manage the relationship between data and the way it + is presented to the user. The separation of functionality introduced by + this architecture gives developers greater flexibility to customize the + presentation of items, and provides a standard model interface to allow + a wide range of data sources to be used with existing item views. + In this document, we give a brief introduction to the model/view paradigm, + outline the concepts involved, and describe the architecture of the item + view system. Each of the components in the architecture is explained, + and examples are given that show how to use the classes provided. + + \section1 The Model/View Architecture + + Model-View-Controller (MVC) is a design pattern originating from + Smalltalk that is often used when building user interfaces. + In \l{Design Patterns}, Gamma et al. write: + + \quotation + MVC consists of three kinds of objects. The Model is the application + object, the View is its screen presentation, and the Controller defines + the way the user interface reacts to user input. Before MVC, user + interface designs tended to lump these objects together. MVC decouples + them to increase flexibility and reuse. + \endquotation + + If the view and the controller objects are combined, the result is + the model/view architecture. This still separates the way that data + is stored from the way that it is presented to the user, but provides + a simpler framework based on the same principles. This separation + makes it possible to display the same data in several different views, + and to implement new types of views, without changing the underlying + data structures. + To allow flexible handling of user input, we introduce the concept of + the \e delegate. The advantage of having a delegate in this framework + is that it allows the way items of data are rendered and edited to be + customized. + + \table + \row \i \inlineimage modelview-overview.png + \i \bold{The model/view architecture} + + The model communicates with a source of data, providing an \e interface + for the other components in the architecture. The nature of the + communication depends on the type of data source, and the way the model + is implemented. + + The view obtains \e{model indexes} from the model; these are references + to items of data. By supplying model indexes to the model, the view can + retrieve items of data from the data source. + + In standard views, a \e delegate renders the items of data. When an item + is edited, the delegate communicates with the model directly using + model indexes. + \endtable + + Generally, the model/view classes can be separated into the three groups + described above: models, views, and delegates. Each of these components + is defined by \e abstract classes that provide common interfaces and, + in some cases, default implementations of features. + Abstract classes are meant to be subclassed in order to provide the full + set of functionality expected by other components; this also allows + specialized components to be written. + + Models, views, and delegates communicate with each other using \e{signals + and slots}: + + \list + \o Signals from the model inform the view about changes to the data + held by the data source. + \o Signals from the view provide information about the user's interaction + with the items being displayed. + \o Signals from the delegate are used during editing to tell the + model and view about the state of the editor. + \endlist + + \section2 Models + + All item models are based on the QAbstractItemModel class. This class + defines an interface that is used by views and delegates to access data. + The data itself does not have to be stored in the model; it can be held + in a data structure or repository provided by a separate class, a file, + a database, or some other application component. + + The basic concepts surrounding models are presented in the section + on \l{Model Classes}. + + QAbstractItemModel + provides an interface to data that is flexible enough to handle views + that represent data in the form of tables, lists, and trees. However, + when implementing new models for list and table-like data structures, + the QAbstractListModel and QAbstractTableModel classes are better + starting points because they provide appropriate default implementations + of common functions. Each of these classes can be subclassed to provide + models that support specialized kinds of lists and tables. + + The process of subclassing models is discussed in the section on + \l{Creating New Models}. + + Qt provides some ready-made models that can be used to handle items of + data: + + \list + \o QStringListModel is used to store a simple list of QString items. + \o QStandardItemModel manages more complex tree structures of items, each + of which can contain arbitrary data. + \o QFileSystemModel provides information about files and directories in the + local filing system. + \o QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel are used + to access databases using model/view conventions. + \endlist + + If these standard models do not meet your requirements, you can subclass + QAbstractItemModel, QAbstractListModel, or QAbstractTableModel to create + your own custom models. + + \section2 Views + + Complete implementations are provided for different kinds of + views: QListView displays a list of items, QTableView displays data + from a model in a table, and QTreeView shows model items of data in a + hierarchical list. Each of these classes is based on the + QAbstractItemView abstract base class. Although these classes are + ready-to-use implementations, they can also be subclassed to provide + customized views. + + The available views are examined in the section on \l{View Classes}. + + \section2 Delegates + + QAbstractItemDelegate is the abstract base class for delegates in the + model/view framework. Since Qt 4.4, the default delegate implementation is + provided by QStyledItemDelegate, and this is used as the default delegate + by Qt's standard views. However, QStyledItemDelegate and QItemDelegate are + independent alternatives to painting and providing editors for items in + views. The difference between them is that QStyledItemDelegate uses the + current style to paint its items. We therefore recommend using + QStyledItemDelegate as the base class when implementing custom delegates or + when working with Qt style sheets. + + Delegates are described in the section on \l{Delegate Classes}. + + \section2 Sorting + + There are two ways of approaching sorting in the model/view + architecture; which approach to choose depends on your underlying + model. + + If your model is sortable, i.e, if it reimplements the + QAbstractItemModel::sort() function, both QTableView and QTreeView + provide an API that allows you to sort your model data + programmatically. In addition, you can enable interactive sorting + (i.e. allowing the users to sort the data by clicking the view's + headers), by connecting the QHeaderView::sortIndicatorChanged() signal + to the QTableView::sortByColumn() slot or the + QTreeView::sortByColumn() slot, respectively. + + The alternative approach, if your model do not have the required + interface or if you want to use a list view to present your data, + is to use a proxy model to transform the structure of your model + before presenting the data in the view. This is covered in detail + in the section on \l {Proxy Models}. + + \section2 Convenience Classes + + A number of \e convenience classes are derived from the standard view + classes for the benefit of applications that rely on Qt's item-based + item view and table classes. They are not intended to be subclassed, + but simply exist to provide a familiar interface to the equivalent classes + in Qt 3. + Examples of such classes include \l QListWidget, \l QTreeWidget, and + \l QTableWidget; these provide similar behavior to the \c QListBox, + \c QListView, and \c QTable classes in Qt 3. + + These classes are less flexible than the view classes, and cannot be + used with arbitrary models. We recommend that you use a model/view + approach to handling data in item views unless you strongly need an + item-based set of classes. + + If you wish to take advantage of the features provided by the model/view + approach while still using an item-based interface, consider using view + classes, such as QListView, QTableView, and QTreeView with + QStandardItemModel. + + \section1 The Model/View Components + + The following sections describe the way in which the model/view pattern + is used in Qt. Each section provides an example of use, and is followed + by a section showing how you can create new components. +*/ + +/*! + \page model-view-using.html + \contentspage model-view-programming.html Contents + \previouspage An Introduction to Model/View Programming + \nextpage Model Classes + + \title Using Models and Views + + \tableofcontents + + \section1 Introduction + + Two of the standard models provided by Qt are QStandardItemModel and + QFileSystemModel. QStandardItemModel is a multi-purpose model that can be + used to represent various different data structures needed by list, table, + and tree views. This model also holds the items of data. + QFileSystemModel is a model that maintains information about the contents + of a directory. As a result, it does not hold any items of data itself, but + simply represents files and directories on the local filing system. + + QFileSystemModel provides a ready-to-use model to experiment with, and can be + easily configured to use existing data. Using this model, we can show how + to set up a model for use with ready-made views, and explore how to + manipulate data using model indexes. + + \section1 Using Views with an Existing Model + + The QListView and QTreeView classes are the most suitable views + to use with QFileSystemModel. The example presented below displays the + contents of a directory in a tree view next to the same information in + a list view. The views share the user's selection so that the selected + items are highlighted in both views. + + \img shareddirmodel.png + + We set up a QFileSystemModel so that it is ready for use, and create some + views to display the contents of a directory. This shows the simplest + way to use a model. The construction and use of the model is + performed from within a single \c main() function: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 0 + + The model is set up to use data from a certain file system. The call to + \l{QFileSystemModel::}{setRootPath()} tell the model which drive on the + file system to expose to the views. + + We create two views so that we can examine the items held in the model in two + different ways: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 5 + + The views are constructed in the same way as other widgets. Setting up + a view to display the items in the model is simply a matter of calling its + \l{QAbstractItemView::setModel()}{setModel()} function with the directory + model as the argument. We filter the data supplied by the model by calling + the \l{QAbstractItemView::}{setRootIndex()} function on each view, passing + a suitable \e{model index} from the file system model for the current + directory. + + The \c index() function used in this case is unique to QFileSystemModel; we + supply it with a directory and it returns a model index. Model indexes are + discussed in the \l{Model Classes} chapter. + + The rest of the function just displays the views within a splitter + widget, and runs the application's event loop: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 8 + + In the above example, we neglected to mention how to handle selections + of items. This subject is covered in more detail in the chapter on + \l{Handling Selections in Item Views}. Before examining how selections + are handled, you may find it useful to read the \l{Model Classes} chapter + which describes the concepts used in the model/view framework. +*/ + +/*! + \page model-view-model.html + \contentspage model-view-programming.html Contents + \previouspage Using Models and Views + \nextpage Creating New Models + + \title Model Classes + + \tableofcontents + + \section1 Basic Concepts + + In the model/view architecture, the model provides a standard interface + that views and delegates use to access data. In Qt, the standard + interface is defined by the QAbstractItemModel class. No matter how the + items of data are stored in any underlying data structure, all subclasses + of QAbstractItemModel represent the data as a hierarchical structure + containing tables of items. Views use this \e convention to access items + of data in the model, but they are not restricted in the way that they + present this information to the user. + + \image modelview-models.png + + Models also notify any attached views about changes to data through the + signals and slots mechanism. + + This chapter describes some basic concepts that are central to the way + item of data are accessed by other components via a model class. More + advanced concepts are discussed in later chapters. + + \section2 Model Indexes + + To ensure that the representation of the data is kept separate from the + way it is accessed, the concept of a \e{model index} is introduced. Each + piece of information that can be obtained via a model is represented by + a model index. Views and delegates use these indexes to request items of + data to display. + + As a result, only the model needs to know how to obtain data, and the type + of data managed by the model can be defined fairly generally. Model indexes + contain a pointer to the model that created them, and this prevents + confusion when working with more than one model. + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 0 + + Model indexes provide \e temporary references to pieces of information, and + can be used to retrieve or modify data via the model. Since models may + reorganize their internal structures from time to time, model indexes may + become invalid, and \e{should not be stored}. If a long-term reference to a + piece of information is required, a \e{persistent model index} must be + created. This provides a reference to the information that the model keeps + up-to-date. Temporary model indexes are provided by the QModelIndex class, + and persistent model indexes are provided by the QPersistentModelIndex + class. + + To obtain a model index that corresponds to an item of data, three + properties must be specified to the model: a row number, a column number, + and the model index of a parent item. The following sections describe + and explain these properties in detail. + + \section2 Rows and Columns + + In its most basic form, a model can be accessed as a simple table in which + items are located by their row and column numbers. \e{This does not mean + that the underlying pieces of data are stored in an array structure}; the + use of row and column numbers is only a convention to allow components to + communicate with each other. We can retrieve information about any given + item by specifying its row and column numbers to the model, and we receive + an index that represents the item: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 1 + + Models that provide interfaces to simple, single level data structures like + lists and tables do not need any other information to be provided but, as + the above code indicates, we need to supply more information when obtaining + a model index. + + \table + \row \i \inlineimage modelview-tablemodel.png + \i \bold{Rows and columns} + + The diagram shows a representation of a basic table model in which each + item is located by a pair of row and column numbers. We obtain a model + index that refers to an item of data by passing the relevant row and + column numbers to the model. + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 2 + + Top level items in a model are always referenced by specifying + \c QModelIndex() as their parent item. This is discussed in the next + section. + \endtable + + \section2 Parents of Items + + The table-like interface to item data provided by models is ideal when + using data in a table or list view; the row and column number system maps + exactly to the way the views display items. However, structures such as + tree views require the model to expose a more flexible interface to the + items within. As a result, each item can also be the parent of another + table of items, in much the same way that a top-level item in a tree view + can contain another list of items. + + When requesting an index for a model item, we must provide some information + about the item's parent. Outside the model, the only way to refer to an + item is through a model index, so a parent model index must also be given: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 3 + + \table + \row \i \inlineimage modelview-treemodel.png + \i \bold{Parents, rows, and columns} + + The diagram shows a representation of a tree model in which each item is + referred to by a parent, a row number, and a column number. + + Items "A" and "C" are represented as top-level siblings in the model: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 4 + + Item "A" has a number of children. A model index for item "B" is + obtained with the following code: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 5 + \endtable + + \section2 Item Roles + + Items in a model can perform various \e roles for other components, + allowing different kinds of data to be supplied for different situations. + For example, Qt::DisplayRole is used to access a string that can be + displayed as text in a view. Typically, items contain data for a number of + different roles, and the standard roles are defined by Qt::ItemDataRole. + + We can ask the model for the item's data by passing it the model index + corresponding to the item, and by specifying a role to obtain the type + of data we want: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 6 + + \table + \row \i \inlineimage modelview-roles.png + \i \bold{Item roles} + + The role indicates to the model which type of data is being referred to. + Views can display the roles in different ways, so it is important to + supply appropriate information for each role. + + The \l{Creating New Models} section covers some specific uses of roles in + more detail. + \endtable + + Most common uses for item data are covered by the standard roles defined in + Qt::ItemDataRole. By supplying appropriate item data for each role, models + can provide hints to views and delegates about how items should be + presented to the user. Different kinds of views have the freedom to + interpret or ignore this information as required. It is also possible to + define additional roles for application-specific purposes. + + \section2 Summary of Concepts + + \list + \o Model indexes give views and delegates information about the location + of items provided by models in a way that is independent of any + underlying data structures. + \o Items are referred to by their row and column numbers, and by the model + index of their parent items. + \o Model indexes are constructed by models at the request of other + components, such as views and delegates. + \o If a valid model index is specified for the parent item when an index is + requested using \l{QAbstractItemModel::index()}{index()}, the index + returned will refer to an item beneath that parent item in the + model. + The index obtained refers to a child of that item. + \o If an invalid model index is specified for the parent item when an index + is requested using \l{QAbstractItemModel::index()}{index()}, the index + returned will refer to a top-level item in the model. + \o The \l{Qt::ItemDataRole}{role} distinguishes between the + different kinds of data associated with an item. + \endlist + + \section2 Using Model Indexes + + To demonstrate how data can be retrieved from a model, using model + indexes, we set up a QFileSystemModel without a view and display the + names of files and directories in a widget. + Although this does not show a normal way of using a model, it demonstrates + the conventions used by models when dealing with model indexes. + + We construct a file system model in the following way: + + \snippet doc/src/snippets/simplemodel-use/main.cpp 0 + + In this case, we set up a default QFileSystemModel, obtain a parent index + using a specific implementation of \l{QFileSystemModel::}{index()} + provided by that model, and we count the number of rows in the model using + the \l{QFileSystemModel::}{rowCount()} function. + + For simplicity, we are only interested in the items in the first column + of the model. We examine each row in turn, obtaining a model index for + the first item in each row, and read the data stored for that item + in the model. + + \snippet doc/src/snippets/simplemodel-use/main.cpp 1 + + To obtain a model index, we specify the row number, column number (zero + for the first column), and the appropriate model index for the parent + of all the items that we want. + The text stored in each item is retrieved using the model's + \l{QFileSystemModel::}{data()} function. We specify the model index and + the \l{Qt::ItemDataRole}{DisplayRole} to obtain data for the + item in the form of a string. + + \snippet doc/src/snippets/simplemodel-use/main.cpp 2 + \codeline + \snippet doc/src/snippets/simplemodel-use/main.cpp 3 + + The above example demonstrates the basic principles used to retrieve + data from a model: + + \list + \i The dimensions of a model can be found using + \l{QAbstractItemModel::rowCount()}{rowCount()} and + \l{QAbstractItemModel::columnCount()}{columnCount()}. + These functions generally require a parent model index to be + specified. + \i Model indexes are used to access items in the model. The row, column, + and parent model index are needed to specify the item. + \i To access top-level items in a model, specify a null model index + as the parent index with \c QModelIndex(). + \i Items contain data for different roles. To obtain the data for a + particular role, both the model index and the role must be supplied + to the model. + \endlist + + + \section1 Further Reading + + New models can be created by implementing the standard interface provided + by QAbstractItemModel. In the \l{Creating New Models} chapter, we will + demonstrate this by creating a convenient ready-to-use model for holding + lists of strings. +*/ + +/*! + \page model-view-view.html + \contentspage model-view-programming.html Contents + \previouspage Creating New Models + \nextpage Handling Selections in Item Views + + \title View Classes + + \tableofcontents + + \section1 Concepts + + In the model/view architecture, the view obtains items of data from the + model and presents them to the user. The way that the data is + presented need not resemble the representation of the data provided by + the model, and may be \e{completely different} from the underlying data + structure used to store items of data. + + The separation of content and presentation is achieved by the use of a + standard model interface provided by QAbstractItemModel, a standard view + interface provided by QAbstractItemView, and the use of model indexes + that represent items of data in a general way. + Views typically manage the overall layout of the data obtained from + models. They may render individual items of data themselves, or use + \l{Delegate Classes}{delegates} to handle both rendering and editing + features. + + As well as presenting data, views handle navigation between items, + and some aspects of item selection. The views also implement basic + user interface features, such as context menus and drag and drop. + A view can provide default editing facilities for items, or it may + work with a \l{Delegate Classes}{delegate} to provide a custom + editor. + + A view can be constructed without a model, but a model must be + provided before it can display useful information. Views keep track of + the items that the user has selected through the use of + \l{Handling Selections in Item Views}{selections} which can be maintained + separately for each view, or shared between multiple views. + + Some views, such as QTableView and QTreeView, display headers as well + as items. These are also implemented by a view class, QHeaderView. + Headers usually access the same model as the view that contains them. + They retrieve data from the model using the + \l{QAbstractItemModel::headerData()} function, and usually display + header information in the form of a label. New headers can be + subclassed from the QHeaderView class to provide more specialized + labels for views. + + \section1 Using an Existing View + + Qt provides three ready-to-use view classes that present data from + models in ways that are familiar to most users. + QListView can display items from a model as a simple list, or in the + form of a classic icon view. QTreeView displays items from a + model as a hierarchy of lists, allowing deeply nested structures to be + represented in a compact way. QTableView presents items from a model + in the form of a table, much like the layout of a spreadsheet + application. + + \img standard-views.png + + The default behavior of the standard views shown above should be + sufficient for most applications. They provide basic editing + facilities, and can be customized to suit the needs of more specialized + user interfaces. + + \section2 Using a Model + + We take the string list model that \l{Creating New Models}{we created as + an example model}, set it up with some data, and construct a view to + display the contents of the model. This can all be performed within a + single function: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 0 + + Note that the \c StringListModel is declared as a \l QAbstractItemModel. + This allows us to use the abstract interface to the model, and + ensures that the code will still work even if we replace the string list + model with a different model in the future. + + The list view provided by \l QListView is sufficient for presenting + the items in the string list model. We construct the view, and set up + the model using the following lines of code: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 2 + \snippet doc/src/snippets/stringlistmodel/main.cpp 4 + + The view is shown in the normal way: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 5 + + The view renders the contents of a model, accessing data via the model's + interface. When the user tries to edit an item, the view uses a default + delegate to provide an editor widget. + + \img stringlistmodel.png + + The above image shows how a QListView represents the data in the string + list model. Since the model is editable, the view automatically allows + each item in the list to be edited using the default delegate. + + \section2 Using Multiple Views onto the Same Model + + Providing multiple views onto the same model is simply a matter of + setting the same model for each view. In the following code we create + two table views, each using the same simple table model which we have + created for this example: + + \snippet doc/src/snippets/sharedtablemodel/main.cpp 0 + \codeline + \snippet doc/src/snippets/sharedtablemodel/main.cpp 1 + + The use of signals and slots in the model/view architecture means that + changes to the model can be propagated to all the attached views, + ensuring that we can always access the same data regardless of the + view being used. + + \img sharedmodel-tableviews.png + + The above image shows two different views onto the same model, each + containing a number of selected items. Although the data from the model + is shown consistently across view, each view maintains its own internal + selection model. This can be useful in certain situations but, for + many applications, a shared selection model is desirable. + + \section1 Handling Selections of Items + + The mechanism for handling selections of items within views is provided + by the \l QItemSelectionModel class. All of the standard views construct + their own selection models by default, and interact with them in the + normal way. The selection model being used by a view can be obtained + through the \l{QAbstractItemView::selectionModel()}{selectionModel()} + function, and a replacement selection model can be specified with + \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()}. + The ability to control the selection model used by a view is useful + when we want to provide multiple consistent views onto the same model + data. + + Generally, unless you are subclassing a model or view, you will not + need to manipulate the contents of selections directly. However, the + interface to the selection model can be accessed, if required, and + this is explored in the chapter on + \l{Handling Selections in Item Views}. + + \section2 Sharing Selections Between Views + + Although it is convenient that the view classes provide their own + selection models by default, when we use more than one view onto the + same model it is often desirable that both the model's data and the + user's selection are shown consistently in all views. + Since the view classes allow their internal selection models to be + replaced, we can achieve a unified selection between views with the + following line: + + \snippet doc/src/snippets/sharedtablemodel/main.cpp 2 + + The second view is given the selection model for the first view. + Both views now operate on the same selection model, keeping both + the data and the selected items synchronized. + + \img sharedselection-tableviews.png + + In the example shown above, two views of the same type were used to + display the same model's data. However, if two different types of view + were used, the selected items may be represented very differently in + each view; for example, a contiguous selection in a table view can be + represented as a fragmented set of highlighted items in a tree view. + +*/ + +/*! + \page model-view-delegate.html + \contentspage model-view-programming.html Contents + \previouspage Handling Selections in Item Views + \nextpage Item View Convenience Classes + + \title Delegate Classes + + \tableofcontents + + \section1 Concepts + + Unlike the Model-View-Controller pattern, the model/view design does not + include a completely separate component for managing interaction with + the user. Generally, the view is responsible for the presentation of + model data to the user, and for processing user input. To allow some + flexibility in the way this input is obtained, the interaction is + performed by delegates. These components provide input capabilities + and are also responsible for rendering individual items in some views. + The standard interface for controlling delegates is defined in the + \l QAbstractItemDelegate class. + + Delegates are expected to be able to render their contents themselves + by implementing the \l{QItemDelegate::paint()}{paint()} + and \l{QItemDelegate::sizeHint()}{sizeHint()} functions. + However, simple widget-based delegates can subclass \l QItemDelegate + instead of \l QAbstractItemDelegate, and take advantage of the default + implementations of these functions. + + Editors for delegates can be implemented either by using widgets to manage + the editing process or by handling events directly. + The first approach is covered later in this chapter, and it is also + shown in the \l{Spin Box Delegate Example}{Spin Box Delegate} example. + + The \l{Pixelator Example}{Pixelator} example shows how to create a + custom delegate that performs specialized rendering for a table view. + + \section1 Using an Existing Delegate + + The standard views provided with Qt use instances of \l QItemDelegate + to provide editing facilities. This default implementation of the + delegate interface renders items in the usual style for each of the + standard views: \l QListView, \l QTableView, and \l QTreeView. + + All the standard roles are handled by the default delegate used by + the standard views. The way these are interpreted is described in the + QItemDelegate documentation. + + The delegate used by a view is returned by the + \l{QAbstractItemView::itemDelegate()}{itemDelegate()} function. + The \l{QAbstractItemView::setItemDelegate()}{setItemDelegate()} function + allows you to install a custom delegate for a standard view, and it is + necessary to use this function when setting the delegate for a custom + view. + + \section1 A Simple Delegate + + The delegate implemented here uses a \l QSpinBox to provide editing + facilities, and is mainly intended for use with models that display + integers. Although we set up a custom integer-based table model for + this purpose, we could easily have used \l QStandardItemModel instead + since the custom delegate will control data entry. We construct a + table view to display the contents of the model, and this will use + the custom delegate for editing. + + \img spinboxdelegate-example.png + + We subclass the delegate from \l QItemDelegate because we do not want + to write custom display functions. However, we must still provide + functions to manage the editor widget: + + \snippet examples/itemviews/spinboxdelegate/delegate.h 0 + + Note that no editor widgets are set up when the delegate is + constructed. We only construct an editor widget when it is needed. + + \section2 Providing an Editor + + In this example, when the table view needs to provide an editor, it + asks the delegate to provide an editor widget that is appropriate + for the item being modified. The + \l{QAbstractItemDelegate::createEditor()}{createEditor()} function is + supplied with everything that the delegate needs to be able to set up + a suitable widget: + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 1 + + Note that we do not need to keep a pointer to the editor widget because + the view takes responsibility for destroying it when it is no longer + needed. + + We install the delegate's default event filter on the editor to ensure + that it provides the standard editing shortcuts that users expect. + Additional shortcuts can be added to the editor to allow more + sophisticated behavior; these are discussed in the section on + \l{#EditingHints}{Editing Hints}. + + The view ensures that the editor's data and geometry are set + correctly by calling functions that we define later for these purposes. + We can create different editors depending on the model index supplied + by the view. For example, if we have a column of integers and a column + of strings we could return either a \c QSpinBox or a \c QLineEdit, + depending on which column is being edited. + + The delegate must provide a function to copy model data into the + editor. In this example, we read the data stored in the + \l{Qt::ItemDataRole}{display role}, and set the value in the + spin box accordingly. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 2 + + In this example, we know that the editor widget is a spin box, but we + could have provided different editors for different types of data in + the model, in which case we would need to cast the widget to the + appropriate type before accessing its member functions. + + \section2 Submitting Data to the Model + + When the user has finished editing the value in the spin box, the view + asks the delegate to store the edited value in the model by calling the + \l{QAbstractItemDelegate::setModelData()}{setModelData()} function. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 3 + + Since the view manages the editor widgets for the delegate, we only + need to update the model with the contents of the editor supplied. + In this case, we ensure that the spin box is up-to-date, and update + the model with the value it contains using the index specified. + + The standard \l QItemDelegate class informs the view when it has + finished editing by emitting the + \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} signal. + The view ensures that the editor widget is closed and destroyed. In + this example, we only provide simple editing facilities, so we need + never emit this signal. + + All the operations on data are performed through the interface + provided by \l QAbstractItemModel. This makes the delegate mostly + independent from the type of data it manipulates, but some + assumptions must be made in order to use certain types of + editor widgets. In this example, we have assumed that the model + always contains integer values, but we can still use this + delegate with different kinds of models because \l{QVariant} + provides sensible default values for unexpected data. + + \section2 Updating the Editor's Geometry + + It is the responsibility of the delegate to manage the editor's + geometry. The geometry must be set when the editor is created, and + when the item's size or position in the view is changed. Fortunately, + the view provides all the necessary geometry information inside a + \l{QStyleOptionViewItem}{view option} object. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 4 + + In this case, we just use the geometry information provided by the + view option in the item rectangle. A delegate that renders items with + several elements would not use the item rectangle directly. It would + position the editor in relation to the other elements in the item. + + \target EditingHints + \section2 Editing Hints + + After editing, delegates should provide hints to the other components + about the result of the editing process, and provide hints that will + assist any subsequent editing operations. This is achieved by + emitting the \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} + signal with a suitable hint. This is taken care of by the default + QItemDelegate event filter which we installed on the spin box when + it was constructed. + + The behavior of the spin box could be adjusted to make it more user + friendly. In the default event filter supplied by QItemDelegate, if + the user hits \key Return to confirm their choice in the spin box, + the delegate commits the value to the model and closes the spin box. + We can change this behavior by installing our own event filter on the + spin box, and provide editing hints that suit our needs; for example, + we might emit \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} + with the \l{QAbstractItemDelegate::EndEditHint}{EditNextItem} hint to + automatically start editing the next item in the view. + + Another approach that does not require the use of an event + filter is to provide our own editor widget, perhaps subclassing + QSpinBox for convenience. This alternative approach would give us + more control over how the editor widget behaves at the cost of + writing additional code. It is usually easier to install an event + filter in the delegate if you need to customize the behavior of + a standard Qt editor widget. + + Delegates do not have to emit these hints, but those that do not will + be less integrated into applications, and will be less usable than + those that emit hints to support common editing actions. +*/ + +/*! + \page model-view-selection.html + \contentspage model-view-programming.html Contents + \previouspage View Classes + \nextpage Delegate Classes + + \title Handling Selections in Item Views + + \tableofcontents + + \section1 Concepts + + The selection model used in the item view classes offers many improvements + over the selection model used in Qt 3. It provides a more general + description of selections based on the facilities of the model/view + architecture. Although the standard classes for manipulating selections are + sufficient for the item views provided, the selection model allows you to + create specialized selection models to suit the requirements for your own + item models and views. + + Information about the items selected in a view is stored in an instance of + the \l QItemSelectionModel class. This maintains model indexes for items in + a single model, and is independent of any views. Since there can be many + views onto a model, it is possible to share selections between views, + allowing applications to show multiple views in a consistent way. + + Selections are made up of \e{selection ranges}. These efficiently maintain + information about large selections of items by recording only the starting + and ending model indexes for each range of selected items. Non-contiguous + selections of items are constructed by using more than one selection range + to describe the selection. + + Selections are applied to a collection of model indexes held by a selection + model. The most recent selection of items applied is known as the + \e{current selection}. The effects of this selection can be modified even + after its application through the use of certain types of selection + commands. These are discussed later in this section. + + + \section2 Current Item and Selected Items + + In a view, there is always a current item and a selected item - two + independent states. An item can be the current item and selected at the + same time. The view is responsible for ensuring that there is always a + current item as keyboard navigation, for example, requires a current item. + + The table below highlights the differences between current item and + selected items. + + \table + \header + \o Current Item + \o Selected Items + + \row + \o There can only be one current item. + \o There can be multiple selected items. + \row + \o The current item will be changed with key navigation or mouse + button clicks. + \o The selected state of items is set or unset, depending on several + pre-defined modes - e.g., single selection, multiple selection, + etc. - when the user interacts with the items. + \row + \o The current item will be edited if the edit key, \gui F2, is + pressed or the item is double-clicked (provided that editing is + enabled). + \o The current item can be used together with an anchor to specify a + range that should be selected or deselected (or a combination of + the two). + \row + \o The current item is indicated by the focus rectangle. + \o The selected items are indicated with the selection rectangle. + \endtable + + When manipulating selections, it is often helpful to think of + \l QItemSelectionModel as a record of the selection state of all the items + in an item model. Once a selection model is set up, collections of items + can be selected, deselected, or their selection states can be toggled + without the need to know which items are already selected. The indexes of + all selected items can be retrieved at any time, and other components can + be informed of changes to the selection model via the signals and slots + mechanism. + + + \section1 Using a Selection Model + + The standard view classes provide default selection models that can + be used in most applications. A selection model belonging to one view + can be obtained using the view's + \l{QAbstractItemView::selectionModel()}{selectionModel()} function, + and shared between many views with + \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()}, + so the construction of new selection models is generally not required. + + A selection is created by specifying a model, and a pair of model + indexes to a \l QItemSelection. This uses the indexes to refer to items + in the given model, and interprets them as the top-left and bottom-right + items in a block of selected items. + To apply the selection to items in a model requires the selection to be + submitted to a selection model; this can be achieved in a number of ways, + each having a different effect on the selections already present in the + selection model. + + + \section2 Selecting Items + + To demonstrate some of the principal features of selections, we construct + an instance of a custom table model with 32 items in total, and open a + table view onto its data: + + \snippet doc/src/snippets/itemselection/main.cpp 0 + + The table view's default selection model is retrieved for later use. + We do not modify any items in the model, but instead select a few + items that the view will display at the top-left of the table. To do + this, we need to retrieve the model indexes corresponding to the + top-left and bottom-right items in the region to be selected: + + \snippet doc/src/snippets/itemselection/main.cpp 1 + + To select these items in the model, and see the corresponding change + in the table view, we need to construct a selection object then apply + it to the selection model: + + \snippet doc/src/snippets/itemselection/main.cpp 2 + + The selection is applied to the selection model using a command + defined by a combination of + \l{QItemSelectionModel::SelectionFlag}{selection flags}. + In this case, the flags used cause the items recorded in the + selection object to be included in the selection model, regardless + of their previous state. The resulting selection is shown by the view. + + \img selected-items1.png + + The selection of items can be modified using various operations that + are defined by the selection flags. The selection that results from + these operations may have a complex structure, but will be represented + efficiently by the selection model. The use of different selection + flags to manipulate the selected items is described when we examine + how to update a selection. + + \section2 Reading the Selection State + + The model indexes stored in the selection model can be read using + the \l{QItemSelectionModel::selectedIndexes()}{selectedIndexes()} + function. This returns an unsorted list of model indexes that we can + iterate over as long as we know which model they are for: + + \snippet doc/src/snippets/reading-selections/window.cpp 0 + + The above code uses Qt's convenient \l{Generic Containers}{foreach + keyword} to iterate over, and modify, the items corresponding to the + indexes returned by the selection model. + + The selection model emits signals to indicate changes in the + selection. These notify other components about changes to both the + selection as a whole and the currently focused item in the item + model. We can connect the + \l{QItemSelectionModel::selectionChanged()}{selectionChanged()} + signal to a slot, and examine the items in the model that are selected or + deselected when the selection changes. The slot is called with two + \l{QItemSelection} objects: one contains a list of indexes that + correspond to newly selected items; the other contains indexes that + correspond to newly deselected items. + + In the following code, we provide a slot that receives the + \l{QItemSelectionModel::selectionChanged()}{selectionChanged()} + signal, fills in the selected items with + a string, and clears the contents of the deselected items. + + \snippet doc/src/snippets/updating-selections/window.cpp 0 + \snippet doc/src/snippets/updating-selections/window.cpp 1 + \codeline + \snippet doc/src/snippets/updating-selections/window.cpp 2 + + We can keep track of the currently focused item by connecting the + \l{QItemSelectionModel::currentChanged()}{currentChanged()} signal + to a slot that is called with two model indexes. These correspond to + the previously focused item, and the currently focused item. + + In the following code, we provide a slot that receives the + \l{QItemSelectionModel::currentChanged()}{currentChanged()} signal, + and uses the information provided to update the status bar of a + \l QMainWindow: + + \snippet doc/src/snippets/updating-selections/window.cpp 3 + + Monitoring selections made by the user is straightforward with these + signals, but we can also update the selection model directly. + + \section2 Updating a Selection + + Selection commands are provided by a combination of selection flags, + defined by \l{QItemSelectionModel::SelectionFlag}. + Each selection flag tells the selection model how to update its + internal record of selected items when either of the + \l{QItemSelection::select()}{select()} functions are called. + The most commonly used flag is the + \l{QItemSelectionModel::SelectionFlag}{Select} flag + which instructs the selection model to record the specified items as + being selected. The + \l{QItemSelectionModel::SelectionFlag}{Toggle} flag causes the + selection model to invert the state of the specified items, + selecting any deselected items given, and deselecting any currently + selected items. The \l{QItemSelectionModel::SelectionFlag}{Deselect} + flag deselects all the specified items. + + Individual items in the selection model are updated by creating a + selection of items, and applying them to the selection model. In the + following code, we apply a second selection of items to the table + model shown above, using the + \l{QItemSelectionModel::SelectionFlag}{Toggle} command to invert the + selection state of the items given. + + \snippet doc/src/snippets/itemselection/main.cpp 3 + + The results of this operation are displayed in the table view, + providing a convenient way of visualizing what we have achieved: + + \img selected-items2.png + + By default, the selection commands only operate on the individual + items specified by the model indexes. However, the flag used to + describe the selection command can be combined with additional flags + to change entire rows and columns. For example if you call + \l{QItemSelectionModel::select()}{select()} with only one index, but + with a command that is a combination of + \l{QItemSelectionModel::SelectionFlag}{Select} and + \l{QItemSelectionModel::SelectionFlag}{Rows}, the + entire row containing the item referred to will be selected. + The following code demonstrates the use of the + \l{QItemSelectionModel::SelectionFlag}{Rows} and + \l{QItemSelectionModel::SelectionFlag}{Columns} flags: + + \snippet doc/src/snippets/itemselection/main.cpp 4 + + Although only four indexes are supplied to the selection model, the + use of the + \l{QItemSelectionModel::SelectionFlag}{Columns} and + \l{QItemSelectionModel::SelectionFlag}{Rows} selection flags means + that two columns and two rows are selected. The following image shows + the result of these two selections: + + \img selected-items3.png + + The commands performed on the example model have all involved + accumulating a selection of items in the model. It is also possible + to clear the selection, or to replace the current selection with + a new one. + + To replace the current selection with a new selection, combine + the other selection flags with the + \l{QItemSelectionModel::SelectionFlag}{Current} flag. A command using + this flag instructs the selection model to replace its current collection + of model indexes with those specified in a call to + \l{QItemSelectionModel::select()}{select()}. + To clear all selections before you start adding new ones, + combine the other selection flags with the + \l{QItemSelectionModel::SelectionFlag}{Clear} flag. This + has the effect of resetting the selection model's collection of model + indexes. + + \section2 Selecting All Items in a Model + + To select all items in a model, it is necessary to create a + selection for each level of the model that covers all items in that + level. We do this by retrieving the indexes corresponding to the + top-left and bottom-right items with a given parent index: + + \snippet doc/src/snippets/reading-selections/window.cpp 2 + + A selection is constructed with these indexes and the model. The + corresponding items are then selected in the selection model: + + \snippet doc/src/snippets/reading-selections/window.cpp 3 + + This needs to be performed for all levels in the model. + For top-level items, we would define the parent index in the usual way: + + \snippet doc/src/snippets/reading-selections/window.cpp 1 + + For hierarchical models, the + \l{QAbstractItemModel::hasChildren()}{hasChildren()} function is used to + determine whether any given item is the parent of another level of + items. +*/ + +/*! + \page model-view-creating-models.html + \contentspage model-view-programming.html Contents + \previouspage Model Classes + \nextpage View Classes + + \title Creating New Models + + \tableofcontents + + \section1 Introduction + + The separation of functionality between the model/view components allows + models to be created that can take advantage of existing views. This + approach lets us present data from a variety of sources using standard + graphical user interface components, such as QListView, QTableView, and + QTreeView. + + The QAbstractItemModel class provides an interface that is flexible + enough to support data sources that arrange information in hierarchical + structures, allowing for the possibility that data will be inserted, + removed, modified, or sorted in some way. It also provides support for + drag and drop operations. + + The QAbstractListModel and QAbstractTableModel classes provide support + for interfaces to simpler non-hierarchical data structures, and are + easier to use as a starting point for simple list and table models. + + In this chapter, we create a simple read-only model to explore + the basic principles of the model/view architecture. Later in this + chapter, we will adapt this simple model so that items can be modified + by the user. + + For an example of a more complex model, see the + \l{itemviews/simpletreemodel}{Simple Tree Model} example. + + The requirements of QAbstractItemModel subclasses is described in more + detail in the \l{Model Subclassing Reference} document. + + \section1 Designing a Model + + When creating a new model for an existing data structure, it is important + to consider which type of model should be used to provide an interface + onto the data. If the data structure can be represented as a + list or table of items, you can subclass QAbstractListModel or + QAbstractTableModel since these classes provide suitable default + implementations for many functions. + + However, if the underlying data structure can only be represented by a + hierarchical tree structure, it is necessary to subclass + QAbstractItemModel. This approach is taken in the + \l{itemviews/simpletreemodel}{Simple Tree Model} example. + + In this chapter, we will implement a simple model based on a list of + strings, so the QAbstractListModel provides an ideal base class on + which to build. + + Whatever form the underlying data structure takes, it is + usually a good idea to supplement the standard QAbstractItemModel API + in specialized models with one that allows more natural access to the + underlying data structure. This makes it easier to populate the model + with data, yet still enables other general model/view components to + interact with it using the standard API. The model described below + provides a custom constructor for just this purpose. + + \section1 A Read-Only Example Model + + The model implemented here is a simple, non-hierarchical, read-only data + model based on the standard QStringListModel class. It has a \l QStringList + as its internal data source, and implements only what is needed to make a + functioning model. To make the implementation easier, we subclass + \l QAbstractListModel because it defines sensible default behavior for list + models, and it exposes a simpler interface than the \l QAbstractItemModel + class. + + When implementing a model it is important to remember that + \l QAbstractItemModel does not store any data itself, it merely + presents an interface that the views use to access the data. + For a minimal read-only model it is only necessary to implement a few + functions as there are default implementations for most of the + interface. The class declaration is as follows: + + + \snippet doc/src/snippets/stringlistmodel/model.h 0 + \snippet doc/src/snippets/stringlistmodel/model.h 1 + \codeline + \snippet doc/src/snippets/stringlistmodel/model.h 5 + + Apart from the model's constructor, we only need to implement two + functions: \l{QAbstractItemModel::rowCount()}{rowCount()} returns the + number of rows in the model and \l{QAbstractItemModel::data()}{data()} + returns an item of data corresponding to a specified model index. + + Well behaved models also implement + \l{QAbstractItemModel::headerData()}{headerData()} to give tree and + table views something to display in their headers. + + Note that this is a non-hierarchical model, so we don't have to worry + about the parent-child relationships. If our model was hierarchical, we + would also have to implement the + \l{QAbstractItemModel::index()}{index()} and + \l{QAbstractItemModel::parent()}{parent()} functions. + + The list of strings is stored internally in the \c stringList private + member variable. + + \section2 Dimensions of The Model + + We want the number of rows in the model to be the same as the number of + strings in the string list. We implement the + \l{QAbstractItemModel::rowCount()}{rowCount()} function with this in + mind: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 0 + + Since the model is non-hierarchical, we can safely ignore the model index + corresponding to the parent item. By default, models derived from + QAbstractListModel only contain one column, so we do not need to + reimplement the \l{QAbstractItemModel::columnCount()}{columnCount()} + function. + + \section2 Model Headers and Data + + For items in the view, we want to return the strings in the string list. + The \l{QAbstractItemModel::data()}{data()} function is responsible for + returning the item of data that corresponds to the index argument: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 1-data-read-only + + We only return a valid QVariant if the model index supplied is valid, + the row number is within the range of items in the string list, and the + requested role is one that we support. + + Some views, such as QTreeView and QTableView, are able to display headers + along with the item data. If our model is displayed in a view with headers, + we want the headers to show the row and column numbers. We can provide + information about the headers by subclassing the + \l{QAbstractItemModel::headerData()}{headerData()} function: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 2 + + Again, we return a valid QVariant only if the role is one that we support. + The orientation of the header is also taken into account when deciding the + exact data to return. + + Not all views display headers with the item data, and those that do may + be configured to hide them. Nonetheless, it is recommended that you + implement the \l{QAbstractItemModel::headerData()}{headerData()} function + to provide relevant information about the data provided by the model. + + An item can have several roles, giving out different data depending on the + role specified. The items in our model only have one role, + \l{Qt::ItemDataRole}{DisplayRole}, so we return the data + for items irrespective of the role specified. + However, we could reuse the data we provide for the + \l{Qt::ItemDataRole}{DisplayRole} in + other roles, such as the + \l{Qt::ItemDataRole}{ToolTipRole} that views can use to + display information about items in a tooltip. + + \section1 An Editable Model + + The read-only model shows how simple choices could be presented to the + user but, for many applications, an editable list model is much more + useful. We can modify the read-only model to make the items editable + by changing the data() function we implemented for read-only, and + by implementing two extra functions: + \l{QAbstractItemModel::flags()}{flags()} and + \l{QAbstractItemModel::setData()}{setData()}. + The following function declarations are added to the class definition: + + \snippet doc/src/snippets/stringlistmodel/model.h 2 + \snippet doc/src/snippets/stringlistmodel/model.h 3 + + \section2 Making the Model Editable + + A delegate checks whether an item is editable before creating an + editor. The model must let the delegate know that its items are + editable. We do this by returning the correct flags for each item in + the model; in this case, we enable all items and make them both + selectable and editable: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 3 + + Note that we do not have to know how the delegate performs the actual + editing process. We only have to provide a way for the delegate to set the + data in the model. This is achieved through the + \l{QAbstractItemModel::setData()}{setData()} function: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 4 + \snippet doc/src/snippets/stringlistmodel/model.cpp 5 + + In this model, the item in the string list that corresponds to the + model index is replaced by the value provided. However, before we + can modify the string list, we must make sure that the index is + valid, the item is of the correct type, and that the role is + supported. By convention, we insist that the role is the + \l{Qt::ItemDataRole}{EditRole} since this is the role used by the + standard item delegate. For boolean values, however, you can use + Qt::CheckStateRole and set the Qt::ItemIsUserCheckable flag; a + checkbox will then be used for editing the value. The underlying + data in this model is the same for all roles, so this detail just + makes it easier to integrate the model with standard components. + + When the data has been set, the model must let the views know that some + data has changed. This is done by emitting the + \l{QAbstractItemModel::dataChanged()}{dataChanged()} signal. Since only + one item of data has changed, the range of items specified in the signal + is limited to just one model index. + + Also the data() function needs to be changed to add the Qt::EditRole test: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 1 + + \section2 Inserting and Removing Rows + + It is possible to change the number of rows and columns in a model. In the + string list model it only makes sense to change the number of rows, so we + only reimplement the functions for inserting and removing rows. These are + declared in the class definition: + + \snippet doc/src/snippets/stringlistmodel/model.h 4 + + Since rows in this model correspond to strings in a list, the + \c insertRows() function inserts a number of empty strings into the string + list before the specified position. The number of strings inserted is + equivalent to the number of rows specified. + + The parent index is normally used to determine where in the model the + rows should be added. In this case, we only have a single top-level list + of strings, so we just insert empty strings into that list. + + \snippet doc/src/snippets/stringlistmodel/model.cpp 6 + \snippet doc/src/snippets/stringlistmodel/model.cpp 7 + + The model first calls the + \l{QAbstractItemModel::beginInsertRows()}{beginInsertRows()} function to + inform other components that the number of rows is about to change. The + function specifies the row numbers of the first and last new rows to be + inserted, and the model index for their parent item. After changing the + string list, it calls + \l{QAbstractItemModel::endInsertRows()}{endInsertRows()} to complete the + operation and inform other components that the dimensions of the model + have changed, returning true to indicate success. + + The function to remove rows from the model is also simple to write. + The rows to be removed from the model are specified by the position and + the number of rows given. + We ignore the parent index to simplify our implementation, and just + remove the corresponding items from the string list. + + \snippet doc/src/snippets/stringlistmodel/model.cpp 8 + \snippet doc/src/snippets/stringlistmodel/model.cpp 9 + + The \l{QAbstractItemModel::beginRemoveRows()}{beginRemoveRows()} function + is always called before any underlying data is removed, and specifies the + first and last rows to be removed. This allows other components to access + the data before it becomes unavailable. + After the rows have been removed, the model emits + \l{QAbstractItemModel::endRemoveRows()}{endRemoveRows()} to finish the + operation and let other components know that the dimensions of the model + have changed. + + \section1 Next Steps + + We can display the data provided by this model, or any other model, using + the \l QListView class to present the model's items in the form of a vertical + list. + For the string list model, this view also provides a default editor so that + the items can be manipulated. We examine the possibilities made available by + the standard view classes in the chapter on \l{View Classes}. + + The \l{Model Subclassing Reference} document discusses the requirements of + QAbstractItemModel subclasses in more detail, and provides a guide to the + virtual functions that must be implemented to enable various features in + different types of models. +*/ + +/*! + \page model-view-convenience.html + \contentspage model-view-programming.html Contents + \previouspage Delegate Classes + \nextpage Using Drag and Drop with Item Views + + \title Item View Convenience Classes + + \tableofcontents + + \section1 Overview + + Alongside the model/view classes, Qt 4 also includes standard widgets to + provide classic item-based container widgets. These behave in a similar + way to the item view classes in Qt 3, but have been rewritten to use the + underlying model/view framework for performance and maintainability. The + old item view classes are still available in the compatibility library + (see the \l{porting4.html}{Porting Guide} for more information). + + The item-based widgets have been given names which reflect their uses: + \c QListWidget provides a list of items, \c QTreeWidget displays a + multi-level tree structure, and \c QTableWidget provides a table of cell + items. Each class inherits the behavior of the \c QAbstractItemView + class which implements common behavior for item selection and header + management. + + \section1 List Widgets + + Single level lists of items are typically displayed using a \c QListWidget + and a number of \c{QListWidgetItem}s. A list widget is constructed in the + same way as any other widget: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 0 + + List items can be added directly to the list widget when they are + constructed: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 3 + + They can also be constructed without a parent list widget and added to + a list at some later time: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 6 + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 7 + + Each item in a list can display a text label and an icon. The colors + and font used to render the text can be changed to provide a customized + appearance for items. Tooltips, status tips, and "What's + This?" help are all easily configured to ensure that the list is properly + integrated into the application. + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 8 + + By default, items in a list are presented in the order of their creation. + Lists of items can be sorted according to the criteria given in + \l{Qt::SortOrder} to produce a list of items that is sorted in forward or + reverse alphabetical order: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 4 + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 5 + + + \section1 Tree Widgets + + Trees or hierarchical lists of items are provided by the \c QTreeWidget + and \c QTreeWidgetItem classes. Each item in the tree widget can have + child items of its own, and can display a number of columns of + information. Tree widgets are created just like any other widget: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 0 + + Before items can be added to the tree widget, the number of columns must + be set. For example, we could define two columns, and create a header + to provide labels at the top of each column: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 1 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 2 + + The easiest way to set up the labels for each section is to supply a string + list. For more sophisticated headers, you can construct a tree item, + decorate it as you wish, and use that as the tree widget's header. + + Top-level items in the tree widget are constructed with the tree widget as + their parent widget. They can be inserted in an arbitrary order, or you + can ensure that they are listed in a particular order by specifying the + previous item when constructing each item: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 3 + \codeline + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 4 + + Tree widgets deal with top-level items slightly differently to other + items from deeper within the tree. Items can be removed from the top + level of the tree by calling the tree widget's + \l{QTreeWidget::takeTopLevelItem()}{takeTopLevelItem()} function, but + items from lower levels are removed by calling their parent item's + \l{QTreeWidgetItem::takeChild()}{takeChild()} function. + Items are inserted in the top level of the tree with the + \l{QTreeWidget::insertTopLevelItem()}{insertTopLevelItem()} function. + At lower levels in the tree, the parent item's + \l{QTreeWidgetItem::insertChild()}{insertChild()} function is used. + + It is easy to move items around between the top level and lower levels + in the tree. We just need to check whether the items are top-level items + or not, and this information is supplied by each item's \c parent() + function. For example, we can remove the current item in the tree widget + regardless of its location: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 10 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 11 + + Inserting the item somewhere else in the tree widget follows the same + pattern: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 8 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 9 + + + \section1 Table Widgets + + Tables of items similar to those found in spreadsheet applications + are constructed with the \c QTableWidget and \c QTableWidgetItem. These + provide a scrolling table widget with headers and items to use within it. + + Tables can be created with a set number of rows and columns, or these + can be added to an unsized table as they are needed. + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.h 0 + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 0 + + Items are constructed outside the table before being added to the table + at the required location: + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 3 + + Horizontal and vertical headers can be added to the table by constructing + items outside the table and using them as headers: + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 1 + + Note that the rows and columns in the table begin at zero. + + \section1 Common Features + + There are a number of item-based features common to each of the + convenience classes that are available through the same interfaces + in each class. We present these in the following sections with some + examples for different widgets. + Look at the list of \l{Model/View Classes} for each of the widgets + for more details about the use of each function used. + + \section2 Hidden Items + + It is sometimes useful to be able to hide items in an item view widget + rather than remove them. Items for all of the above widgets can be + hidden and later shown again. You can determine whether an item is hidden + by calling the isItemHidden() function, and items can be hidden with + \c setItemHidden(). + + Since this operation is item-based, the same function is available for + all three convenience classes. + + \section2 Selections + + The way items are selected is controlled by the widget's selection mode + (\l{QAbstractItemView::SelectionMode}). + This property controls whether the user can select one or many items and, + in many-item selections, whether the selection must be a continuous range + of items. The selection mode works in the same way for all of the + above widgets. + + \table + \row + \i \img selection-single.png + \i \bold{Single item selections:} + Where the user needs to choose a single item from a widget, the + default \c SingleSelection mode is most suitable. In this mode, the + current item and the selected item are the same. + + \row + \i \img selection-multi.png + \i \bold{Multi-item selections:} + In this mode, the user can toggle the selection state of any item in the + widget without changing the existing selection, much like the way + non-exclusive checkboxes can be toggled independently. + + \row + \i \img selection-extended.png + \i \bold{Extended selections:} + Widgets that often require many adjacent items to be selected, such + as those found in spreadsheets, require the \c ExtendedSelection mode. + In this mode, continuous ranges of items in the widget can be selected + with both the mouse and the keyboard. + Complex selections, involving many items that are not adjacent to other + selected items in the widget, can also be created if modifier keys are + used. + + If the user selects an item without using a modifier key, the existing + selection is cleared. + \endtable + + The selected items in a widget are read using the \c selectedItems() + function, providing a list of relevant items that can be iterated over. + For example, we can find the sum of all the numeric values within a + list of selected items with the following code: + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 4 + + Note that for the single selection mode, the current item will be in + the selection. In the multi-selection and extended selection modes, the + current item may not lie within the selection, depending on the way the + user formed the selection. + + \section2 Searching + + It is often useful to be able to find items within an item view widget, + either as a developer or as a service to present to users. All three + item view convenience classes provide a common \c findItems() function + to make this as consistent and simple as possible. + + Items are searched for by the text that they contain according to + criteria specified by a selection of values from Qt::MatchFlags. + We can obtain a list of matching items with the \c findItems() + function: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 6 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 7 + + The above code causes items in a tree widget to be selected if they + contain the text given in the search string. This pattern can also be + used in the list and table widgets. +*/ + +/*! + \page model-view-dnd.html + \contentspage model-view-programming.html Contents + \previouspage Item View Convenience Classes + \nextpage Proxy Models + + \title Using Drag and Drop with Item Views + + \tableofcontents + + \section1 Overview + + Qt's drag and drop infrastructure is fully supported by the model/view framework. + Items in lists, tables, and trees can be dragged within the views, and data can be + imported and exported as MIME-encoded data. + + The standard views automatically support internal drag and drop, where items are + moved around to change the order in which they are displayed. By default, drag and + drop is not enabled for these views because they are configured for the simplest, + most common uses. To allow items to be dragged around, certain properties of the + view need to be enabled, and the items themselves must also allow dragging to occur. + + The requirements for a model that only allows items to be exported from a + view, and which does not allow data to be dropped into it, are fewer than + those for a fully-enabled drag and drop model. + + See also the \l{Model Subclassing Reference} for more information about + enabling drag and drop support in new models. + + \section1 Using Convenience Views + + Each of the types of item used with QListWidget, QTableWidget, and QTreeWidget + is configured to use a different set of flags by default. For example, each + QListWidgetItem or QTreeWidgetItem is initially enabled, checkable, selectable, + and can be used as the source of a drag and drop operation; each QTableWidgetItem + can also be edited and used as the target of a drag and drop operation. + + Although all of the standard items have one or both flags set for drag and drop, + you generally need to set various properties in the view itself to take advantage + of the built-in support for drag and drop: + + \list + \o To enable item dragging, set the view's + \l{QAbstractItemView::dragEnabled}{dragEnabled} property to \c true. + \o To allow the user to drop either internal or external items within the view, + set the view's \l{QAbstractScrollArea::}{viewport()}'s + \l{QWidget::acceptDrops}{acceptDrops} property to \c true. + \o To show the user where the item currently being dragged will be placed if + dropped, set the view's \l{QAbstractItemView::showDropIndicator}{showDropIndicator} + property. This provides the user with continuously updating information about + item placement within the view. + \endlist + + For example, we can enable drag and drop in a list widget with the following lines + of code: + + \snippet doc/src/snippets/qlistwidget-dnd/mainwindow.cpp 0 + + The result is a list widget which allows the items to be copied + around within the view, and even lets the user drag items between + views containing the same type of data. In both situations, the + items are copied rather than moved. + + To enable the user to move the items around within the view, we + must set the list widget's \l {QAbstractItemView::}{dragDropMode}: + + \snippet doc/src/snippets/qlistwidget-dnd/mainwindow.cpp 1 + + \section1 Using Model/View Classes + + Setting up a view for drag and drop follows the same pattern used with the + convenience views. For example, a QListView can be set up in the same way as a + QListWidget: + + \snippet doc/src/snippets/qlistview-dnd/mainwindow.cpp 0 + + Since access to the data displayed by the view is controlled by a model, the + model used also has to provide support for drag and drop operations. The + actions supported by a model can be specified by reimplementing the + QAbstractItemModel::supportedDropActions() function. For example, copy and + move operations are enabled with the following code: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 10 + + Although any combination of values from Qt::DropActions can be given, the + model needs to be written to support them. For example, to allow Qt::MoveAction + to be used properly with a list model, the model must provide an implementation + of QAbstractItemModel::removeRows(), either directly or by inheriting the + implementation from its base class. + + \section2 Enabling Drag and Drop for Items + + Models indicate to views which items can be dragged, and which will accept drops, + by reimplementing the QAbstractItemModel::flags() function to provide suitable + flags. + + For example, a model which provides a simple list based on QAbstractListModel + can enable drag and drop for each of the items by ensuring that the flags + returned contain the \l Qt::ItemIsDragEnabled and \l Qt::ItemIsDropEnabled + values: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 7 + + Note that items can be dropped into the top level of the model, but dragging is + only enabled for valid items. + + In the above code, since the model is derived from QStringListModel, we + obtain a default set of flags by calling its implementation of the flags() + function. + + \section2 Encoding Exported Data + + When items of data are exported from a model in a drag and drop operation, they + are encoded into an appropriate format corresponding to one or more MIME types. + Models declare the MIME types that they can use to supply items by reimplementing + the QAbstractItemModel::mimeTypes() function, returning a list of standard MIME + types. + + For example, a model that only provides plain text would provide the following + implementation: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 9 + + The model must also provide code to encode data in the advertised format. This + is achieved by reimplementing the QAbstractItemModel::mimeData() function to + provide a QMimeData object, just as in any other drag and drop operation. + + The following code shows how each item of data, corresponding to a given list of + indexes, is encoded as plain text and stored in a QMimeData object. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 8 + + Since a list of model indexes is supplied to the function, this approach is general + enough to be used in both hierarchical and non-heirarchical models. + + Note that custom datatypes must be declared as \l{QMetaObject}{meta objects} + and that stream operators must be implemented for them. See the QMetaObject + class description for details. + + \section2 Inserting Dropped Data into a Model + + The way that any given model handles dropped data depends on both its type + (list, table, or tree) and the way its contents is likely to be presented to + the user. Generally, the approach taken to accommodate dropped data should + be the one that most suits the model's underlying data store. + + Different types of model tend to handle dropped data in different ways. List + and table models only provide a flat structure in which items of data are + stored. As a result, they may insert new rows (and columns) when data is + dropped on an existing item in a view, or they may overwrite the item's + contents in the model using some of the data supplied. Tree models are + often able to add child items containing new data to their underlying data + stores, and will therefore behave more predictably as far as the user + is concerned. + + Dropped data is handled by a model's reimplementation of + QAbstractItemModel::dropMimeData(). For example, a model that handles a + simple list of strings can provide an implementation that handles data + dropped onto existing items separately to data dropped into the top level + of the model (i.e., onto an invalid item). + + The model first has to make sure that the operation should be acted on, + the data supplied is in a format that can be used, and that its destination + within the model is valid: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 0 + \snippet doc/src/snippets/qlistview-dnd/model.cpp 1 + + A simple one column string list model can indicate failure if the data + supplied is not plain text, or if the column number given for the drop + is invalid. + + The data to be inserted into the model is treated differently depending on + whether it is dropped onto an existing item or not. In this simple example, + we want to allow drops between existing items, before the first item in the + list, and after the last item. + + When a drop occurs, the model index corresponding to the parent item will + either be valid, indicating that the drop occurred on an item, or it will + be invalid, indicating that the drop occurred somewhere in the view that + corresponds to top level of the model. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 2 + + We initially examine the row number supplied to see if we can use it + to insert items into the model, regardless of whether the parent index is + valid or not. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 3 + + If the parent model index is valid, the drop occurred on an item. In this + simple list model, we find out the row number of the item and use that + value to insert dropped items into the top level of the model. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 4 + + When a drop occurs elsewhere in the view, and the row number is unusable, + we append items to the top level of the model. + + In hierarchical models, when a drop occurs on an item, it would be better to + insert new items into the model as children of that item. In the simple + example shown here, the model only has one level, so this approach is not + appropriate. + + \section2 Decoding Imported Data + + Each implementation of \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} must + also decode the data and insert it into the model's underlying data structure. + + For a simple string list model, the encoded items can be decoded and streamed + into a QStringList: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 5 + + The strings can then be inserted into the underlying data store. For consistency, + this can be done through the model's own interface: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 6 + + Note that the model will typically need to provide implementations of the + QAbstractItemModel::insertRows() and QAbstractItemModel::setData() functions. + + \sa {Item Views Puzzle Example} +*/ + +/*! + \page model-view-proxy-models.html + \contentspage model-view-programming.html Contents + \previouspage Using Drag and Drop with Item Views + \nextpage Model Subclassing Reference + + \title Proxy Models + + \tableofcontents + + \section1 Overview + + In the model/view framework, items of data supplied by a single model can be shared + by any number of views, and each of these can possibly represent the same information + in completely different ways. + Custom views and delegates are effective ways to provide radically different + representations of the same data. However, applications often need to provide + conventional views onto processed versions of the same data, such as differently-sorted + views onto a list of items. + + Although it seems appropriate to perform sorting and filtering operations as internal + functions of views, this approach does not allow multiple views to share the results + of such potentially costly operations. The alternative approach, involving sorting + within the model itself, leads to the similar problem where each view has to display + items of data that are organized according to the most recent processing operation. + + To solve this problem, the model/view framework uses proxy models to manage the + information supplied between individual models and views. Proxy models are components + that behave like ordinary models from the perspective of a view, and access data from + source models on behalf of that view. The signals and slots used by the model/view + framework ensure that each view is updated appropriately no matter how many proxy models + are placed between itself and the source model. + + \section1 Using Proxy Models + + Proxy models can be inserted between an existing model and any number of views. + Qt is supplied with a standard proxy model, QSortFilterProxyModel, that is usually + instantiated and used directly, but can also be subclassed to provide custom filtering + and sorting behavior. The QSortFilterProxyModel class can be used in the following way: + + \snippet doc/src/snippets/qsortfilterproxymodel/main.cpp 0 + \codeline + \snippet doc/src/snippets/qsortfilterproxymodel/main.cpp 1 + + Since proxy models are inherit from QAbstractItemModel, they can be connected to + any kind of view, and can be shared between views. They can also be used to + process the information obtained from other proxy models in a pipeline arrangement. + + The QSortFilterProxyModel class is designed to be instantiated and used directly + in applications. More specialized proxy models can be created by subclassing this + classes and implementing the required comparison operations. + + \section1 Customizing Proxy Models + + Generally, the type of processing used in a proxy model involves mapping each item of + data from its original location in the source model to either a different location in + the proxy model. In some models, some items may have no corresponding location in the + proxy model; these models are \e filtering proxy models. Views access items using + model indexes provided by the proxy model, and these contain no information about the + source model or the locations of the original items in that model. + + QSortFilterProxyModel enables data from a source model to be filtered before + being supplied to views, and also allows the contents of a source model to + be supplied to views as pre-sorted data. + + \section2 Custom Filtering Models + + The QSortFilterProxyModel class provides a filtering model that is fairly versatile, + and which can be used in a variety of common situations. For advanced users, + QSortFilterProxyModel can be subclassed, providing a mechanism that enables custom + filters to be implemented. + + Subclasses of QSortFilterProxyModel can reimplement two virtual functions that are + called whenever a model index from the proxy model is requested or used: + + \list + \o \l{QSortFilterProxyModel::filterAcceptsColumn()}{filterAcceptsColumn()} is used to + filter specific columns from part of the source model. + \o \l{QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} is used to filter + specific rows from part of the source model. + \endlist + + The default implementations of the above functions in QSortFilterProxyModel + return true to ensure that all items are passed through to views; reimplementations + of these functions should return false to filter out individual rows and columns. + + \section2 Custom Sorting Models + + QSortFilterProxyModel instances use Qt's built-in qStableSort() function to set up + mappings between items in the source model and those in the proxy model, allowing a + sorted hierarchy of items to be exposed to views without modifying the structure of the + source model. To provide custom sorting behavior, reimplement the + \l{QSortFilterProxyModel::lessThan()}{lessThan()} function to perform custom + comparisons. +*/ + +/*! + \page model-view-model-subclassing.html + \contentspage model-view-programming.html Contents + \previouspage Proxy Models + + \title Model Subclassing Reference + + \tableofcontents + + \section1 Introduction + + Model subclasses need to provide implementations of many of the virtual functions + defined in the QAbstractItemModel base class. The number of these functions that need + to be implemented depends on the type of model - whether it supplies views with + a simple list, a table, or a complex hierarchy of items. Models that inherit from + QAbstractListModel and QAbstractTableModel can take advantage of the default + implementations of functions provided by those classes. Models that expose items + of data in tree-like structures must provide implementations for many of the + virtual functions in QAbstractItemModel. + + The functions that need to be implemented in a model subclass can be divided into three + groups: + + \list + \o \bold{Item data handling:} All models need to implement functions to enable views and + delegates to query the dimensions of the model, examine items, and retrieve data. + \o \bold{Navigation and index creation:} Hierarchical models need to provide functions + that views can call to navigate the tree-like structures they expose, and obtain + model indexes for items. + \o \bold{Drag and drop support and MIME type handling:} Models inherit functions that + control the way that internal and external drag and drop operations are performed. + These functions allow items of data to be described in terms of MIME types that + other components and applications can understand. + \endlist + + For more information, see the \l + {"Item View Classes" Chapter of C++ GUI Programming with Qt 4}. + + \section1 Item Data Handling + + Models can provide varying levels of access to the data they provide: They can be + simple read-only components, some models may support resizing operations, and + others may allow items to be edited. + + \section2 Read-Only Access + + To provide read-only access to data provided by a model, the following functions + \e{must} be implemented in the model's subclass: + + \table 90% + \row \o \l{QAbstractItemModel::flags()}{flags()} + \o Used by other components to obtain information about each item provided by + the model. In many models, the combination of flags should include + Qt::ItemIsEnabled and Qt::ItemIsSelectable. + \row \o \l{QAbstractItemModel::data()}{data()} + \o Used to supply item data to views and delegates. Generally, models only + need to supply data for Qt::DisplayRole and any application-specific user + roles, but it is also good practice to provide data for Qt::ToolTipRole, + Qt::AccessibleTextRole, and Qt::AccessibleDescriptionRole. + See the Qt::ItemDataRole enum documentation for information about the types + associated with each role. + \row \o \l{QAbstractItemModel::headerData()}{headerData()} + \o Provides views with information to show in their headers. The information is + only retrieved by views that can display header information. + \row \o \l{QAbstractItemModel::rowCount()}{rowCount()} + \o Provides the number of rows of data exposed by the model. + \endtable + + These four functions must be implemented in all types of model, including list models + (QAbstractListModel subclasses) and table models (QAbstractTableModel subclasses). + + Additionally, the following functions \e{must} be implemented in direct subclasses + of QAbstractTableModel and QAbstractItemModel: + + \table 90% + \row \o \l{QAbstractItemModel::columnCount()}{columnCount()} + \o Provides the number of columns of data exposed by the model. List models do not + provide this function because it is already implemented in QAbstractListModel. + \endtable + + \section2 Editable Items + + Editable models allow items of data to be modified, and may also provide + functions to allow rows and columns to be inserted and removed. To enable + editing, the following functions must be implemented correctly: + + \table 90% + \row \o \l{QAbstractItemModel::flags()}{flags()} + \o Must return an appropriate combination of flags for each item. In particular, + the value returned by this function must include \l{Qt::ItemIsEditable} in + addition to the values applied to items in a read-only model. + \row \o \l{QAbstractItemModel::setData()}{setData()} + \o Used to modify the item of data associated with a specified model index. + To be able to accept user input, provided by user interface elements, this + function must handle data associated with Qt::EditRole. + The implementation may also accept data associated with many different kinds + of roles specified by Qt::ItemDataRole. After changing the item of data, + models must emit the \l{QAbstractItemModel::dataChanged()}{dataChanged()} + signal to inform other components of the change. + \row \o \l{QAbstractItemModel::setHeaderData()}{setHeaderData()} + \o Used to modify horizontal and vertical header information. After changing + the item of data, models must emit the + \l{QAbstractItemModel::headerDataChanged()}{headerDataChanged()} + signal to inform other components of the change. + \endtable + + \section2 Resizable Models + + All types of model can support the insertion and removal of rows. Table models + and hierarchical models can also support the insertion and removal of columns. + It is important to notify other components about changes to the model's dimensions + both \e before and \e after they occur. As a result, the following functions + can be implemented to allow the model to be resized, but implementations must + ensure that the appropriate functions are called to notify attached views and + delegates: + + \table 90% + \row \o \l{QAbstractItemModel::insertRows()}{insertRows()} + \o Used to add new rows and items of data to all types of model. + Implementations must call + \l{QAbstractItemModel::beginInsertRows()}{beginInsertRows()} \e before + inserting new rows into any underlying data structures, and call + \l{QAbstractItemModel::endInsertRows()}{endInsertRows()} + \e{immediately afterwards}. + \row \o \l{QAbstractItemModel::removeRows()}{removeRows()} + \o Used to remove rows and the items of data they contain from all types of model. + Implementations must call + \l{QAbstractItemModel::beginRemoveRows()}{beginRemoveRows()} + \e before inserting new columns into any underlying data structures, and call + \l{QAbstractItemModel::endRemoveRows()}{endRemoveRows()} + \e{immediately afterwards}. + \row \o \l{QAbstractItemModel::insertColumns()}{insertColumns()} + \o Used to add new columns and items of data to table models and hierarchical models. + Implementations must call + \l{QAbstractItemModel::beginInsertColumns()}{beginInsertColumns()} \e before + rows are removed from any underlying data structures, and call + \l{QAbstractItemModel::endInsertColumns()}{endInsertColumns()} + \e{immediately afterwards}. + \row \o \l{QAbstractItemModel::removeColumns()}{removeColumns()} + \o Used to remove columns and the items of data they contain from table models and + hierarchical models. + Implementations must call + \l{QAbstractItemModel::beginRemoveColumns()}{beginRemoveColumns()} + \e before columns are removed from any underlying data structures, and call + \l{QAbstractItemModel::endRemoveColumns()}{endRemoveColumns()} + \e{immediately afterwards}. + \endtable + + Generally, these functions should return true if the operation was successful. + However, there may be cases where the operation only partly succeeded; for example, + if less than the specified number of rows could be inserted. In such cases, the + model should return false to indicate failure to enable any attached components to + handle the situation. + + The signals emitted by the functions called in implementations of the resizing + API give attached components the chance to take action before any data becomes + unavailable. The encapsulation of insert and remove operations with begin and end + functions also enable the model to manage + \l{QPersistentModelIndex}{persistent model indexes} correctly. + + Normally, the begin and end functions are capable of informing other components + about changes to the model's underlying structure. For more complex changes to the + model's structure, perhaps involving internal reorganization or sorting of data, + it is necessary to emit the \l{QAbstractItemModel::layoutChanged()}{layoutChanged()} + signal to cause any attached views to be updated. + + \section2 Lazy Population of Model Data + + Lazy population of model data effectively allows requests for information + about the model to be deferred until it is actually needed by views. + + Some models need to obtain data from remote sources, or must perform + time-consuming operations to obtain information about the way the + data is organized. Since views generally request as much information + as possible in order to accurately display model data, it can be useful + to restrict the amount of information returned to them to reduce + unnecessary follow-up requests for data. + + In hierarchical models where finding the number of children of a given + item is an expensive operation, it is useful to ensure that the model's + \l{QAbstractItemModel::}{rowCount()} implementation is only called when + necessary. In such cases, the \l{QAbstractItemModel::}{hasChildren()} + function can be reimplemented to provide an inexpensive way for views to + check for the presence of children and, in the case of QTreeView, draw + the appropriate decoration for their parent item. + + Whether the reimplementation of \l{QAbstractItemModel::}{hasChildren()} + returns \c true or \c false, it may not be necessary for the view to call + \l{QAbstractItemModel::}{rowCount()} to find out how many children are + present. For example, QTreeView does not need to know how many children + there are if the parent item has not been expanded to show them. + + If it is known that many items will have children, reimplementing + \l{QAbstractItemModel::}{hasChildren()} to unconditionally return \c true + is sometimes a useful approach to take. This ensures that each item can + be later examined for children while making initial population of model + data as fast as possible. The only disadvantage is that items without + children may be displayed incorrectly in some views until the user + attempts to view the non-existent child items. + + + \section1 Navigation and Model Index Creation + + Hierarchical models need to provide functions that views can call to navigate the + tree-like structures they expose, and obtain model indexes for items. + + \section2 Parents and Children + + Since the structure exposed to views is determined by the underlying data + structure, it is up to each model subclass to create its own model indexes + by providing implementations of the following functions: + + \table 90% + \row \o \l{QAbstractItemModel::index()}{index()} + \o Given a model index for a parent item, this function allows views and delegates + to access children of that item. If no valid child item - corresponding to the + specified row, column, and parent model index, can be found, the function + must return QModelIndex(), which is an invalid model index. + \row \o \l{QAbstractItemModel::parent()}{parent()} + \o Provides a model index corresponding to the parent of any given child item. + If the model index specified corresponds to a top-level item in the model, or if + there is no valid parent item in the model, the function must return + an invalid model index, created with the empty QModelIndex() constructor. + \endtable + + Both functions above use the \l{QAbstractItemModel::createIndex()}{createIndex()} + factory function to generate indexes for other components to use. It is normal for + models to supply some unique identifier to this function to ensure that + the model index can be re-associated with its corresponding item later on. + + \section1 Drag and Drop Support and MIME Type Handling + + The model/view classes support drag and drop operations, providing default behavior + that is sufficient for many applications. However, it is also possible to customize + the way items are encoded during drag and drop operations, whether they are copied + or moved by default, and how they are inserted into existing models. + + Additionally, the convenience view classes implement specialized behavior that + should closely follow that expected by existing developers. + The \l{#Convenience Views}{Convenience Views} section provides an overview of this + behavior. + + \section2 MIME Data + + By default, the built-in models and views use an internal MIME type + (\c{application/x-qabstractitemmodeldatalist}) to pass around information about + model indexes. This specifies data for a list of items, containing the row and + column numbers of each item, and information about the roles that each item + supports. + + Data encoded using this MIME type can be obtained by calling + QAbstractItemModel::mimeData() with a QModelIndexList containing the items to + be serialized. + \omit + The following types are used to store information about + each item as it is streamed into a QByteArray and stored in a QMimeData object: + + \table 90% + \header \o Description \o Type + \row \o Row \o int + \row \o Column \o int + \row \o Data for each role \o QMap<int, QVariant> + \endtable + + This information can be retrieved for use in non-model classes by calling + QMimeData::data() with the \c{application/x-qabstractitemmodeldatalist} MIME + type and streaming out the items one by one. + \endomit + + When implementing drag and drop support in a custom model, it is possible to + export items of data in specialized formats by reimplementing the following + function: + + \table 90% + \row \o \l{QAbstractItemModel::mimeData()}{mimeData()} + \o This function can be reimplemented to return data in formats other + than the default \c{application/x-qabstractitemmodeldatalist} internal + MIME type. + + Subclasses can obtain the default QMimeData object from the base class + and add data to it in additional formats. + \endtable + + For many models, it is useful to provide the contents of items in common format + represented by MIME types such as \c{text/plain} and \c{image/png}. Note that + images, colors and HTML documents can easily be added to a QMimeData object with + the QMimeData::setImageData(), QMimeData::setColorData(), and + QMimeData::setHtml() functions. + + \section2 Accepting Dropped Data + + When a drag and drop operation is performed over a view, the underlying model is + queried to determine which types of operation it supports and the MIME types + it can accept. This information is provided by the + QAbstractItemModel::supportedDropActions() and QAbstractItemModel::mimeTypes() + functions. Models that do not override the implementations provided by + QAbstractItemModel support copy operations and the default internal MIME type + for items. + + When serialized item data is dropped onto a view, the data is inserted into + the current model using its implementation of QAbstractItemModel::dropMimeData(). + The default implementation of this function will never overwrite any data in the + model; instead, it tries to insert the items of data either as siblings of an + item, or as children of that item. + + To take advantage of QAbstractItemModel's default implementation for the built-in + MIME type, new models must provide reimplementations of the following functions: + + \table 90% + \row \o \l{QAbstractItemModel::insertRows()}{insertRows()} + \o {1, 2} These functions enable the model to automatically insert new data using + the existing implementation provided by QAbstractItemModel::dropMimeData(). + \row \o \l{QAbstractItemModel::insertColumns()}{insertColumns()} + \row \o \l{QAbstractItemModel::setData()}{setData()} + \o Allows the new rows and columns to be populated with items. + \row \o \l{QAbstractItemModel::setItemData()}{setItemData()} + \o This function provides more efficient support for populating new items. + \endtable + + To accept other forms of data, these functions must be reimplemented: + + \table 90% + \row \o \l{QAbstractItemModel::supportedDropActions()}{supportedDropActions()} + \o Used to return a combination of \l{Qt::DropActions}{drop actions}, + indicating the types of drag and drop operations that the model accepts. + \row \o \l{QAbstractItemModel::mimeTypes()}{mimeTypes()} + \o Used to return a list of MIME types that can be decoded and handled by + the model. Generally, the MIME types that are supported for input into + the model are the same as those that it can use when encoding data for + use by external components. + \row \o \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} + \o Performs the actual decoding of the data transferred by drag and drop + operations, determines where in the model it will be set, and inserts + new rows and columns where necessary. How this function is implemented + in subclasses depends on the requirements of the data exposed by each + model. + \endtable + + If the implementation of the \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} + function changes the dimensions of a model by inserting or removing rows or + columns, or if items of data are modified, care must be taken to ensure that + all relevant signals are emitted. It can be useful to simply call + reimplementations of other functions in the subclass, such as + \l{QAbstractItemModel::setData()}{setData()}, + \l{QAbstractItemModel::insertRows()}{insertRows()}, and + \l{QAbstractItemModel::insertColumns()}{insertColumns()}, to ensure that the + model behaves consistently. + + In order to ensure drag operations work properly, it is important to + reimplement the following functions that remove data from the model: + + \list + \o \l{QAbstractItemModel::}{removeRows()} + \o \l{QAbstractItemModel::}{removeRow()} + \o \l{QAbstractItemModel::}{removeColumns()} + \o \l{QAbstractItemModel::}{removeColumn()} + \endlist + + For more information about drag and drop with item views, refer to + \l{Using Drag and Drop with Item Views}. + + \section2 Convenience Views + + The convenience views (QListWidget, QTableWidget, and QTreeWidget) override + the default drag and drop functionality to provide less flexible, but more + natural behavior that is appropriate for many applications. For example, + since it is more common to drop data into cells in a QTableWidget, replacing + the existing contents with the data being transferred, the underlying model + will set the data of the target items rather than insert new rows and columns + into the model. For more information on drag and drop in convenience views, + you can see \l{Using Drag and Drop with Item Views}. + + \section1 Performance Optimization for Large Amounts of Data + + The \l{QAbstractItemModel::}{canFetchMore()} function checks if the parent + has more data available and returns true or false accordingly. The + \l{QAbstractItemModel::}{fetchMore()} function fetches data based on the + parent specified. Both these functions can be combined, for example, in a + database query involving incremental data to populate a QAbstractItemModel. + We reimplement \l{QAbstractItemModel::}{canFetchMore()} to indicate if there + is more data to be fetched and \l{QAbstractItemModel::}{fetchMore()} to + populate the model as required. + + Another example would be dynamically populated tree models, where we + reimplement \l{QAbstractItemModel::}{fetchMore()} when a branch in the tree + model is expanded. + + If your reimplementation of \l{QAbstractItemModel::}{fetchMore()} adds rows + to the model, you need to call \l{QAbstractItemModel::}{beginInsertRows()} + and \l{QAbstractItemModel::}{endInsertRows()}. Also, both + \l{QAbstractItemModel::}{canFetchMore()} and \l{QAbstractItemModel::} + {fetchMore()} must be reimplemented as their default implementation returns + false and does nothing. +*/ diff --git a/doc/src/frameworks-technologies/phonon.qdoc b/doc/src/frameworks-technologies/phonon.qdoc new file mode 100644 index 000000000..be203f3ec --- /dev/null +++ b/doc/src/frameworks-technologies/phonon.qdoc @@ -0,0 +1,558 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page phonon-overview.html + \title Phonon Overview + \ingroup frameworks-technologies + + \tableofcontents + + \section1 Introduction + + Qt uses the Phonon multimedia framework to provide functionality + for playback of the most common multimedia formats. The media can + be read from files or streamed over a network, using a QURL to a + file. + + In this overview, we take a look at the main concepts of Phonon. + We also explain the architecture, examine the + core API classes, and show examples on how to use the classes + provided. + + \section1 Architecture + + Phonon has three basic concepts: media objects, sinks, and paths. + A media object manages a media source, for instance, a music file; + it provides simple playback control, such as starting, stopping, + and pausing the playback. A sink outputs the media from Phonon, + e.g., by rendering video on a widget, or by sending audio to a + sound card. Paths are used to connect Phonon objects, i.e., a + media object and a sink, in a graph - called a media graph in + Phonon. + + As an example, we show a media graph for an audio stream: + + \image conceptaudio.png + + The playback is started and managed by the media object, which + send the media stream to any sinks connected to it by a path. The + sink then plays the stream back, usually though a sound card. + + \omit Not sure if this goes here, or anywhere... + All nodes in the graph are synchronized by the framework, + meaning that if more than one sink is connected to the same + media object, the framework will handle the synchronization + between the sinks; this happens for instance when a media + source containing video with sound is played back. More on + this later. + \endomit + + \section2 Media Objects + + The media object, an instance of the \l{Phonon::}{MediaObject} + class, lets you start, pause, and stop the playback of a media + stream, i.e., it provided basic control over the playback. You may + think of the object as a simple media player. + + The media data is provided by a media source, which is + kept by the media object. The media source is a separate + object - an instance of \l{Phonon::}{MediaSource} - in Phonon, and + not part of the graph itself. The source will supply the media + object with raw data. The data can be read from files and streamed + over a network. The contents of the source will be interpreted by + the media object. + + A media object is always instantiated with the default constructor + and then supplied with a media source. Concrete code examples are + given later in this overview. + + As a complement to the media object, Phonon also provides + \l{Phonon::}{MediaController}, which provides control over + features that are optional for a given media. For instance, for + chapters, menus, and titles of a VOB (DVD) file will be features + managed by a \l{Phonon::}{MediaController}. + + \section2 Sinks + + A sink is a node that can output media from the graph, i.e., it + does not send its output to other nodes. A sink is usually a + rendering device. + + The input of sinks in a Phonon media graph comes from a + \l{Phonon::}{MediaObject}, though it might have been processed + through other nodes on the way. + + While the \l{Phonon::}{MediaObject} controls the playback, the + sink has basic controls for manipulation of the media. With an + audio sink, for instance, you can control the volume and mute the + sound, i.e., it represents a virtual audio device. Another example + is the \l{Phonon::}{VideoWidget}, which can render video on a + QWidget and alter the brightness, hue, and scaling of the video. + + As an example we give an image of a graph used for playing back a + video file with sound. + + \image conceptvideo.png + + \section2 Processors + + Phonon does not allow manipulation of media streams directly, + i.e., one cannot alter a media stream's bytes programmatically + after they have been given to a media object. We have other nodes + to help with this: processors, which are placed in the graph on + the path somewhere between the media object and its sinks. In + Phonon, processors are of the \l{Phonon::}{Effect} class. + + When inserted into the rendering process, the processor will + alter the media stream, and will be active as long as it is part + of the graph. To stop, it needs to be removed. + + \omit \image conceptprocessor.png \endomit + + The \c {Effect}s may also have controls that affect how the media + stream is manipulated. A processor applying a depth effect to + audio, for instance, can have a value controlling the amount of + depth. An \c Effect can be configured at any point in time. + + \section1 Playback + + In some common cases, it is not necessary to build a graph + yourself. + + Phonon has convenience functions for building common graphs. For + playing an audio file, you can use the + \l{Phonon::}{createPlayer()} function. This will set up the + necessary graph and return the media object node; the sound can + then be started by calling its \l{Phonon::MediaObject::}{play()} + function. + + \snippet snippets/phonon.cpp 0 + + We have a similar solution for playing video files, the + \l{Phonon::}{VideoPlayer}. + + \snippet snippets/phonon.cpp 1 + + The VideoPlayer is a widget onto which the video will be drawn. + + The \c .pro file for a project needs the following line to be added: + + \snippet doc/src/snippets/code/doc_src_phonon.qdoc 0 + + Phonon comes with several widgets that provide functionality + commonly associated with multimedia players - notably SeekSlider + for controlling the position of the stream, VolumeSlider for + controlling sound volume, and EffectWidget for controlling the + parameters of an effect. You can learn about them in the API + documentation. + + \section1 Building Graphs + + If you need more freedom than the convenience functions described + in the previous section offers you, you can build the graphs + yourself. We will now take a look at how some common graphs are + built. Starting a graph up is a matter of calling the + \l{Phonon::MediaObject::}{play()} function of the media object. + + If the media source contains several types of media, for instance, a + stream with both video and audio, the graph will contain two + output nodes: one for the video and one for the audio. + + We will now look at the code required to build the graphs discussed + previously in the \l{Architecture} section. + + \section2 Audio + + When playing back audio, you create the media object and connect + it to an audio output node - a node that inherits from + AbstractAudioOutput. Currently, AudioOutput, which outputs audio + to the sound card, is provided. + + The code to create the graph is straight forward: + + \snippet snippets/phonon.cpp 2 + + Notice that the type of media an input source has is resolved by + Phonon, so you need not be concerned with this. If a source + contains multiple media formats, this is also handled + automatically. + + The media object is always created using the default constructor + since it handles all multimedia formats. + + The setting of a Category, Phonon::MusicCategory in this case, + does not affect the actual playback; the category can be used by + KDE to control the playback through, for instance, the control + panel. + + \omit Not sure about this + Users of KDE can often also choose to send sound with the + CommunicationCategory, e.g., given to VoIP, to their headset, + while sound with MusicCategory is sent to the sound card. + \endomit + + The AudioOutput class outputs the audio media to a sound card, + that is, one of the audio devices of the operating system. An + audio device can be a sound card or a intermediate technology, + such as \c DirectShow on windows. A default device will be chosen + if one is not set with \l{Phonon::AudioOutput::}{setOutputDevice()}. + + The AudioOutput node will work with all audio formats supported by + the back end, so you don't need to know what format a specific + media source has. + + For a an extensive example of audio playback, see the \l{Music + Player Example}{Phonon Music Player}. + + \section3 Audio Effects + + Since a media stream cannot be manipulated directly, the backend + can produce nodes that can process the media streams. These nodes + are inserted into the graph between a media object and an output + node. + + Nodes that process media streams inherit from the Effect class. + The effects available depends on the underlying system. Most of + these effects will be supported by Phonon. See the \l{Querying + Backends for Support} section for information on how to resolve + the available effects on a particular system. + + We will now continue the example from above using the Path + variable \c path to add an effect. The code is again trivial: + + \snippet snippets/phonon.cpp 3 + + Here we simply take the first available effect on the system. + + The effect will start immediately after being inserted into the + graph if the media object is playing. To stop it, you have to + detach it again using \l{Phonon::Path::}{removeEffect()} of the Path. + + \section2 Video + + For playing video, VideoWidget is provided. This class functions + both as a node in the graph and as a widget upon which it draws + the video stream. The widget will automatically choose an available + device for playing the video, which is usually a technology + between the Qt application and the graphics card, such as \c + DirectShow on Windows. + + The video widget does not play the audio (if any) in the media + stream. If you want to play the audio as well, you will need + an AudioOutput node. You create and connect it to the graph as + shown in the previous section. + + The code for creating this graph is given below, after which + one can play the video with \l{Phonon::MediaObject::}{play()}. + + \snippet snippets/phonon.cpp 4 + + The VideoWidget does not need to be set to a Category, it is + automatically classified to \l{Phonon::}{VideoCategory}, we only + need to assure that the audio is also classified in the same + category. + + The media object will split files with different media content + into separate streams before sending them off to other nodes in + the graph. It is the media object that determines the type of + content appropriate for nodes that connect to it. + + \omit This section is from the future + + \section2 Multiple Audio Sources and Graph Outputs + + In this section, we take a look at a graph that contains multiple + audio sources in addition to video. We have a video camera with + some embarrassing home footage from last weekend's party, a + microphone with which we intend to add commentary, and an audio + music file to set the correct mood. It would be an advantage to + write the graph output to a file for later viewing, but since this + is not yet supported by Qt backends, we will play it back + directly. + + <image of party graph> + + <code> + + <code walkthrough> + + \endomit + + \section1 Backends + + The multimedia functionality is not implemented by Phonon itself, + but by a back end - often also referred to as an engine. This + includes connecting to, managing, and driving the underlying + hardware or intermediate technology. For the programmer, this + implies that the media nodes, e.g., media objects, processors, and + sinks, are produced by the back end. Also, it is responsible for + building the graph, i.e., connecting the nodes. + + The backends of Qt use the media systems DirectShow (which + requires DirectX) on Windows, QuickTime on Mac, and GStreamer on + Linux. The functionality provided on the different platforms are + dependent on these underlying systems and may vary somewhat, e.g., + in the media formats supported. + + Backends expose information about the underlying system. It can + tell which media formats are supported, e.g., \c AVI, \c mp3, or + \c OGG. + + A user can often add support for new formats and filters to the + underlying system, by, for instance, installing the DivX codex. We + can therefore not give an exact overview of which formats are + available with the Qt backends. + + \omit Not sure I want a separate section for this + \section2 Communication with the Backends + + We cooperate with backends through static functions in the + Phonon namespace. We have already seen some of these functions + in code examples. Their two main responsibilities are creating + graph nodes and supplying information about the capabilities + of the various nodes. The nodes uses the backend internally + when created, so it is only connecting them in the graph that + you need to use the backend directly. + + The main functions for graph building are: + + \list + \o createPath(): This function creates a path between to + nodes, which it takes as arguments. + \o + \endlist + + For more detailed information, please consult the API + documentation. + + \endomit + + \section2 Querying Backends for Support + + As mentioned, Phonon depends on the backend to provide its + functionality. Depending on the individual backend, full support + of the API may not be in place. Applications therefore need to + check with the backend if functionality they require is + implemented. In this section, we take look at how this is done. + + The backend provides the + \l{Phonon::BackendCapabilities::}{availableMimeTypes()} and + \l{Phonon::BackendCapabilities::}{isMimeTypeAvailable()} functions + to query which MIME types the backend can produce nodes for. The + types are listed as strings, which for any type is equal for any + backend or platform. + + The backend will emit a signal - + \l{Phonon::BackendCapabilities::}{Notifier::capabilitiesChanged()} + - if its abilities have changed. If the available audio devices + have changed, the + \l{Phonon::BackendCapabilities::}{Notifier::availableAudioOutputDevicesChanged()} + signal is emitted instead. + + To query the actual audio devices possible, we have the + \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} as + mentioned in the \l{#Sinks}{Sinks} section. To query information + about the individual devices, you can examine its \c name(); this + string is dependent on the operating system, and the Qt backends + does not analyze the devices further. + + The sink for playback of video does not have a selection of + devices. For convenience, the \l{Phonon::}{VideoWidget} is both a + node in the graph and a widget on which the video output is + rendered. To query the various video formats available, use + \l{Phonon::BackendCapabilities::}{isMimeTypeAvailable()}. To add + it to a path, you can use the Phonon::createPath() as usual. After + creating a media object, it is also possible to call its + \l{Phonon::MediaObject::}{hasVideo()} function. + + See also the \l{Capabilities Example}. + + \section1 Installing Phonon + + When running the Qt configure script, you will be notified whether + Phonon support is available on your system. As mentioned + previously, to use develop and run Phonon applications, you also + need to link to a backend, which provides the multimedia + functionality. + + Note that Phonon applications will compile and run without a + working backend, but will, of course, not work as expected. + + The following sections explains requirements for each backend. + + \section2 Windows + + On Windows, building Phonon requires DirectX and DirectShow + version 9 or higher. You'll need additional SDKs you can download + from Microsoft. + + \section3 Windows XP and later Windows versions + + If you develop for Windows XP and up, you should download the Windows SDK + \l{http://www.microsoft.com/downloads/details.aspx?FamilyID=e6e1c3df-a74f-4207-8586-711ebe331cdc&DisplayLang=en}{here}. + Before building Qt, just call the script: \c {C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin\setenv.cmd} + + \note Visual C++ 2008 already contains the Windows SDK and doesn't + need that package and has already the environment set up for a + smooth compilation of phonon. + + \section3 Earlier Windows versions than Windows XP + + If you want to support previous Windows versions, you should download and install the Platform SDK. You find it + \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en}{here}. + + \note The platform SDK provided with Visual C++ is not + complete and + you'll need this one to have DirectShow 9.0 support. You can download the DirectX SDK + \l{http://www.microsoft.com/downloads/details.aspx?familyid=09F7578C-24AA-4E0A-BF91-5FEC24C8C7BF&displaylang=en}{here}. + + \section3 Setting up the environment + + Once the SDKs are installed, please make sure to set your + environment variables LIB and INCLUDE correctly. The paths to the + include and lib directory of the SDKs should appear first. + Typically, to setup your environment, you would execute the + following script: + + \code + Set DXSDK_DIR=C:\Program Files\Microsoft DirectX SDK (February 2007) + %DXSDK_DIR%\utilities\bin\dx_setenv.cmd + C:\program files\Microsoft Platform SDK\setenv.cmd + \endcode + + If your environment is setup correctly, executing configure.exe on + your Qt installation should automatically activate Phonon. + + \warning The MinGW version of Qt does not support building the + Qt backend. + + \section2 Linux + + The Qt backend on Linux uses GStreamer (minimum version is 0.10), + which must be installed on the system. At a minimum, you need the + GStreamer library and base plugins, which provides support for \c + .ogg files. The package names may vary between Linux + distributions; on Mandriva, they have the following names: + + \table + \header + \o Package + \o Description + \row + \o libgstreamer0.10_0.10 + \o The GStreamer base library. + \row + \o libgstreamer0.10_0.10-devel + \o Contains files for developing applications with + GStreamer. + \row + \o libgstreamer-plugins-base0.10 + \o Contains the basic plugins for audio and video + playback, and will enable support for \c ogg files. + \row + \o libgstreamer-plugins-base0.10-devel + \o Makes it possible to develop applications using the + base plugins. + \endtable + + \omit Should go in troubleshooting (in for example README) + alsasink backend for GStreamer + \table + \header + \o Variable + \o Description + \row + \o PHONON_GST_AUDIOSINK + \o Sets the audio sink to be used. Possible values are + ... alsasink. + \row + \o PHONON_GSTREAMER_DRIVER + \o Sets the driver for GStreamer. This driver will + usually be configured automatically when + installing. + \row + \o PHONON_GST_VIDEOWIDGET + \o This variable can be set to the name of a widget to + use as the video widget?? + \row + \o PHONON_GST_DEBUG + \o Phonon will give debug information while running if + this variable is set to a number between 1 and 3. + \row + \o PHONON_TESTURL + \o ... + \endtable + \endomit + + \section2 Mac OS X + + On Mac OS X, Qt uses QuickTime for its backend. The minimum + supported version is 7.0. + + \section1 Deploying Phonon Applications on Windows and Mac OS X + + On Windows and Mac OS X, the Qt backend makes use of the + \l{QtOpenGL Module}{QtOpenGL} module. You therefore need to deploy + the QtOpenGL shared library. If this is not what you want, it is + possible to configure Qt without OpenGL support. In that case, you + need to run \c configure with the \c -no-opengl option. + + \section1 Work in Progress + + Phonon and its Qt backends, though fully functional for + multimedia playback, are still under development. Functionality to + come is the possibility to capture media and more processors for + both music and video files. + + Another important consideration is to implement support for + storing media to files; i.e., not playing back media directly. + + We also hope in the future to be able to support direct + manipulation of media streams. This will give the programmer more + freedom to manipulate streams than just through processors. + + Currently, the multimedia framework supports one input source. It will be + possible to include several sources. This is useful in, for example, audio + mixer applications where several audio sources can be sent, processed and + output as a single audio stream. +*/ + diff --git a/doc/src/frameworks-technologies/plugins-howto.qdoc b/doc/src/frameworks-technologies/plugins-howto.qdoc new file mode 100644 index 000000000..1321dda14 --- /dev/null +++ b/doc/src/frameworks-technologies/plugins-howto.qdoc @@ -0,0 +1,325 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group plugins + \title Plugin Classes + \ingroup groups + + \brief Plugin related classes. + + These classes deal with shared libraries, (e.g. .so and DLL files), + and with Qt plugins. + + See the \link plugins-howto.html plugins documentation\endlink. + + See also the \l{ActiveQt framework} for Windows. +*/ + +/*! + \page plugins-howto.html + \title How to Create Qt Plugins + \brief A guide to creating plugins to extend Qt applications and + functionality provided by Qt. + + \ingroup frameworks-technologies + + \keyword QT_DEBUG_PLUGINS + \keyword QT_NO_PLUGIN_CHECK + + Qt provides two APIs for creating plugins: + + \list + \o A higher-level API for writing extensions to Qt itself: custom database + drivers, image formats, text codecs, custom styles, etc. + \o A lower-level API for extending Qt applications. + \endlist + + For example, if you want to write a custom QStyle subclass and + have Qt applications load it dynamically, you would use the + higher-level API. + + Since the higher-level API is built on top of the lower-level API, + some issues are common to both. + + If you want to provide plugins for use with \QD, see the QtDesigner + module documentation. + + Topics: + + \tableofcontents + + \section1 The Higher-Level API: Writing Qt Extensions + + Writing a plugin that extends Qt itself is achieved by + subclassing the appropriate plugin base class, implementing a few + functions, and adding a macro. + + There are several plugin base classes. Derived plugins are stored + by default in sub-directories of the standard plugin directory. Qt + will not find plugins if they are not stored in the right + directory. + + \table + \header \o Base Class \o Directory Name \o Key Case Sensitivity + \row \o QAccessibleBridgePlugin \o \c accessiblebridge \o Case Sensitive + \row \o QAccessiblePlugin \o \c accessible \o Case Sensitive + \row \o QDecorationPlugin \o \c decorations \o Case Insensitive + \row \o QFontEnginePlugin \o \c fontengines \o Case Insensitive + \row \o QIconEnginePlugin \o \c iconengines \o Case Insensitive + \row \o QImageIOPlugin \o \c imageformats \o Case Sensitive + \row \o QInputContextPlugin \o \c inputmethods \o Case Sensitive + \row \o QKbdDriverPlugin \o \c kbddrivers \o Case Insensitive + \row \o QMouseDriverPlugin \o \c mousedrivers \o Case Insensitive + \row \o QScreenDriverPlugin \o \c gfxdrivers \o Case Insensitive + \row \o QScriptExtensionPlugin \o \c script \o Case Sensitive + \row \o QSqlDriverPlugin \o \c sqldrivers \o Case Sensitive + \row \o QStylePlugin \o \c styles \o Case Insensitive + \row \o QTextCodecPlugin \o \c codecs \o Case Sensitive + \endtable + + Suppose that you have a new style class called \c MyStyle that you + want to make available as a plugin. The required code is + straightforward, here is the class definition (\c + mystyleplugin.h): + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 0 + + Ensure that the class implementation is located in a \c .cpp file + (including the class definition): + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 1 + + (Note that QStylePlugin is case insensitive, and the lower-case + version of the key is used in our + \l{QStylePlugin::create()}{create()} implementation; most other + plugins are case sensitive.) + + For database drivers, image formats, text codecs, and most other + plugin types, no explicit object creation is required. Qt will + find and create them as required. Styles are an exception, since + you might want to set a style explicitly in code. To apply a + style, use code like this: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 2 + + Some plugin classes require additional functions to be + implemented. See the class documentation for details of the + virtual functions that must be reimplemented for each type of + plugin. + + The \l{Style Plugin Example} shows how to implement a plugin + that extends the QStylePlugin base class. + + \section1 The Lower-Level API: Extending Qt Applications + + Not only Qt itself but also Qt application can be extended + through plugins. This requires the application to detect and load + plugins using QPluginLoader. In that context, plugins may provide + arbitrary functionality and are not limited to database drivers, + image formats, text codecs, styles, and the other types of plugin + that extend Qt's functionality. + + Making an application extensible through plugins involves the + following steps: + + \list 1 + \o Define a set of interfaces (classes with only pure virtual + functions) used to talk to the plugins. + \o Use the Q_DECLARE_INTERFACE() macro to tell Qt's + \l{meta-object system} about the interface. + \o Use QPluginLoader in the application to load the plugins. + \o Use qobject_cast() to test whether a plugin implements a given + interface. + \endlist + + Writing a plugin involves these steps: + + \list 1 + \o Declare a plugin class that inherits from QObject and from the + interfaces that the plugin wants to provide. + \o Use the Q_INTERFACES() macro to tell Qt's \l{meta-object + system} about the interfaces. + \o Export the plugin using the Q_EXPORT_PLUGIN2() macro. + \o Build the plugin using a suitable \c .pro file. + \endlist + + For example, here's the definition of an interface class: + + \snippet examples/tools/plugandpaint/interfaces.h 2 + + Here's the definition of a plugin class that implements that + interface: + + \snippet examples/tools/plugandpaintplugins/extrafilters/extrafiltersplugin.h 0 + + The \l{tools/plugandpaint}{Plug & Paint} example documentation + explains this process in detail. See also \l{Creating Custom + Widgets for Qt Designer} for information about issues that are + specific to \QD. You can also take a look at the \l{Echo Plugin + Example} is a more trivial example on how to implement a plugin + that extends Qt applications. Please note that a QCoreApplication + must have been initialized before plugins can be loaded. + + \section1 Locating Plugins + + Qt applications automatically know which plugins are available, + because plugins are stored in the standard plugin subdirectories. + Because of this applications don't require any code to find and load + plugins, since Qt handles them automatically. + + During development, the directory for plugins is \c{QTDIR/plugins} + (where \c QTDIR is the directory where Qt is installed), with each + type of plugin in a subdirectory for that type, e.g. \c styles. If + you want your applications to use plugins and you don't want to use + the standard plugins path, have your installation process + determine the path you want to use for the plugins, and save the + path, e.g. using QSettings, for the application to read when it + runs. The application can then call + QCoreApplication::addLibraryPath() with this path and your + plugins will be available to the application. Note that the final + part of the path (e.g., \c styles) cannot be changed. + + If you want the plugin to be loadable then one approach is to + create a subdirectory under the application and place the plugin + in that directory. If you distribute any of the plugins that come + with Qt (the ones located in the \c plugins directory), you must + copy the sub-directory under \c plugins where the plugin is + located to your applications root folder (i.e., do not include the + \c plugins directory). + + \note In Symbian all binaries must be located in the directory \\sys\\bin, + so each Qt plugin has a stub with the same basename as the plugin dll + and suffix ".qtplugin" to make Qt extension plugins work similarly to + other platforms. + When trying to locate the plugin, Qt actually looks for the stub + instead of the plugin binary. While plugin stub files have the + suffix ".qtplugin", they can still be loaded also by specifying a filename + with the normal library suffix ".dll" for QPluginLoader, so normally application + developer doesn't need to care about the different suffix of the stub. + Because of the way applications can be installed + on ROM or various other drives in Symbian, Qt looks for the stub from + the same directory on all available drives if it is not located in the given + directory when loading a plugin. + + For more information about deployment, + see the \l {Deploying Qt Applications} and \l {Deploying Plugins} + documentation. + + \section1 Static Plugins + + The normal and most flexible way to include a plugin with an + application is to compile it into a dynamic library that is shipped + separately, and detected and loaded at runtime. + + Plugins can be linked statically against your application. If you + build the static version of Qt, this is the only option for + including Qt's predefined plugins. Using static plugins makes the + deployment less error-prone, but has the disadvantage that no + functionality from plugins can be added without a complete rebuild + and redistribution of the application. + + When compiled as a static library, Qt provides the following + static plugins: + + \table + \header \o Plugin name \o Type \o Description + \row \o \c qtaccessiblecompatwidgets \o Accessibility \o Accessibility for Qt 3 support widgets + \row \o \c qtaccessiblewidgets \o Accessibility \o Accessibility for Qt widgets + \row \o \c qdecorationdefault \o Decorations (Qt Extended) \o Default style + \row \o \c qdecorationwindows \o Decorations (Qt Extended) \o Windows style + \row \o \c qgif \o Image formats \o GIF + \row \o \c qjpeg \o Image formats \o JPEG + \row \o \c qmng \o Image formats \o MNG + \row \o \c qico \o Image formats \o ICO + \row \o \c qsvg \o Image formats \o SVG + \row \o \c qtiff \o Image formats \o TIFF + \row \o \c qimsw_multi \o Input methods (Qt Extended) \o Input Method Switcher + \row \o \c qwstslibmousehandler \o Mouse drivers (Qt Extended) \o \c tslib mouse + \row \o \c qgfxtransformed \o Graphic drivers (Qt Extended) \o Transformed screen + \row \o \c qgfxvnc \o Graphic drivers (Qt Extended) \o VNC + \row \o \c qscreenvfb \o Graphic drivers (Qt Extended) \o Virtual frame buffer + \row \o \c qsqldb2 \o SQL driver \o IBM DB2 \row \o \c qsqlibase \o SQL driver \o Borland InterBase + \row \o \c qsqlite \o SQL driver \o SQLite version 3 + \row \o \c qsqlite2 \o SQL driver \o SQLite version 2 + \row \o \c qsqlmysql \o SQL driver \o MySQL + \row \o \c qsqloci \o SQL driver \o Oracle (OCI) + \row \o \c qsqlodbc \o SQL driver \o Open Database Connectivity (ODBC) + \row \o \c qsqlpsql \o SQL driver \o PostgreSQL + \row \o \c qsqltds \o SQL driver \o Sybase Adaptive Server (TDS) + \row \o \c qcncodecs \o Text codecs \o Simplified Chinese (People's Republic of China) + \row \o \c qjpcodecs \o Text codecs \o Japanese + \row \o \c qkrcodecs \o Text codecs \o Korean + \row \o \c qtwcodecs \o Text codecs \o Traditional Chinese (Taiwan) + \endtable + + To link statically against those plugins, you need to use the + Q_IMPORT_PLUGIN() macro in your application and you need to add + the required plugins to your build using \c QTPLUGIN. + For example, in your \c main.cpp: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 4 + + In the \c .pro file for your application, you need the following + entry: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 5 + + It is also possible to create your own static plugins, by + following these steps: + + \list 1 + \o Add \c{CONFIG += static} to your plugin's \c .pro file. + \o Use the Q_IMPORT_PLUGIN() macro in your application. + \o Link your application with your plugin library using \c LIBS + in the \c .pro file. + \endlist + + See the \l{tools/plugandpaint}{Plug & Paint} example and the + associated \l{tools/plugandpaintplugins/basictools}{Basic Tools} + plugin for details on how to do this. + + \note If you are not using qmake to build your application you need + to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is + defined. + + \sa QPluginLoader, QLibrary, {Plug & Paint Example} +*/ diff --git a/doc/src/frameworks-technologies/qthelp.qdoc b/doc/src/frameworks-technologies/qthelp.qdoc new file mode 100644 index 000000000..87a909415 --- /dev/null +++ b/doc/src/frameworks-technologies/qthelp.qdoc @@ -0,0 +1,382 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group helpsystem + \title Help System + \ingroup groups + + \brief Classes used to provide online-help for applications. + + \keyword help system + + These classes provide for all forms of online-help in your application, + with three levels of detail: + + \list 1 + \o Tool Tips and Status Bar message - flyweight help, extremely brief, + entirely integrated in the user interface, requiring little + or no user interaction to invoke. + \o What's This? - lightweight, but can be + a three-paragraph explanation. + \o Online Help - can encompass any amount of information, + but is typically slower to call up, somewhat separated + from the user's work, and often users feel that using online + help is a digression from their real task. + \endlist + +*/ + +/*! + \page qthelp-framework.html + \title The Qt Help Framework + \brief Integrating Documentation in Applications + \ingroup frameworks-technologies + + \section1 Topics + + \tableofcontents + + \section1 Overview + The Qt help system includes tools for generating and viewing + Qt help files. In addition it provides classes for accessing + help contents programatically to be able to integrate online + help into Qt applications. + + The actual help data, meaning the table of contents, index + keywords or html documents, is contained in Qt compressed help + files. So, one such a help file represents usually one manual + or documentation set. Since most products are more comprehensive + and consist of a number of tools, one manual is rarely enough. + Instead, more manuals which should be accessible at the same + time, exist. Ideally, it should also be possible to reference + certain points of interest of one manual to another. + Therefore, the Qt help system operates on help collection files + which include any number of compressed help files. + + However, having collection files to merge many documentation + sets may lead to some problems. For example, one index keyword + may be defined in different documentations. So, when only seeing + it in the index and activating it, you cannot be sure that + the expected documentation will be shown. Therefore, the Qt + help system offers the possibiltiy to filter the help contents + after certain attributes. This requires however, that the + attributes have been assigned to the help contents before the + generation of the compressed help file. + + As already mentioned, the Qt compressed help file contains all + data, so there is no need any longer to ship all single html + files. Instead, only the compressed help file and optionally the + collection file has to be distributed. The collection file is + optional since any existing collection file, e.g. from an older + release could be used. + + So, in general, there are four files interacting with the help + system, two used for generating Qt help and two meant for + distribution: + + \table + \header + \o Name + \o Extension + \o Brief Description + \row + \o \l {Qt Help Project} + \o .qhp + \o The input file for the help generator consisting of the table + of contents, indices and references to the actual documentation + files (*.html); it also defines a unique namespace for the + documentation. + + \row + \o Qt Compressed Help + \o .qch + \o The output file of the help generator. This binary file contains + all information specified in the help project file along with all + compressed documentation files. + + \row + \o \l {Qt Help Collection Project} + \o .qhcp + \o The input file for the help collection generator. It contains + references to compressed help files which should be included in + the collection; it also may contain other information for + customizing Qt Assistant. + + \row + \o Qt Help Collection + \o .qhc + \o The output of the help collection generator. This is the file + QHelpEngine operates on. It contains references to any number of + compressed help files as well as additional information, such as + custom filters. + \endtable + + \section1 Generating Qt Help + + Building help files for the Qt help system assumes that the html + documentation files already exist, i.e. the Qt help system does + not offer the possibility to create html files like e.g. Doxygen. + + Once the html documentents are in place, a \l {Qt Help Project} file + has to be created. After specifying all relevant information in + this file, it needs to be compiled by calling: + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 2 + + The file 'doc.qch' contains then all html files in compressed + form along with the table of contents and index keywords. To + test if the generated file is correct, open Qt Assistant and + install the file via the Settings|Documentation page. + + \target Qt Help Collection Project + \section2 Creating a Qt Help Collection + + The first step is to create a Qt Help Collection Project file. + Since a Qt help collection stores primarily references to + compressed help files, the project 'mycollection.qhcp' file + looks unsurprisingly simple: + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 3 + + For actually creating the collection file call: + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 4 + + Instead of running two tools, one for generating the compressed + help and one for generating the collection file, it is also + possible to just run the qcollectiongenerator tool with a + slightly modified project file instructing the generator to + create the compressed help first. + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 5 + + Of course, it is possible to specify more than one file in the + 'generate' or 'register' section, so any number of compressed + help files can be generated and registered in one go. + + \section1 Using Qt Help + + Accessing the help contents can be done in two ways: Using Qt + Assistant as documentation browser or using the QHelpEngine + API for embedding the help contents directly in an application. + + \section2 Using Qt Assistant + + \QA operates on a collection file which can be specified + before start up. If no collection file is given, a default one + will be created and used. In either case, it is possible to + register any Qt compressed help file and access the help contents. + + When using Assistant as the help browser for an application, it + would be desirable that it can be customized to fit better to the + application and doesn't look like an independent, standalone + help browser. To achieve this, several additional properties can + be set in an Qt help collection file, to change e.g. the title + or application icon of Qt Assistant. For more information on + this topic have a look at the \l{assistant-manual.html} + {Qt Assistant manual}. + + \section2 Using QHelpEngine API + + Instead of showing the help in an external application like the + Qt Assistant, it is also possible to embed the online help in + the application. The contents can then be retrieved via the + QHelpEngine class and can be displayed in nearly any form. + Showing it in a QTextBrowser is probably the most common way, but + embedding it in What's This help is also perfectly possible. + + Retrieving help data from the file engine does not involve a + lot of code. The first step is to create an instance of the + help engine. Then we ask the engine for the links assigned to + the identifier, in this case "MyDialog::ChangeButton". If a link + was found, meaning at least one help document exists to this topic, + we get the actual help contents by calling fileData() and display + the document to the user. + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 6 + + For further information on how to use the API, have a look at + the QHelpEngine class reference. +*/ + +/*! + \page qthelpproject.html + \title Qt Help Project + + A Qt help project collects all data necessary to generate a + compressed help file. Along with the actual help data, like + the table of contents, index keywords and help documents, it + contains some extra information like a namespace to identify + the help file. One help project stands for one documentation, + e.g. the Qt Assistant manual. + + \section1 Qt Help Project File Format + + The file format is XML-based. For a better understanding of + the format we'll discuss the following example: + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 7 + + \section2 Namespace + + To enable the QHelpEngine to retrieve the proper documentation to + a given link, every documentation set has to have a unique + identifier. A unique identifier makes is also possible for the + help collection to keep track of a documentation set without relying + on its file name. The Qt help system uses a namespace as identifier + which is defined by the mandatory namespace tags. In the example + above, the namespace is "mycompany.com.myapplication.1_0". + + \target Virtual Folders + \section2 Virtual Folders + + Having a namespace for every documentation naturally means that + the documentation sets are quite separated. From the help engines + point of view this is beneficial, but from the documentors view + it is often desirable to cross reference certain topic from one + manual to another without having to specify absolute links. To + solve this problem, the help system introduced the concept of + virtual folders. + + A virtual folder will become the root directory of all files + referenced in a compressed help file. When two documentations + share the same virtual folder, they can use relative paths when + defining hyperlinks pointing to the other documentation. If a + file is contained in both documentations or manuals, the one + from the current manual has precedence over the other. + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 8 + + The above example specifies 'doc' as virtual folder. If another + manual, e.g. for a small helper tool for 'My Application' + specifies the same folder, it is sufficient to write + 'doc.html#section1' to reference the first section in the + 'My Application' manual. + + The virtual folder tag is mandatory and the folder must not + contain any '/'. + + \target Custom Filters + \section2 Custom Filters + + Next in the Qt help project file are the optional definitions of + custom filters. A custom filter contains a list of filter + attributes which will be used later to display only the documentation + which has all those attributes assigned to. So, when setting the + current filter in the QHelpEngine to "My Application 1.0" only + the documentation which has "myapp" and "1.0" set as filter + attributes will be shown. + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 9 + + It is possible to define any number of custom filters in a help + project file. Important to know is, that the filter attributes have + not to be specified in the same project file; they can be defined + in any other help file. The definition of a filter attributes + takes place by specifying them in a filter section. + + \target Filter Section + \section2 Filter Section + + A filter section contains the actual documentation. One Qt help project + file may contain more than one filter sections. Every filter section + consists of four parts, the filter attributes section, the table of + contents, the keywords and the files list. In theory all parts are + optional but not specifying anything there will result in an empty + documentation. + + \section3 Filter Attributes + + Every filter section should have filter attributes assigned to it, to + enable documentation filtering. If no filter attribute is defined, the + documentation will only be shown if no filtering occurs, meaning the + current custom filter in the QHelpEngine does not contain any filter + attributes. + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 10 + + In this case, the filter attributes 'myapp' and '1.0' are assigned + to the filter section, i.e. all contents specified in this section + will only be shown if the current custom filter has 'myapp' or '1.0' + or both as filter attributes. + + \section3 Table of contents + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 11 + + One section tag represents one item in the table of contents. The + sections can be nested to any degree, but from a users perspective + it should not be more than four or five levels. A section is defined + by its title and reference. The reference, like all file references in a Qt + help project, are relative to the help project file itself. + \note The referenced files must be inside the same directory (or within a + subdirectory) as the help project file. An absolute file path is not supported + either. + + \section3 Keywords + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 12 + + The keyword section lists all keywords of this filter section. A + keyword consists basically of a name and a file reference. If the + attribute 'name' is used then the keyword specified there will appear in + the visible index, i.e. it will be accessible through the QHelpIndexModel. + If 'id' is used, the keyword does not appear in the index and is + only accessible via the linksForIdentifier() function of the + QHelpEngineCore. 'name' and 'id' can be specified at the same time. + + \section3 Files + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 13 + + Finally, the actual documentation files have to be listed. Make sure + that all files neccessary to display the help are mentioned, i.e. + stylesheets or similar files need to be there as well. The files, like all + file references in a Qt help project, are relative to the help project file + itself. As the example shows, files (but not directories) can also be + specified as patterns using wildcards. All listed files will be compressed + and written to the Qt compressed help file. So, in the end, one single Qt + help file contains all documentation files along with the contents and + indices. \note The referenced files must be inside the same directory + (or within a subdirectory) as the help project file. An absolute file path + is not supported either. +*/ diff --git a/doc/src/frameworks-technologies/qundo.qdoc b/doc/src/frameworks-technologies/qundo.qdoc new file mode 100644 index 000000000..0c83e84ce --- /dev/null +++ b/doc/src/frameworks-technologies/qundo.qdoc @@ -0,0 +1,113 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qundo.html + \title Overview of Qt's Undo Framework + \keyword Undo framework + \ingroup frameworks-technologies + + \section1 Introduction + + Qt's Undo Framework is an implementation of the Command pattern, for + implementing undo/redo functionality in applications. + + The Command pattern is based on the idea that all editing in + an application is done by creating instances of command objects. + Command objects apply changes to the document and are stored + on a command stack. Furthermore, each command knows how to undo its + changes to bring the document back to its previous state. As long + as the application only uses command objects to change the state of + the document, it is possible to undo a sequence of commands by + traversing the stack downwards and calling undo + on each command in turn. It is also possible to redo a sequence of + commands by traversing the stack upwards and calling + redo on each command. + + \section1 Classes + + The framework consists of four classes: + + \list + \i \l QUndoCommand is the base class of all commands stored on an + undo stack. It can apply (redo) or undo a single change in the document. + \i \l QUndoStack is a list of QUndoCommand objects. It contains all the + commands executed on the document and can roll the document's state + backwards or forwards by undoing or redoing them. + \i \l QUndoGroup is a group of undo stacks. It is useful when an application + contains more than one undo stack, typically one for each opened + document. QUndoGroup provides a single pair of undo/redo slots for all + the stacks in the group. It forwards undo and redo requests to + the active stack, which is the stack associated with the document that + is currently being edited by the user. + \i \l QUndoView is a widget which shows the contents of an undo stack. Clicking + on a command in the view rolls the document's state backwards or + forwards to that command. + \endlist + + \section1 Concepts + + The following concepts are supported by the framework: + + \list + \i \bold{Clean state:} Used to signal when the document enters and leaves a + state that has been saved to disk. This is typically used to disable or + enable the save actions, and to update the document's title bar. + \i \bold{Command compression:} Used to compress sequences of commands into a + single command. + For example: In a text editor, the commands that insert individual + characters into the document can be compressed into a single command that + inserts whole sections of text. These bigger changes are more convenient + for the user to undo and redo. + \i \bold{Command macros:} A sequence of commands, all of which are undone or + redone in one step. + These simplify the task of writing an application, since a set of simpler + commands can be composed into more complex commands. For example, a command + that moves a set of selected objects in a document can be created by + combining a set of commands, each of which moves a single object. + \endlist + + QUndoStack provides convenient undo and redo QAction objects that + can be inserted into a menu or a toolbar. The text properties of these + actions always reflect what command will be undone or redone when + they are triggered. Similarly, QUndoGroup provides undo and redo actions + that always behave like the undo and redo actions of the active stack. +*/ diff --git a/doc/src/frameworks-technologies/richtext.qdoc b/doc/src/frameworks-technologies/richtext.qdoc new file mode 100644 index 000000000..aeaf819a2 --- /dev/null +++ b/doc/src/frameworks-technologies/richtext.qdoc @@ -0,0 +1,1226 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group richtext-processing + \title Rich Text Processing APIs +*/ + +/*! + \page richtext.html + \title Rich Text Processing + \brief An overview of Qt's rich text processing, editing and display features. + + \ingroup frameworks-technologies + + \nextpage Rich Text Document Structure + + The Scribe framework provides a set of classes for reading and manipulating + structured rich text documents. Unlike previous rich text support in Qt, the + new classes are centered around the QTextDocument class rather than raw + textual information. This enables the developer to create and modify + structured rich text documents without having to prepare content in an + intermediate markup format. + + The information within a document can be accessed via two complementary + interfaces: A cursor-based interface is used for editing, and a read-only + hierarchical interface provides a high level overview of the document + structure. The main advantage of the cursor-based interface is that the + text can be edited using operations that mimic a user's interaction with + an editor, without losing the underlying structure of the document. The + read-only hierarchical interface is most useful when performing operations + such as searching and document export. + + This document is divided up into chapters for convenient reference: + + \list + \i \l{Rich Text Document Structure} outlines + the different kinds of elements in a QTextDocument, and describes how + they are arranged in a document structure. + \i \l{The QTextCursor Interface} explains how rich + text documents can be edited using the cursor-based interface. + \i \l{Document Layouts} briefly explains the role of document layouts. + \i \l{Common Rich Text Editing Tasks} examines some + common tasks that involve reading or manipulating rich text documents. + \i \l{Advanced Rich Text Processing} examines advanced rich text editing tasks. + \i \l{Supported HTML Subset} lists the HTML tags supported by QTextDocument. + \endlist + + \section1 Rich Text Processing APIs + + Qt provides an extensive collection of classes for parsing, rendering + manipulating and editing rich text. + + \annotatedlist richtext-processing +*/ + +/*! + \page richtext-structure.html + \contentspage richtext.html Contents + \previouspage Rich Text Processing + \nextpage The QTextCursor Interface + + \title Rich Text Document Structure + + \tableofcontents + + Text documents are represented by the QTextDocument class, which + contains information about the document's internal representation, its + structure, and keeps track of modifications to provide undo/redo + facilities. + + The structured representation of a text document presents its contents as + a hierarchy of text blocks, frames, tables, and other objects. These provide + a logical structure to the document and describe how their contents will be + displayed. Generally, frames and tables are used to group other + structures while text blocks contain the actual textual information. + + New elements are created and inserted into the document programmatically + \l{richtext-cursor.html}{with a QTextCursor} or by using an editor + widget, such as QTextEdit. Elements can be given a particular format when + they are created; otherwise they take the cursor's current format for the + element. + + \table + \row + \i \inlineimage richtext-document.png + \i \bold{Basic structure} + + The "top level" of a document might be populated in the way shown. + Each document always contains a root frame, and this always contains + at least one text block. + + For documents with some textual content, the root + frame usually contains a sequence of blocks and other elements. + + Sequences of frames and tables are always separated by text blocks in a + document, even if the text blocks contain no information. This ensures that + new elements can always be inserted between existing structures. + \endtable + + In this chapter, we look at each of the structural elements + used in a rich text document, outline their features and uses, and show + how to examine their contents. Document editing is described in + \l{richtext-cursor.html}{The QTextCursor Interface}. + + \section1 Rich Text Documents + + QTextDocument objects contain all the information required to construct + rich text documents. + Text documents can be accessed in two complementary ways: as a linear + buffer for editors to use, and as an object hierarchy that is useful to + layout engines. + In the hierarchical document model, objects generally correspond to + visual elements such as frames, tables, and lists. At a lower level, + these elements describe properties such as the text style and alignment. + The linear representation of the document is used for editing and + manipulation of the document's contents. + + Although QTextEdit makes it easy to display and edit rich text, documents + can also be used independently of any editor widget, for example: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 0 + + Alternatively, they can be extracted from an existing editor: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 1 + + This flexibility enables applications to handle multiple rich text + documents without the overhead of multiple editor widgets, or requiring + documents to be stored in some intermediate format. + + An empty document contains a root frame which itself contains a single + empty text block. Frames provide logical separation between parts of the document, but + also have properties that determine how they will appear when rendered. + A table is a specialized type of frame that consists of a number of + cells, arranged into rows and columns, each of which can contain + further structure and text. Tables provide management and layout + features that allow flexible configurations of cells to be created. + + Text blocks contain text fragments, each of which specifies text and + character format information. Textual properties are defined both at + the character level and at the block level. At the character level, + properties such as font family, text color, and font weight can be + specified. The block level properties control the higher level + appearance and behavior of the text, such as the direction of text + flow, alignment, and background color. + + The document structure is not manipulated directly. Editing is + performed through a cursor-based interface. + The \l{richtext-cursor.html}{text cursor interface} + automatically inserts new document elements into the root frame, and + ensures that it is padded with empty blocks where necessary. + + We obtain the root frame in the following manner: + + \snippet doc/src/snippets/textdocument-frames/xmlwriter.h 0 + \snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 0 + + When navigating the document structure, it is useful to begin at the + root frame because it provides access to the entire document structure. + + + \section1 Document Elements + + Rich text documents usually consist of common elements such as paragraphs, + frames, tables, and lists. These are represented in a QTextDocument + by the QTextBlock, QTextFrame, QTextTable, and QTextList classes. + Unlike the other elements in a document, images are represented by + specially formatted text fragments. This enables them to be placed + formatted inline with the surrounding text. + + The basic structural building blocks in documents are QTextBlock and + QTextFrame. Blocks themselves contain fragments of rich text + (QTextFragment), but these do not directly influence the high level + structure of a document. + + Elements which can group together other document elements are typically + subclasses of QTextObject, and fall into two categories: Elements that + group together text blocks are subclasses of QTextBlockGroup, and those + that group together frames and other elements are subclasses of QTextFrame. + + \section2 Text Blocks + + Text blocks are provided by the QTextBlock class. + + Text blocks group together fragments of text with different character formats, + and are used to represent paragraphs in the document. Each block + typically contains a number of text fragments with different styles. + Fragments are created when text is inserted into the document, and more + of them are added when the document is edited. The document splits, merges, + and removes fragments to efficiently represent the different styles + of text in the block. + + The fragments within a given block can be examined by using a + QTextBlock::iterator to traverse the block's internal structure: + + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 3 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 5 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 6 + + Blocks are also used to represent list items. As a result, blocks can + define their own character formats which contain information about + block-level decoration, such as the type of bullet points used for + list items. The formatting for the block itself is described by the + QTextBlockFormat class, and describes properties such as text alignment, + indentation, and background color. + + Although a given document may contain complex structures, once we have a + reference to a valid block in the document, we can navigate between each + of the text blocks in the order in which they were written: + + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 0 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 1 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 2 + + This method is useful for when you want to extract just the rich text from a + document because it ignores frames, tables, and other types of structure. + + QTextBlock provides comparison operators that make it easier to manipulate + blocks: \l{QTextBlock::operator==()}{operator==()} and + \l{QTextBlock::operator!=()}{operator!=()} are used to test whether two + blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used + to determine which one occurs first in a document. + + \section2 Frames + + Frames are provided by the QTextFrame class. + + Text frames group together blocks of text and child frames, creating + document structures that are larger than paragraphs. The format of a frame + specifies how it is rendered and positioned on the page. Frames are + either inserted into the text flow, or they float on the left or right + hand side of the page. + Each document contains a root frame that contains all the other document + elements. As a result, all frames except the root frame have a parent + frame. + + Since text blocks are used to separate other document elements, each + frame will always contain at least one text block, and zero or more + child frames. We can inspect the contents of a frame by using a + QTextFrame::iterator to traverse the frame's child elements: + + \snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 1 + \snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 2 + + Note that the iterator selects both frames and blocks, so it is necessary + to check which it is referring to. This allows us to navigate the document + structure on a frame-by-frame basis yet still access text blocks if + required. Both the QTextBlock::iterator and QTextFrame::iterator classes + can be used in complementary ways to extract the required structure from + a document. + + \section2 Tables + + Tables are provided by the QTextTable class. + + Tables are collections of cells that are arranged in rows and columns. + Each table cell is a document element with its own character format, but it + can also contain other elements, such as frames and text blocks. Table cells + are automatically created when the table is constructed, or when extra rows + or columns are added. They can also be moved between tables. + + QTextTable is a subclass of QTextFrame, so tables are treated like frames + in the document structure. For each frame that we encounter in the + document, we can test whether it represents a table, and deal with it in a + different way: + + \snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 0 + \snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 1 + + The cells within an existing table can be examined by iterating through + the rows and columns. + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 9 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 10 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 11 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 12 + + + \section2 Lists + + Lists are provided by the QTextList class. + + Lists are sequences of text blocks that are formatted in the usual way, but + which also provide the standard list decorations such as bullet points and + enumerated items. Lists can be nested, and will be indented if the list's + format specifies a non-zero indentation. + + We can refer to each list item by its index in the list: + + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 0 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 1 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 2 + + Since QTextList is a subclass of QTextBlockGroup, it does not group the + list items as child elements, but instead provides various functions for + managing them. This means that any text block we find when traversing a + document may actually be a list item. We can ensure that list items are + correctly identified by using the following code: + + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 3 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 4 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 5 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 6 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 7 + + + \section2 Images + + Images in QTextDocument are represented by text fragments that reference + external images via the resource mechanism. Images are created using the + cursor interface, and can be modified later by changing the character + format of the image's text fragment: + + \snippet doc/src/snippets/textdocument-imageformat/main.cpp 0 + \snippet doc/src/snippets/textdocument-imageformat/main.cpp 1 + \snippet doc/src/snippets/textdocument-imageformat/main.cpp 2 + + The fragment that represents the image can be found by iterating over + the fragments in the text block that contains the image. +*/ + +/*! + \page richtext-cursor.html + \contentspage richtext.html Contents + \previouspage Rich Text Document Structure + \nextpage Document Layouts + + \title The QTextCursor Interface + + \tableofcontents + + Documents can be edited via the interface provided by the QTextCursor + class; cursors are either created using a constructor or obtained from + an editor widget. The cursor is used to perform editing operations that + correspond exactly to those the user is able to make themselves in an + editor. As a result, information about the document structure is also + available through the cursor, and this allows the structure to be + modified. The use of a cursor-oriented interface for editing makes the + process of writing a custom editor simpler for developers, since the + editing operations can be easily visualized. + + The QTextCursor class also maintains information about any text it + has selected in the document, again following a model that is + conceptually similar to the actions made by the user to select text + in an editor. + + Rich text documents can have multiple cursors + associated with them, and each of these contains information about their + position in the document and any selections that they may hold. This + cursor-based paradigm makes common operations, such as cutting and pasting + text, simple to implement programmatically, yet it also allows more complex + editing operations to be performed on the document. + + This chapter describes most of the common editing operations that you + will need to perform using a cursor, from basic insertion of text and + document elements to more complex manipulation of document structures. + + \section1 Cursor-Based Editing + + At the simplest level, text documents are made up of a string of characters, + marked up in some way to represent the block structure of the text within the + document. QTextCursor provides a cursor-based interface that allows the + contents of a QTextDocument to be manipulated at the character level. Since + the elements (blocks, frames, tables, etc.) are also encoded in the character + stream, the document structure can itself be changed by the cursor. + + The cursor keeps track of its location within its parent document, and can + report information about the surrounding structure, such as the enclosing + text block, frame, table, or list. The formats of the enclosing structures + can also be directly obtained through the cursor. + + \section2 Using a Cursor + + The main use of a cursor is to insert or modify text within a block. + We can use a text editor's cursor to do this: + + \snippet doc/src/snippets/textblock-formats/main.cpp 0 + + Alternatively, we can obtain a cursor directly from a document: + + \snippet doc/src/snippets/textdocument-images/main.cpp 0 + + The cursor is positioned at the start of the document so that we can write + into the first (empty) block in the document. + + \section2 Grouping Cursor Operations + + A series of editing operations can be packaged together so that they can + be replayed, or undone together in a single action. This is achieved by + using the \c beginEditBlock() and \c endEditBlock() functions in the + following way, as in the following example where we select the word that + contains the cursor: + + \snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 0 + + If editing operations are not grouped, the document automatically records + the individual operations so that they can be undone later. Grouping + operations into larger packages can make editing more efficient both for + the user and for the application, but care has to be taken not to group too + many operations together as the user may want find-grained control over the + undo process. + + \section2 Multiple Cursors + + Multiple cursors can be used to simultaneously edit the same document, + although only one will be visible to the user in a QTextEdit widget. + The QTextDocument ensures that each cursor writes text correctly and + does not interfere with any of the others. + + \omit + \snippet doc/src/snippets/textdocument-cursors/main.cpp 0 + \snippet doc/src/snippets/textdocument-cursors/main.cpp 1 + \endomit + + \section1 Inserting Document Elements + + QTextCursor provides several functions that can be used to change the + structure of a rich text document. Generally, these functions allow + document elements to be created with relevant formatting information, + and they are inserted into the document at the cursor's position. + + The first group of functions insert block-level elements, and update the + cursor position, but they do not return the element that was inserted: + + \list + \i \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block + (paragraph) into a document at the cursor's position, and moves the + cursor to the start of the new block. + \i \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing + text fragment into a document at the cursor's position. + \i \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a + document at the cursor's position. + \i \l{QTextCursor::insertText()}{insertText()} inserts text into the + document at the cursor's position. + \endlist + + You can examine the contents of the element that was inserted through the + cursor interface. + + The second group of functions insert elements that provide structure to + the document, and return the structure that was inserted: + + \list + \i \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the + document \e after the cursor's current block, and moves the cursor to + the start of the empty block in the new frame. + \i \l{QTextCursor::insertList()}{insertList()} inserts a list into the + document at the cursor's position, and moves the cursor to the start + of the first item in the list. + \i \l{QTextCursor::insertTable()}{insertTable()} inserts a table into + the document \e after the cursor's current block, and moves the cursor + to the start of the block following the table. + \endlist + + These elements either contain or group together other elements in the + document. + + \section2 Text and Text Fragments + + Text can be inserted into the current block in the current character + format, or in a custom format that is specified with the text: + + \snippet doc/src/snippets/textdocument-charformats/main.cpp 0 + + Once the character format has been used with a cursor, that format becomes + the default format for any text inserted with that cursor until another + character format is specified. + + If a cursor is used to insert text without specifying a character format, + the text will be given the character format used at that position in the + document. + + \section2 Blocks + + Text blocks are inserted into the document with the + \l{QTextCursor::insertBlock()}{insertBlock()} function. + + \snippet doc/src/snippets/textblock-formats/main.cpp 1 + + The cursor is positioned at the start of the new block. + + \section2 Frames + + Frames are inserted into a document using the cursor, and will be placed + within the cursor's current frame \e after the current block. + The following code shows how a frame can be inserted between two text + blocks in a document's root frame. We begin by finding the cursor's + current frame: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 0 + + We insert some text in this frame then set up a frame format for the + child frame: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 1 + + The frame format will give the frame an external margin of 32 pixels, + internal padding of 8 pixels, and a border that is 4 pixels wide. + See the QTextFrameFormat documentation for more information about + frame formats. + + The frame is inserted into the document after the preceding text: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 2 + + We add some text to the document immediately after we insert the frame. + Since the text cursor is positioned \e{inside the frame} when it is inserted + into the document, this text will also be inserted inside the frame. + + Finally, we position the cursor outside the frame by taking the last + available cursor position inside the frame we recorded earlier: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 3 + + The text that we add last is inserted after the child frame in the + document. Since each frame is padded with text blocks, this ensures that + more elements can always be inserted with a cursor. + + \section2 Tables + + Tables are inserted into the document using the cursor, and will be + placed within the cursor's current frame \e after the current block: + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 0 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 3 + + Tables can be created with a specific format that defines the overall + properties of the table, such as its alignment, background color, and + the cell spacing used. It can also determine the constraints on each + column, allowing each of them to have a fixed width, or resize according + to the available space. + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 2 + + The columns in the table created above will each take up a certain + percentage of the available width. Note that the table format is + optional; if you insert a table without a format, some sensible + default values will be used for the table's properties. + + Since cells can contain other document elements, they too can be + formatted and styled as necessary. + + Text can be added to the table by navigating to each cell with the cursor + and inserting text. + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 4 + + We can create a simple timetable by following this approach: + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 5 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 6 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 7 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 8 + + \section2 Lists + + Lists of block elements can be automatically created and inserted into the + document at the current cursor position. Each list that is created in this + way requires a list format to be specified: + + \snippet doc/src/snippets/textdocument-lists/mainwindow.cpp 0 + + The above code first checks whether the cursor is within an existing list + and, if so, gives the list format for the new list a suitable level of + indentation. This allows nested lists to be created with increasing + levels of indentation. A more sophisticated implementation would also use + different kinds of symbol for the bullet points in each level of the list. + + \section2 Images + + Inline images are added to documents through the cursor in the usual manner. + Unlike many other elements, all of the image properties are specified by the + image's format. This means that a QTextImageFormat object has to be + created before an image can be inserted: + + \snippet doc/src/snippets/textdocument-images/main.cpp 1 + + The image name refers to an entry in the application's resource file. + The method used to derive this name is described in + \l{resources.html}{The Qt Resource System}. + + \section1 Examples + + Rich text is stored in text documents that can either be created by + importing HTML from an external source, or generated using a QTextCursor. + + \section2 Manipulating Rich Text + + The easiest way to use a rich text document is through + the QTextEdit class, providing an editable view onto a document. The code + below imports HTML into a document, and displays the document using a + text edit widget. + + \snippet doc/src/snippets/scribe-overview/main.cpp 1 + + You can retrieve the document from the text edit using the + document() function. The document can then be edited programmatically + using the QTextCursor class. This class is modeled after a screen + cursor, and editing operations follow the same semantics. The following + code changes the first line of the document to a bold font, leaving all + other font properties untouched. The editor will be automatically + updated to reflect the changes made to the underlying document data. + + \snippet doc/src/snippets/scribe-overview/main.cpp 0 + + Note that the cursor was moved from the start of the first line to the + end, but that it retained an anchor at the start of the line. This + demonstrates the cursor-based selection facilities of the + QTextCursor class. + + \section2 Generating a Calendar + + Rich text can be generated very quickly using the cursor-based + approach. The following example shows a simple calendar in a + QTextEdit widget with bold headers for the days of the week: + + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 0 + \codeline + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 1 + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 2 + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 3 + + The above example demonstrates how simple it is to quickly generate new + rich text documents using a minimum amount of code. Although we have + generated a crude fixed-pitch calendar to avoid quoting too much code, + Scribe provides much more sophisticated layout and formatting features. +*/ + +/*! + \page richtext-layouts.html + \contentspage richtext.html Contents + \previouspage The QTextCursor Interface + \nextpage Common Rich Text Editing Tasks + + \title Document Layouts + + \tableofcontents + + The layout of a document is only relevant when it is to be displayed on + a device, or when some information is requested that requires a visual + representation of the document. Until this occurs, the document does + not need to be formatted and prepared for a device. + + \section1 Overview + + Each document's layout is managed by a subclass of the + QAbstractTextDocumentLayout class. This class provides a common + interface for layout and rendering engines. The default rendering + behavior is currently implemented in a private class. This approach + makes it possible to create custom layouts, and provides the + mechanism used when preparing pages for printing or exporting to + Portable Document Format (PDF) files. + + \section1 Example - Shaped Text Layout + + Sometimes it is important to be able to format plain text within an + irregularly-shaped region, perhaps when rendering a custom widget, for + example. Scribe provides generic features, such as those provided by + the QTextLayout class, to help developers perform word-wrapping and + layout tasks without the need to create a document first. + + \img plaintext-layout.png + + Formatting and drawing a paragraph of plain text is straightforward. + The example below will lay out a paragraph of text, using a single + font, around the right hand edge of a circle. + + \snippet doc/src/snippets/plaintextlayout/window.cpp 0 + + We create a text layout, specifying the text string we want to display + and the font to use. We ensure that the text we supplied is formatted + correctly by obtaining text lines from the text format, and wrapping + the remaining text using the available space. The lines are positioned + as we move down the page. + + The formatted text can be drawn onto a paint device; in the above code, + the text is drawn directly onto a widget. + */ + + /*! + \page richtext-common-tasks.html + \contentspage richtext.html Contents + \previouspage Document Layouts + \nextpage Advanced Rich Text Processing + + \title Common Rich Text Editing Tasks + + \tableofcontents + + There are a number of tasks that are often performed by developers + when editing and processing text documents using Qt. These include the use + of display widgets such as QTextBrowser and QTextEdit, creation of + documents with QTextDocument, editing using a QTextCursor, and + exporting the document structure. + This document outlines some of the more common ways of using the rich + text classes to perform these tasks, showing convenient patterns that can + be reused in your own applications. + + \section1 Using QTextEdit + + A text editor widget can be constructed and used to display HTML in the + following way: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 2 + + By default, the text editor contains a document with a root frame, inside + which is an empty text block. This document can be obtained so that it can + be modified directly by the application: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 3 + + The text editor's cursor may also be used to edit a document: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 4 + + Although a document can be edited using many cursors at once, a QTextEdit + only displays a single cursor at a time. Therefore, if we want to update the + editor to display a particular cursor or its selection, we need to set the + editor's cursor after we have modified the document: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 5 + + \section1 Selecting Text + + Text is selected by moving the cursor using operations that are similar to + those performed by a user in a text editor. To select text between two + points in the document, we need to position the cursor at the first point + then move it using a special mode (\l{QTextCursor::MoveMode}) with a + move operation (\l{QTextCursor::MoveOperation}). + When we select the text, we leave the selection anchor at the old cursor + position just as the user might do by holding down the Shift key when + selecting text: + + \snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 1 + + In the above code, a whole word is selected using this method. QTextCursor + provides a number of common move operations for selecting individual + characters, words, lines, and whole blocks. + + \section1 Finding Text + + QTextDocument provides a cursor-based interface for searching, making + it easy to find and modify text in the style of a text editor. The following + code finds all the instances of a particular word in a document, and changes + the color of each: + + \snippet doc/src/snippets/textdocument-find/main.cpp 0 + \snippet doc/src/snippets/textdocument-find/main.cpp 1 + + Note that the cursor does not have to be moved after each search and replace + operation; it is always positioned at the end of the word that was just + replaced. + + \section1 Printing Documents + + QTextEdit is designed for the display of large rich text documents that are + read on screen, rendering them in the same way as a web browser. As a result, + it does not automatically break the contents of the document into page-sized + pieces that are suitable for printing. + + QTextDocument provides a \l{QTextDocument::print()}{print()} function to + allow documents to be printed using the QPrinter class. The following code + shows how to prepare a document in a QTextEdit for printing with a QPrinter: + + \snippet doc/src/snippets/textdocument-printing/mainwindow.cpp 0 + + The document is obtained from the text editor, and a QPrinter is constructed + then configured using a QPrintDialog. If the user accepts the printer's + configuration then the document is formatted and printed using the + \l{QTextDocument::print()}{print()} function. +*/ + +/*! + \page richtext-advanced-processing.html + \contentspage richtext.html Contents + \previouspage Common Rich Text Editing Tasks + \nextpage Supported HTML Subset + + \title Advanced Rich Text Processing + + \section1 Handling Large Files + + Qt does not limit the size of files that are used for text + processing. In most cases, this will not present a problem. For + especially large files, however, you might experience that your + application will become unresponsive or that you will run out of + memory. The size of the files you can load depends on your + hardware and on Qt's and your own application's implementation. + + If you are faced with this problem, we recommend that you address the + following issues: + + \list + \o You should consider breaking up large paragraphs into smaller + ones as Qt handles small paragraphs better. You could also + insert line breaks at regular intervals, which will look the + same as one large paragraph in a QTextEdit. + \o You can reduce the amount of blocks in a QTextDocument with + \l{QTextDocument::}{maximumBlockCount()}. The document is only + as large as the number of blocks as far as QTextEdit is concerned. + \o When adding text to a text edit, it is an advantage to add it + in an edit block (see example below). The result is that the + text edit does not need to build the entire document structure at once. + \endlist + + We give an example of the latter technique from the list. We assume that + the text edit is visible. + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 6 + + \omit + Ideas for other sections: + + * Hiding QTextBlock elements. + * Changing the word wrapping mode in QTextEdit. Custom word wrapping? + \endomit +*/ + +/*! + \page richtext-html-subset.html + \title Supported HTML Subset + \brief Describes the support for HTML markup in text widgets. + + \contentspage richtext.html Contents + \previouspage Common Rich Text Editing Tasks + + Qt's text widgets are able to display rich text, specified using a subset of \l{HTML 4} + markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display + rich text specified in this way. + + \tableofcontents + + \section1 Using HTML Markup in Text Widgets + + Widgets automatically detect HTML markup and display rich text accordingly. For example, + setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"} + will result in the label displaying text like this: \bold{Hello} \e{Qt!} + + When HTML markup is used for text, Qt follows the rules defined by the \l{HTML 4} + specification. This includes default properties for text layout, such as the + direction of the text flow (left-to-right) which can be changed by applying the + \l{#Block Attributes}{\c dir} attribute to blocks of text. + + \section1 Supported Tags + + The following table lists the HTML tags supported by Qt's + \l{Rich Text Processing}{rich text} engine: + + \table + \header \o Tag + \o Description + \o Comment + \row \o \c a + \o Anchor or link + \o Supports the \c href and \c name attributes. + \row \o \c address + \o Address + \o + \row \o \c b + \o Bold + \o + \row \o \c big + \o Larger font + \o + \row \o \c blockquote + \o Indented paragraph + \o + \row \o \c body + \o Document body + \o Supports the \c bgcolor attribute, which + can be a Qt \l{QColor::setNamedColor()}{color name} + or a \c #RRGGBB color specification. + \row \o \c br + \o Line break + \o + \row \o \c center + \o Centered paragraph + \o + \row \o \c cite + \o Inline citation + \o Same as \c i. + \row \o \c code + \o Code + \o Same as \c tt. + \row \o \c dd + \o Definition data + \o + \row \o \c dfn + \o Definition + \o Same as \c i. + \row \o \c div + \o Document division + \o Supports the standard \l{block attributes}. + \row \o \c dl + \o Definition list + \o Supports the standard \l{block attributes}. + \row \o \c dt + \o Definition term + \o Supports the standard \l{block attributes}. + \row \o \c em + \o Emphasized + \o Same as \c i. + \row \o \c font + \o Font size, family, and/or color + \o Supports the following attributes: + \c size, \c face, and \c color (Qt + \l{QColor::setNamedColor()}{color names} or + \c #RRGGBB). + \row \o \c h1 + \o Level 1 heading + \o Supports the standard \l{block attributes}. + \row \o \c h2 + \o Level 2 heading + \o Supports the standard \l{block attributes}. + \row \o \c h3 + \o Level 3 heading + \o Supports the standard \l{block attributes}. + \row \o \c h4 + \o Level 4 heading + \o Supports the standard \l{block attributes}. + \row \o \c h5 + \o Level 5 heading + \o Supports the standard \l{block attributes}. + \row \o \c h6 + \o Level 6 heading + \o Supports the standard \l{block attributes}. + \row \o \c head + \o Document header + \o + \row \o \c hr + \o Horizontal line + \o Supports the \c width attribute, which can + be specified as an absolute or relative (\c %) value. + \row \o \c html + \o HTML document + \o + \row \o \c i + \o Italic + \o + \row \o \c img + \o Image + \o Supports the \c src, \c source + (for Qt 3 compatibility), \c width, and \c height + attributes. + \row \o \c kbd + \o User-entered text + \o + \row \o \c meta + \o Meta-information + \o If a text encoding is specified using the \c{meta} tag, + it is picked up by Qt::codecForHtml(). + Likewise, if an encoding is specified to + QTextDocument::toHtml(), the encoding is stored using + a \c meta tag, for example: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 7 + + \row \o \c li + \o List item + \o + \row \o \c nobr + \o Non-breakable text + \o + \row \o \c ol + \o Ordered list + \o Supports the standard \l{list attributes}. + \row \o \c p + \o Paragraph + \o Left-aligned by default. Supports the standard + \l{block attributes}. + \row \o \c pre + \o Preformated text + \o + \row \o \c qt + \o Qt rich-text document + \o Synonym for \c html. Provided for compatibility with + earlier versions of Qt. + \row \o \c s + \o Strikethrough + \o + \row \o \c samp + \o Sample code + \o Same as \c tt. + \row \o \c small + \o Small font + \o + \row \o \c span + \o Grouped elements + \o + \row \o \c strong + \o Strong + \o Same as \c b. + \row \o \c sub + \o Subscript + \o + \row \o \c sup + \o Superscript + \o + \row \o \c table + \o Table + \o Supports the following attributes: \c border, + \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} + or \c #RRGGBB), \c cellspacing, \c cellpadding, + \c width (absolute or relative), and \c height. + \row \o \c tbody + \o Table body + \o Does nothing. + \row \o \c td + \o Table data cell + \o Supports the standard \l{table cell attributes}. + \row \o \c tfoot + \o Table footer + \o Does nothing. + \row \o \c th + \o Table header cell + \o Supports the standard \l{table cell attributes}. + \row \o \c thead + \o Table header + \o If the \c thead tag is specified, it is used when printing tables + that span multiple pages. + \row \o \c title + \o Document title + \o The value specified using the \c + title tag is available through + QTextDocument::metaInformation(). + \row \o \c tr + \o Table row + \o Supports the \c bgcolor attribute, which + can be a Qt \l{QColor::setNamedColor()}{color name} + or a \c #RRGGBB color specification. + \row \o \c tt + \o Typewrite font + \o + \row \o \c u + \o Underlined + \o + \row \o \c ul + \o Unordered list + \o Supports the standard \l{list attributes}. + \row \o \c var + \o Variable + \o Same as \c i. + \endtable + + \section1 Block Attributes + + The following attributes are supported by the \c div, \c dl, \c + dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags: + + \list + \o \c align (\c left, \c right, \c center, \c justify) + \o \c dir (\c ltr, \c rtl) + \endlist + + \section1 List Attributes + + The following attribute is supported by the \c ol and \c ul tags: + + \list + \o \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle) + \endlist + + \section1 Table Cell Attributes + + The following attributes are supported by the \c td and \c th + tags: + + \list + \o \c width (absolute, relative, or no-value) + \o \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} or \c #RRGGBB) + \o \c colspan + \o \c rowspan + \o \c align (\c left, \c right, \c center, \c justify) + \o \c valign (\c top, \c middle, \c bottom) + \endlist + + \section1 CSS Properties + The following table lists the CSS properties supported by Qt's + \l{Rich Text Processing}{rich text} engine: + + \table + \header \o Property + \o Values + \o Description + \row + \o \c background-color + \o <color> + \o Background color for elements + \row + \o \c background-image + \o <uri> + \o Background image for elements + \row \o \c color + \o <color> + \o Text foreground color + \row \o \c font-family + \o <family name> + \o Font family name + \row \o \c font-size + \o [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px + \o Font size relative to the document font, or specified in points or pixels + \row \o \c font-style + \o [ normal | italic | oblique ] + \o + \row \o \c font-weight + \o [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ] + \o Specifies the font weight used for text, where \c normal and \c bold + are mapped to the corresponding QFont weights. Numeric values are + 8 times the equivalent QFont weight values. + \row \o \c text-decoration + \o none | [ underline || overline || line-through ] + \o Additional text effects + \row \o \c font + \o [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ] + \o Font shorthand property + \row \o \c text-indent + \o <length>px + \o First line text indentation in pixels + \row \o \c white-space + \o normal | pre | nowrap | pre-wrap + \o Declares how whitespace in HTML is handled. + \row \o \c margin-top + \o <length>px + \o Top paragraph margin in pixels + \row \o \c margin-bottom + \o <length>px + \o Bottom paragraph margin in pixels + \row \o \c margin-left + \o <length>px + \o Left paragraph margin in pixels + \row \o \c margin-right + \o <length>px + \o Right paragraph margin in pixels + \row \o \c padding-top + \o <length>px + \o Top table cell padding in pixels + \row \o \c padding-bottom + \o <length>px + \o Bottom table cell padding in pixels + \row \o \c padding-left + \o <length>px + \o Left table cell padding in pixels + \row \o \c padding-right + \o <length>px + \o Right table cell padding in pixels + \row \o \c padding + \o <length>px + \o Shorthand for setting all the padding properties at once. + \row \o \c vertical-align + \o baseline | sub | super | middle | top | bottom + \o Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply. + \row \o \c border-color + \o <color> + \o Border color for text tables. + \row \o \c border-style + \o none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset + \o Border style for text tables. + \row \o \c background + \o [ <'background-color'> || <'background-image'> ] + \o Background shorthand property + \row \o \c page-break-before + \o [ auto | always ] + \o Make it possible to enforce a page break before the paragraph/table + \row \o \c page-break-after + \o [ auto | always ] + \o Make it possible to enforce a page break after the paragraph/table + \row \o float + \o [ left | right | none ] + \o Specifies where an image or a text will be placed in another element. Note that the \c float property is + only supported for tables and images. + \row \o \c text-transform + \o [ uppercase | lowercase ] + \o Select the transformation that will be performed on the text prior to displaying it. + \row \o \c font-variant + \o small-caps + \o Perform the smallcaps transformation on the text prior to displaying it. + \row \o \c word-spacing + \o <width>px + \o Specifies an alternate spacing between each word. + \endtable + + \section1 Supported CSS Selectors + + All CSS 2.1 selector classes are supported except pseudo-class selectors such + as \c{:first-child}, \c{:visited} and \c{:hover}. + +*/ diff --git a/doc/src/frameworks-technologies/statemachine.qdoc b/doc/src/frameworks-technologies/statemachine.qdoc new file mode 100644 index 000000000..b0b13a7fd --- /dev/null +++ b/doc/src/frameworks-technologies/statemachine.qdoc @@ -0,0 +1,566 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group statemachine + \title State Machine Classes +*/ + +/*! + \page statemachine-api.html + \title The State Machine Framework + \brief An overview of the State Machine framework for constructing and executing state graphs. + + \ingroup frameworks-technologies + + \tableofcontents + + The State Machine framework provides classes for creating and executing + state graphs. The concepts and notation are based on those from Harel's + \l{Statecharts: A visual formalism for complex systems}{Statecharts}, which + is also the basis of UML state diagrams. The semantics of state machine + execution are based on \l{State Chart XML: State Machine Notation for + Control Abstraction}{State Chart XML (SCXML)}. + + Statecharts provide a graphical way of modeling how a system reacts to + stimuli. This is done by defining the possible \e states that the system can + be in, and how the system can move from one state to another (\e transitions + between states). A key characteristic of event-driven systems (such as Qt + applications) is that behavior often depends not only on the last or current + event, but also the events that preceded it. With statecharts, this + information is easy to express. + + The State Machine framework provides an API and execution model that can be + used to effectively embed the elements and semantics of statecharts in Qt + applications. The framework integrates tightly with Qt's meta-object system; + for example, transitions between states can be triggered by signals, and + states can be configured to set properties and invoke methods on QObjects. + Qt's event system is used to drive the state machines. + + The state graph in the State Machine framework is hierarchical. States can be nested inside of + other states, and the current configuration of the state machine consists of the set of states + which are currently active. All the states in a valid configuration of the state machine will + have a common ancestor. + + \section1 Classes in the State Machine Framework + + These classes are provided by qt for creating event-driven state machines. + + \annotatedlist statemachine + + \section1 A Simple State Machine + + To demonstrate the core functionality of the State Machine API, let's look + at a small example: A state machine with three states, \c s1, \c s2 and \c + s3. The state machine is controlled by a single QPushButton; when the button + is clicked, the machine transitions to another state. Initially, the state + machine is in state \c s1. The statechart for this machine is as follows: + + \img statemachine-button.png + \omit + \caption This is a caption + \endomit + + The following snippet shows the code needed to create such a state machine. + First, we create the state machine and states: + + \snippet doc/src/snippets/statemachine/main.cpp 0 + + Then, we create the transitions by using the QState::addTransition() + function: + + \snippet doc/src/snippets/statemachine/main.cpp 1 + + Next, we add the states to the machine and set the machine's initial state: + + \snippet doc/src/snippets/statemachine/main.cpp 2 + + Finally, we start the state machine: + + \snippet doc/src/snippets/statemachine/main.cpp 3 + + The state machine executes asynchronously, i.e. it becomes part of your + application's event loop. + + \section1 Doing Useful Work on State Entry and Exit + + The above state machine merely transitions from one state to another, it + doesn't perform any operations. The QState::assignProperty() function can be + used to have a state set a property of a QObject when the state is + entered. In the following snippet, the value that should be assigned to a + QLabel's text property is specified for each state: + + \snippet doc/src/snippets/statemachine/main.cpp 4 + + When any of the states is entered, the label's text will be changed + accordingly. + + The QState::entered() signal is emitted when the state is entered, and the + QState::exited() signal is emitted when the state is exited. In the + following snippet, the button's showMaximized() slot will be called when + state \c s3 is entered, and the button's showMinimized() slot will be called + when \c s3 is exited: + + \snippet doc/src/snippets/statemachine/main.cpp 5 + + Custom states can reimplement QAbstractState::onEntry() and + QAbstractState::onExit(). + + \section1 State Machines That Finish + + The state machine defined in the previous section never finishes. In order + for a state machine to be able to finish, it needs to have a top-level \e + final state (QFinalState object). When the state machine enters a top-level + final state, the machine will emit the QStateMachine::finished() signal and + halt. + + All you need to do to introduce a final state in the graph is create a + QFinalState object and use it as the target of one or more transitions. + + \section1 Sharing Transitions By Grouping States + + Assume we wanted the user to be able to quit the application at any time by + clicking a Quit button. In order to achieve this, we need to create a final + state and make it the target of a transition associated with the Quit + button's clicked() signal. We could add a transition from each of \c s1, \c + s2 and \c s3; however, this seems redundant, and one would also have to + remember to add such a transition from every new state that is added in the + future. + + We can achieve the same behavior (namely that clicking the Quit button quits + the state machine, regardless of which state the state machine is in) by + grouping states \c s1, \c s2 and \c s3. This is done by creating a new + top-level state and making the three original states children of the new + state. The following diagram shows the new state machine. + + \img statemachine-button-nested.png + \omit + \caption This is a caption + \endomit + + The three original states have been renamed \c s11, \c s12 and \c s13 to + reflect that they are now children of the new top-level state, \c s1. Child + states implicitly inherit the transitions of their parent state. This means + it is now sufficient to add a single transition from \c s1 to the final + state \c s2. New states added to \c s1 will also automatically inherit this + transition. + + All that's needed to group states is to specify the proper parent when the + state is created. You also need to specify which of the child states is the + initial one (i.e. which child state the state machine should enter when the + parent state is the target of a transition). + + \snippet doc/src/snippets/statemachine/main2.cpp 0 + + \snippet doc/src/snippets/statemachine/main2.cpp 1 + + In this case we want the application to quit when the state machine is + finished, so the machine's finished() signal is connected to the + application's quit() slot. + + A child state can override an inherited transition. For example, the + following code adds a transition that effectively causes the Quit button to + be ignored when the state machine is in state \c s12. + + \snippet doc/src/snippets/statemachine/main2.cpp 2 + + A transition can have any state as its target, i.e. the target state does + not have to be on the same level in the state hierarchy as the source state. + + \section1 Using History States to Save and Restore the Current State + + Imagine that we wanted to add an "interrupt" mechanism to the example + discussed in the previous section; the user should be able to click a button + to have the state machine perform some non-related task, after which the + state machine should resume whatever it was doing before (i.e. return to the + old state, which is one of \c s11, \c s12 and \c s13 in this case). + + Such behavior can easily be modeled using \e{history states}. A history + state (QHistoryState object) is a pseudo-state that represents the child + state that the parent state was in the last time the parent state was + exited. + + A history state is created as a child of the state for which we wish to + record the current child state; when the state machine detects the presence + of such a state at runtime, it automatically records the current (real) + child state when the parent state is exited. A transition to the history + state is in fact a transition to the child state that the state machine had + previously saved; the state machine automatically "forwards" the transition + to the real child state. + + The following diagram shows the state machine after the interrupt mechanism + has been added. + + \img statemachine-button-history.png + \omit + \caption This is a caption + \endomit + + The following code shows how it can be implemented; in this example we + simply display a message box when \c s3 is entered, then immediately return + to the previous child state of \c s1 via the history state. + + \snippet doc/src/snippets/statemachine/main2.cpp 3 + + \section1 Using Parallel States to Avoid a Combinatorial Explosion of States + + Assume that you wanted to model a set of mutually exclusive properties of a + car in a single state machine. Let's say the properties we are interested in + are Clean vs Dirty, and Moving vs Not moving. It would take four mutually + exclusive states and eight transitions to be able to represent and freely + move between all possible combinations. + + \img statemachine-nonparallel.png + \omit + \caption This is a caption + \endomit + + If we added a third property (say, Red vs Blue), the total number of states + would double, to eight; and if we added a fourth property (say, Enclosed vs + Convertible), the total number of states would double again, to 16. + + Using parallel states, the total number of states and transitions grows + linearly as we add more properties, instead of exponentially. Furthermore, + states can be added to or removed from the parallel state without affecting + any of their sibling states. + + \img statemachine-parallel.png + \omit + \caption This is a caption + \endomit + + To create a parallel state group, pass QState::ParallelStates to the QState + constructor. + + \snippet doc/src/snippets/statemachine/main3.cpp 0 + + When a parallel state group is entered, all its child states will be + simultaneously entered. Transitions within the individual child states + operate normally. However, any of the child states may take a transition which exits the parent + state. When this happens, the parent state and all of its child states are exited. + + The parallelism in the State Machine framework follows an interleaved semantics. All parallel + operations will be executed in a single, atomic step of the event processing, so no event can + interrupt the parallel operations. However, events will still be processed sequentially, since + the machine itself is single threaded. As an example: Consider the situation where there are two + transitions that exit the same parallel state group, and their conditions become true + simultaneously. In this case, the event that is processed last of the two will not have any + effect, since the first event will already have caused the machine to exit from the parallel + state. + + \section1 Detecting that a Composite State has Finished + + A child state can be final (a QFinalState object); when a final child state + is entered, the parent state emits the QState::finished() signal. The + following diagram shows a composite state \c s1 which does some processing + before entering a final state: + + \img statemachine-finished.png + \omit + \caption This is a caption + \endomit + + When \c s1 's final state is entered, \c s1 will automatically emit + finished(). We use a signal transition to cause this event to trigger a + state change: + + \snippet doc/src/snippets/statemachine/main3.cpp 1 + + Using final states in composite states is useful when you want to hide the + internal details of a composite state; i.e. the only thing the outside world + should be able to do is enter the state, and get a notification when the + state has completed its work. This is a very powerful abstraction and + encapsulation mechanism when building complex (deeply nested) state + machines. (In the above example, you could of course create a transition + directly from \c s1 's \c done state rather than relying on \c s1 's + finished() signal, but with the consequence that implementation details of + \c s1 are exposed and depended on). + + For parallel state groups, the QState::finished() signal is emitted when \e + all the child states have entered final states. + + \section1 Targetless Transitions + + A transition need not have a target state. A transition without a target can + be triggered the same way as any other transition; the difference is that + when a targetless transition is triggered, it doesn't cause any state + changes. This allows you to react to a signal or event when your machine is + in a certain state, without having to leave that state. Example: + + \code + QStateMachine machine; + QState *s1 = new QState(&machine); + + QPushButton button; + QSignalTransition *trans = new QSignalTransition(&button, SIGNAL(clicked())); + s1->addTransition(trans); + + QMessageBox msgBox; + msgBox.setText("The button was clicked; carry on."); + QObject::connect(trans, SIGNAL(triggered()), &msgBox, SLOT(exec())); + + machine.setInitialState(s1); + \endcode + + The message box will be displayed each time the button is clicked, but the + state machine will remain in its current state (s1). If the target state + were explicitly set to s1, however, s1 would be exited and re-entered each + time (e.g. the QAbstractState::entered() and QAbstractState::exited() + signals would be emitted). + + \section1 Events, Transitions and Guards + + A QStateMachine runs its own event loop. For signal transitions + (QSignalTransition objects), QStateMachine automatically posts a + QStateMachine::SignalEvent to itself when it intercepts the corresponding + signal; similarly, for QObject event transitions (QEventTransition objects) + a QStateMachine::WrappedEvent is posted. + + You can post your own events to the state machine using + QStateMachine::postEvent(). + + When posting a custom event to the state machine, you typically also have + one or more custom transitions that can be triggered from events of that + type. To create such a transition, you subclass QAbstractTransition and + reimplement QAbstractTransition::eventTest(), where you check if an event + matches your event type (and optionally other criteria, e.g. attributes of + the event object). + + Here we define our own custom event type, \c StringEvent, for posting + strings to the state machine: + + \snippet doc/src/snippets/statemachine/main4.cpp 0 + + Next, we define a transition that only triggers when the event's string + matches a particular string (a \e guarded transition): + + \snippet doc/src/snippets/statemachine/main4.cpp 1 + + In the eventTest() reimplementation, we first check if the event type is the + desired one; if so, we cast the event to a StringEvent and perform the + string comparison. + + The following is a statechart that uses the custom event and transition: + + \img statemachine-customevents.png + \omit + \caption This is a caption + \endomit + + Here's what the implementation of the statechart looks like: + + \snippet doc/src/snippets/statemachine/main4.cpp 2 + + Once the machine is started, we can post events to it. + + \snippet doc/src/snippets/statemachine/main4.cpp 3 + + An event that is not handled by any relevant transition will be silently + consumed by the state machine. It can be useful to group states and provide + a default handling of such events; for example, as illustrated in the + following statechart: + + \img statemachine-customevents2.png + \omit + \caption This is a caption + \endomit + + For deeply nested statecharts, you can add such "fallback" transitions at + the level of granularity that's most appropriate. + + \section1 Using Restore Policy To Automatically Restore Properties + + In some state machines it can be useful to focus the attention on assigning properties in states, + not on restoring them when the state is no longer active. If you know that a property should + always be restored to its initial value when the machine enters a state that does not explicitly + give the property a value, you can set the global restore policy to + QStateMachine::RestoreProperties. + + \code + QStateMachine machine; + machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); + \endcode + + When this restore policy is set, the machine will automatically restore all properties. If it + enters a state where a given property is not set, it will first search the hierarchy of ancestors + to see if the property is defined there. If it is, the property will be restored to the value + defined by the closest ancestor. If not, it will be restored to its initial value (i.e. the + value of the property before any property assignments in states were executed.) + + Take the following code: + + \snippet doc/src/snippets/statemachine/main5.cpp 0 + + Lets say the property \c fooBar is 0.0 when the machine starts. When the machine is in state + \c s1, the property will be 1.0, since the state explicitly assigns this value to it. When the + machine is in state \c s2, no value is explicitly defined for the property, so it will implicitly + be restored to 0.0. + + If we are using nested states, the parent defines a value for the property which is inherited by + all descendants that do not explicitly assign a value to the property. + + \snippet doc/src/snippets/statemachine/main5.cpp 2 + + Here \c s1 has two children: \c s2 and \c s3. When \c s2 is entered, the property \c fooBar + will have the value 2.0, since this is explicitly defined for the state. When the machine is in + state \c s3, no value is defined for the state, but \c s1 defines the property to be 1.0, so this + is the value that will be assigned to \c fooBar. + + \section1 Animating Property Assignments + + The State Machine API connects with the Animation API in Qt to allow automatically animating + properties as they are assigned in states. + + Say we have the following code: + + \snippet doc/src/snippets/statemachine/main5.cpp 3 + + Here we define two states of a user interface. In \c s1 the \c button is small, and in \c s2 + it is bigger. If we click the button to transition from \c s1 to \c s2, the geometry of the button + will be set immediately when a given state has been entered. If we want the transition to be + smooth, however, all we need to do is make a QPropertyAnimation and add this to the transition + object. + + \snippet doc/src/snippets/statemachine/main5.cpp 4 + + Adding an animation for the property in question means that the property assignment will no + longer take immediate effect when the state has been entered. Instead, the animation will start + playing when the state has been entered and smoothly animate the property assignment. Since we + do not set the start value or end value of the animation, these will be set implicitly. The + start value of the animation will be the property's current value when the animation starts, and + the end value will be set based on the property assignments defined for the state. + + If the global restore policy of the state machine is set to QStateMachine::RestoreProperties, + it is possible to also add animations for the property restorations. + + \section1 Detecting That All Properties Have Been Set In A State + + When animations are used to assign properties, a state no longer defines the exact values that a + property will have when the machine is in the given state. While the animation is running, the + property can potentially have any value, depending on the animation. + + In some cases, it can be useful to be able to detect when the property has actually been assigned + the value defined by a state. + + Say we have the following code: + + \snippet doc/src/snippets/statemachine/main5.cpp 5 + + When \c button is clicked, the machine will transition into state \c s2, which will set the + geometry of the button, and then pop up a message box to alert the user that the geometry has + been changed. + + In the normal case, where animations are not used, this will operate as expected. However, if + an animation for the \c geometry of \c button is set on the transition between \c s1 and \c s2, + the animation will be started when \c s2 is entered, but the \c geometry property will not + actually reach its defined value before the animation is finished running. In this case, the + message box will pop up before the geometry of the button has actually been set. + + To ensure that the message box does not pop up until the geometry actually reaches its final + value, we can use the state's propertiesAssigned() signal. The propertiesAssigned() signal will be + emitted when the property is assigned its final value, whether this is done immediately or + after the animation has finished playing. + + \snippet doc/src/snippets/statemachine/main5.cpp 6 + + In this example, when \c button is clicked, the machine will enter \c s2. It will remain in state + \c s2 until the \c geometry property has been set to \c QRect(0, 0, 50, 50). Then it will + transition into \c s3. When \c s3 is entered, the message box will pop up. If the transition into + \c s2 has an animation for the \c geometry property, then the machine will stay in \c s2 until the + animation has finished playing. If there is no such animation, it will simply set the property and + immediately enter state \c s3. + + Either way, when the machine is in state \c s3, you are guaranteed that the property \c geometry + has been assigned the defined value. + + If the global restore policy is set to QStateMachine::RestoreProperties, the state will not emit + the propertiesAssigned() signal until these have been executed as well. + + \section1 What Happens If A State Is Exited Before The Animation Has Finished + + If a state has property assignments, and the transition into the state has animations for the + properties, the state can potentially be exited before the properties have been assigned to the + values defines by the state. This is true in particular when there are transitions out from the + state that do not depend on the propertiesAssigned signal, as described in the previous section. + + The State Machine API guarantees that a property assigned by the state machine either: + \list + \o Has a value explicitly assigned to the property. + \o Is currently being animated into a value explicitly assigned to the property. + \endlist + + When a state is exited prior to the animation finishing, the behavior of the state machine depends + on the target state of the transition. If the target state explicitly assigns a value to the + property, no additional action will be taken. The property will be assigned the value defined by + the target state. + + If the target state does not assign any value to the property, there are two + options: By default, the property will be assigned the value defined by the state it is leaving + (the value it would have been assigned if the animation had been permitted to finish playing). If + a global restore policy is set, however, this will take precedence, and the property will be + restored as usual. + + \section1 Default Animations + + As described earlier, you can add animations to transitions to make sure property assignments + in the target state are animated. If you want a specific animation to be used for a given property + regardless of which transition is taken, you can add it as a default animation to the state + machine. This is in particular useful when the properties assigned (or restored) by specific + states is not known when the machine is constructed. + + \code + QState *s1 = new QState(); + QState *s2 = new QState(); + + s2->assignProperty(object, "fooBar", 2.0); + s1->addTransition(s2); + + QStateMachine machine; + machine.setInitialState(s1); + machine.addDefaultAnimation(new QPropertyAnimation(object, "fooBar")); + \endcode + + When the machine is in state \c s2, the machine will play the default animation for the + property \c fooBar since this property is assigned by \c s2. + + Note that animations explicitly set on transitions will take precedence over any default + animation for the given property. +*/ diff --git a/doc/src/frameworks-technologies/templates.qdoc b/doc/src/frameworks-technologies/templates.qdoc new file mode 100644 index 000000000..760e1a8ce --- /dev/null +++ b/doc/src/frameworks-technologies/templates.qdoc @@ -0,0 +1,229 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page templates.html + \title Why Doesn't Qt Use Templates for Signals and Slots? + \brief The reasoning behind Qt's implementation of signals and slots. + + Templates are a builtin mechanism in C++ that allows the compiler to + generate code on the fly, depending on the type of the arguments + passed. As such, templates are highly interesting to framework + creators, and we do use advanced templates in many places + in Qt. However, there are limitations: There are things that you can + easily express with templates, and there are things that are + impossible to express with templates. A generic vector container class + is easily expressible, even with partial specialisation for pointer + types, while a function that sets up a graphical user interface based + on a XML description given as a string is not expressible as + template. And then there is gray area in between. Things that you can + hack with templates at the cost of code size, readability, + portability, usability, extensability, robustness and ultimately + design beauty. Both templates and the C preprocessor can be stretched + to do incredibility smart and mind boggling things. But just because + those things can be done, does not necessarily mean doing them is the + right design choice. + + There is an important practical challenge we have to mention: due to + the inadequacies of various compilers it is still not possible to + fully exploit the template mechanism in cross-platform + applications. Code unfortunately is not meant to be published in + books, but compiled with real-world compilers on real-world operating + system. Even today, many widely used C++ compilers have problems with + advanced templates. For example, you cannot safely rely on partial + template specialisation, which is essential for some non-trivial + problem domains. Some compilers also have limitations with regards to + template member functions, which make it hard to combine generic + programming with object orientated programming. However, we do not + perceive these problems as a serious limitation in our work. Even if + all our users had access to a fully standards compliant modern C++ + compiler with excellent template support, we would not abandon the + string-based approach used by our meta object compiler for a template + based signals and slots system. Here are five reasons why: + + \section1 Syntax matters + + Syntax isn't just sugar: the syntax we use to express our algorithms can + significantly affect the readability and maintainability of our code. + The syntax used for Qt's signals and slots has proved very successful in + practice. The syntax is intuitive, simple to use and easy to read. + People learning Qt find the syntax helps them understand and utilize the + signals and slots concept -- despite its highly abstract and generic + nature. Furthermore, declaring signals in class definitions ensures that + the signals are protected in the sense of protected C++ member + functions. This helps programmers get their design right from the very + beginning, without even having to think about design patterns. + + \section1 Code Generators are Good + + Qt's \c{moc} (Meta Object Compiler) provides a clean way to go + beyond the compiled language's facilities. It does so by generating + additional C++ code which can be compiled by any standard C++ compiler. + The \c{moc} reads C++ source files. If it finds one or more class + declarations that contain the Q_OBJECT macro, it produces another C++ + source file which contains the meta object code for those classes. The + C++ source file generated by the \c{moc} must be compiled and + linked with the implementation of the class (or it can be + \c{#included} into the class's source file). Typically \c{moc} + is not called manually, but automatically by the build system, so it + requires no additional effort by the programmer. + + The \c{moc} is not the only code generator Qt is using. Another + prominent example is the \c{uic} (User Interface Compiler). It + takes a user interface description in XML and creates C++ code that + sets up the form. Outside Qt, code generators are common as well. Take + for example \c{rpc} and \c{idl}, that enable programs or + objects to communicate over process or machine boundaries. Or the vast + variety of scanner and parser generators, with \c{lex} and + \c{yacc} being the most well-known ones. They take a grammar + specification as input and generate code that implements a state + machine. The alternatives to code generators are hacked compilers, + proprietary languages or graphical programming tools with one-way + dialogs or wizards that generate obscure code during design time + rather than compile time. Rather than locking our customers into a + proprietary C++ compiler or into a particular Integrated Development + Environment, we enable them to use whatever tools they prefer. Instead + of forcing programmers to add generated code into source repositories, + we encourage them to add our tools to their build system: cleaner, + safer and more in the spirit of UNIX. + + + \section1 GUIs are Dynamic + + C++ is a standarized, powerful and elaborate general-purpose language. + It's the only language that is exploited on such a wide range of + software projects, spanning every kind of application from entire + operating systems, database servers and high end graphics + applications to common desktop applications. One of the keys to C++'s + success is its scalable language design that focuses on maximum + performance and minimal memory consumption whilst still maintaining + ANSI C compatibility. + + For all these advantages, there are some downsides. For C++, the static + object model is a clear disadvantage over the dynamic messaging approach + of Objective C when it comes to component-based graphical user interface + programming. What's good for a high end database server or an operating + system isn't necessarily the right design choice for a GUI frontend. + With \c{moc}, we have turned this disadvantage into an advantage, + and added the flexibility required to meet the challenge of safe and + efficient graphical user interface programming. + + Our approach goes far beyond anything you can do with templates. For + example, we can have object properties. And we can have overloaded + signals and slots, which feels natural when programming in a language + where overloads are a key concept. Our signals add zero bytes to the + size of a class instance, which means we can add new signals without + breaking binary compatibility. Because we do not rely on excessive + inlining as done with templates, we can keep the code size smaller. + Adding new connections just expands to a simple function call rather + than a complex template function. + + Another benefit is that we can explore an object's signals and slots at + runtime. We can establish connections using type-safe call-by-name, + without having to know the exact types of the objects we are connecting. + This is impossible with a template based solution. This kind of runtime + introspection opens up new possibilities, for example GUIs that are + generated and connected from Qt Designer's XML UI files. + + \section1 Calling Performance is Not Everything + + Qt's signals and slots implementation is not as fast as a + template-based solution. While emitting a signal is approximately the + cost of four ordinary function calls with common template + implementations, Qt requires effort comparable to about ten function + calls. This is not surprising since the Qt mechanism includes a + generic marshaller, introspection, queued calls between different + threads, and ultimately scriptability. It does not rely on excessive + inlining and code expansion and it provides unmatched runtime + safety. Qt's iterators are safe while those of faster template-based + systems are not. Even during the process of emitting a signal to + several receivers, those receivers can be deleted safely without your + program crashing. Without this safety, your application would + eventually crash with a difficult to debug free'd memory read or write + error. + + Nonetheless, couldn't a template-based solution improve the performance + of an application using signals and slots? While it is true that Qt adds + a small overhead to the cost of calling a slot through a signal, the + cost of the call is only a small proportion of the entire cost of a + slot. Benchmarking against Qt's signals and slots system is typically + done with empty slots. As soon as you do anything useful in your slots, + for example a few simple string operations, the calling overhead becomes + negligible. Qt's system is so optimized that anything that requires + operator new or delete (for example, string operations or + inserting/removing something from a template container) is significantly + more expensive than emitting a signal. + + Aside: If you have a signals and slots connection in a tight inner loop + of a performance critical task and you identify this connection as the + bottleneck, think about using the standard listener-interface pattern + rather than signals and slots. In cases where this occurs, you probably + only require a 1:1 connection anyway. For example, if you have an object + that downloads data from the network, it's a perfectly sensible design + to use a signal to indicate that the requested data arrived. But if you + need to send out every single byte one by one to a consumer, use a + listener interface rather than signals and slots. + + \section1 No Limits + + Because we had the \c{moc} for signals and slots, we could add + other useful things to it that could not be done with templates. + Among these are scoped translations via a generated \c{tr()} + function, and an advanced property system with introspection and + extended runtime type information. The property system alone is a + great advantage: a powerful and generic user interface design tool + like Qt Designer would be a lot harder to write - if not impossible - + without a powerful and introspective property system. But it does not + end here. We also provide a dynamic qobject_cast<T>() mechanism + that does not rely on the system's RTTI and thus does not share its + limitations. We use it to safely query interfaces from dynamically + loaded components. Another application domain are dynamic meta + objects. We can e.g. take ActiveX components and at runtime create a + meta object around it. Or we can export Qt components as ActiveX + components by exporting its meta object. You cannot do either of these + things with templates. + + C++ with the \c{moc} essentially gives us the flexibility of + Objective-C or of a Java Runtime Environment, while maintaining C++'s + unique performance and scalability advantages. It is what makes Qt the + flexible and comfortable tool we have today. + +*/ diff --git a/doc/src/frameworks-technologies/threads.qdoc b/doc/src/frameworks-technologies/threads.qdoc new file mode 100644 index 000000000..f15678448 --- /dev/null +++ b/doc/src/frameworks-technologies/threads.qdoc @@ -0,0 +1,700 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group thread + \title Threading Classes +*/ + +/*! + \page threads.html + \title Thread Support in Qt + \brief A detailed discussion of thread handling in Qt. + + \ingroup frameworks-technologies + + \nextpage Starting Threads with QThread + + Qt provides thread support in the form of platform-independent + threading classes, a thread-safe way of posting events, and + signal-slot connections across threads. This makes it easy to + develop portable multithreaded Qt applications and take advantage + of multiprocessor machines. Multithreaded programming is also a + useful paradigm for performing time-consuming operations without + freezing the user interface of an application. + + Earlier versions of Qt offered an option to build the library + without thread support. Since Qt 4.0, threads are always enabled. + + \section1 Topics: + + \list + \o \l{Recommended Reading} + \o \l{The Threading Classes} + \o \l{Starting Threads with QThread} + \o \l{Synchronizing Threads} + \o \l{Reentrancy and Thread-Safety} + \o \l{Threads and QObjects} + \o \l{Concurrent Programming} + \o \l{Thread-Support in Qt Modules} + \endlist + + \section1 Recommended Reading + + This document is intended for an audience that has knowledge of, + and experience with, multithreaded applications. If you are new + to threading see our Recommended Reading list: + + \list + \o \l{Threads Primer: A Guide to Multithreaded Programming} + \o \l{Thread Time: The Multithreaded Programming Guide} + \o \l{Pthreads Programming: A POSIX Standard for Better Multiprocessing} + \o \l{Win32 Multithreaded Programming} + \endlist + + \section1 The Threading Classes + + These classes are relevant to threaded applications. + + \annotatedlist thread + +\omit + \list + \o QThread provides the means to start a new thread. + \o QThreadStorage provides per-thread data storage. + \o QThreadPool manages a pool of threads that run QRunnable objects. + \o QRunnable is an abstract class representing a runnable object. + \o QMutex provides a mutual exclusion lock, or mutex. + \o QMutexLocker is a convenience class that automatically locks + and unlocks a QMutex. + \o QReadWriteLock provides a lock that allows simultaneous read access. + \o QReadLocker and QWriteLocker are convenience classes that automatically + lock and unlock a QReadWriteLock. + \o QSemaphore provides an integer semaphore (a generalization of a mutex). + \o QWaitCondition provides a way for threads to go to sleep until + woken up by another thread. + \o QAtomicInt provides atomic operations on integers. + \o QAtomicPointer provides atomic operations on pointers. + \endlist +\endomit + + \note Qt's threading classes are implemented with native threading APIs; + e.g., Win32 and pthreads. Therefore, they can be used with threads of the + same native API. +*/ + +/*! + \page threads-starting.html + \title Starting Threads with QThread + + \contentspage Thread Support in Qt + \nextpage Synchronizing Threads + + A QThread instance represents a thread and provides the means to + \l{QThread::start()}{start()} a thread, which will then execute the + reimplementation of QThread::run(). The \c run() implementation is for a + thread what the \c main() entry point is for the application. All code + executed in a call stack that starts in the \c run() function is executed + by the new thread, and the thread finishes when the function returns. + QThread emits signals to indicate that the thread started or finished + executing. + + \section1 Creating a Thread + + To create a thread, subclass QThread and reimplement its + \l{QThread::run()}{run()} function. For example: + + \snippet doc/src/snippets/threads/threads.h 0 + \codeline + \snippet doc/src/snippets/threads/threads.cpp 0 + \snippet doc/src/snippets/threads/threads.cpp 1 + \dots + \snippet doc/src/snippets/threads/threads.cpp 2 + + \section1 Starting a Thread + + Then, create an instance of the thread object and call + QThread::start(). Note that you must create the QApplication (or + QCoreApplication) object before you can create a QThread. + + The function will return immediately and the + main thread will continue. The code that appears in the + \l{QThread::run()}{run()} reimplementation will then be executed + in a separate thread. + + Creating threads is explained in more detail in the QThread + documentation. + + Note that QCoreApplication::exec() must always be called from the + main thread (the thread that executes \c{main()}), not from a + QThread. In GUI applications, the main thread is also called the + GUI thread because it's the only thread that is allowed to + perform GUI-related operations. +*/ + +/*! + \page threads-synchronizing.html + \title Synchronizing Threads + + \previouspage Starting Threads with QThread + \contentspage Thread Support in Qt + \nextpage Reentrancy and Thread-Safety + + The QMutex, QReadWriteLock, QSemaphore, and QWaitCondition + classes provide means to synchronize threads. While the main idea + with threads is that they should be as concurrent as possible, + there are points where threads must stop and wait for other + threads. For example, if two threads try to access the same + global variable simultaneously, the results are usually + undefined. + + QMutex provides a mutually exclusive lock, or mutex. At most one + thread can hold the mutex at any time. If a thread tries to + acquire the mutex while the mutex is already locked, the thread will + be put to sleep until the thread that currently holds the mutex + unlocks it. Mutexes are often used to protect accesses to shared + data (i.e., data that can be accessed from multiple threads + simultaneously). In the \l{Reentrancy and Thread-Safety} section + below, we will use it to make a class thread-safe. + + QReadWriteLock is similar to QMutex, except that it distinguishes + between "read" and "write" access to shared data and allows + multiple readers to access the data simultaneously. Using + QReadWriteLock instead of QMutex when it is possible can make + multithreaded programs more concurrent. + + QSemaphore is a generalization of QMutex that protects a certain + number of identical resources. In contrast, a mutex protects + exactly one resource. The \l{threads/semaphores}{Semaphores} + example shows a typical application of semaphores: synchronizing + access to a circular buffer between a producer and a consumer. + + QWaitCondition allows a thread to wake up other threads when some + condition has been met. One or many threads can block waiting for + a QWaitCondition to set a condition with + \l{QWaitCondition::wakeOne()}{wakeOne()} or + \l{QWaitCondition::wakeAll()}{wakeAll()}. Use + \l{QWaitCondition::wakeOne()}{wakeOne()} to wake one randomly + selected event or \l{QWaitCondition::wakeAll()}{wakeAll()} to + wake them all. The \l{threads/waitconditions}{Wait Conditions} + example shows how to solve the producer-consumer problem using + QWaitCondition instead of QSemaphore. + + Note that Qt's synchronization classes rely on the use of properly + aligned pointers. For instance, you cannot use packed classes with + MSVC. +*/ + +/*! + \page threads-reentrancy.html + \title Reentrancy and Thread-Safety + + \keyword reentrant + \keyword thread-safe + + \previouspage Synchronizing Threads + \contentspage Thread Support in Qt + \nextpage Threads and QObjects + + Throughout the documentation, the terms \e{reentrant} and + \e{thread-safe} are used to mark classes and functions to indicate + how they can be used in multithread applications: + + \list + \o A \e thread-safe function can be called simultaneously from + multiple threads, even when the invocations use shared data, + because all references to the shared data are serialized. + \o A \e reentrant function can also be called simultaneously from + multiple threads, but only if each invocation uses its own data. + \endlist + + Hence, a \e{thread-safe} function is always \e{reentrant}, but a + \e{reentrant} function is not always \e{thread-safe}. + + By extension, a class is said to be \e{reentrant} if its member + functions can be called safely from multiple threads, as long as + each thread uses a \e{different} instance of the class. The class + is \e{thread-safe} if its member functions can be called safely + from multiple threads, even if all the threads use the \e{same} + instance of the class. + + C++ classes are often reentrant, simply because they only access + their own member data. Any thread can call a member function on an + instance of a reentrant class, as long as no other thread can call + a member function on the \e{same} instance of the class at the + same time. For example, the \c Counter class below is reentrant: + + \snippet doc/src/snippets/threads/threads.cpp 3 + \snippet doc/src/snippets/threads/threads.cpp 4 + + The class isn't thread-safe, because if multiple threads try to + modify the data member \c n, the result is undefined. This is + because the \c ++ and \c -- operators aren't always atomic. + Indeed, they usually expand to three machine instructions: + + \list 1 + \o Load the variable's value in a register. + \o Increment or decrement the register's value. + \o Store the register's value back into main memory. + \endlist + + If thread A and thread B load the variable's old value + simultaneously, increment their register, and store it back, they + end up overwriting each other, and the variable is incremented + only once! + + Clearly, the access must be serialized: Thread A must perform + steps 1, 2, 3 without interruption (atomically) before thread B + can perform the same steps; or vice versa. An easy way to make + the class thread-safe is to protect all access to the data + members with a QMutex: + + \snippet doc/src/snippets/threads/threads.cpp 5 + \snippet doc/src/snippets/threads/threads.cpp 6 + + The QMutexLocker class automatically locks the mutex in its + constructor and unlocks it when the destructor is invoked, at the + end of the function. Locking the mutex ensures that access from + different threads will be serialized. The \c mutex data member is + declared with the \c mutable qualifier because we need to lock + and unlock the mutex in \c value(), which is a const function. + + Many Qt classes are \e{reentrant}, but they are not made + \e{thread-safe}, because making them thread-safe would incur the + extra overhead of repeatedly locking and unlocking a QMutex. For + example, QString is reentrant but not thread-safe. You can safely + access \e{different} instances of QString from multiple threads + simultaneously, but you can't safely access the \e{same} instance + of QString from multiple threads simultaneously (unless you + protect the accesses yourself with a QMutex). + + Some Qt classes and functions are thread-safe. These are mainly + the thread-related classes (e.g. QMutex) and fundamental functions + (e.g. QCoreApplication::postEvent()). + + \note Qt Classes are only documented as \e{thread-safe} if they + are intended to be used by multiple threads. + + \note Terminology in the multithreading domain isn't entirely + standardized. POSIX uses definitions of reentrant and thread-safe + that are somewhat different for its C APIs. When using other + object-oriented C++ class libraries with Qt, be sure the + definitions are understood. +*/ + +/*! + \page threads-qobject.html + \title Threads and QObjects + + \previouspage Reentrancy and Thread Safety + \contentspage Thread Support in Qt + \nextpage Concurrent Programming + + QThread inherits QObject. It emits signals to indicate that the + thread started or finished executing, and provides a few slots as + well. + + More interesting is that \l{QObject}s can be used in multiple + threads, emit signals that invoke slots in other threads, and + post events to objects that "live" in other threads. This is + possible because each thread is allowed to have its own event + loop. + + Topics: + + \tableofcontents + + \section1 QObject Reentrancy + + QObject is reentrant. Most of its non-GUI subclasses, such as + QTimer, QTcpSocket, QUdpSocket, QFtp, and QProcess, are also + reentrant, making it possible to use these classes from multiple + threads simultaneously. Note that these classes are designed to be + created and used from within a single thread; creating an object + in one thread and calling its functions from another thread is not + guaranteed to work. There are three constraints to be aware of: + + \list + \o \e{The child of a QObject must always be created in the thread + where the parent was created.} This implies, among other + things, that you should never pass the QThread object (\c + this) as the parent of an object created in the thread (since + the QThread object itself was created in another thread). + + \o \e{Event driven objects may only be used in a single thread.} + Specifically, this applies to the \l{timers.html}{timer + mechanism} and the \l{QtNetwork}{network module}. For example, + you cannot start a timer or connect a socket in a thread that + is not the \l{QObject::thread()}{object's thread}. + + \o \e{You must ensure that all objects created in a thread are + deleted before you delete the QThread.} This can be done + easily by creating the objects on the stack in your + \l{QThread::run()}{run()} implementation. + \endlist + + Although QObject is reentrant, the GUI classes, notably QWidget + and all its subclasses, are not reentrant. They can only be used + from the main thread. As noted earlier, QCoreApplication::exec() + must also be called from that thread. + + In practice, the impossibility of using GUI classes in other + threads than the main thread can easily be worked around by + putting time-consuming operations in a separate worker thread and + displaying the results on screen in the main thread when the + worker thread is finished. This is the approach used for + implementing the \l{threads/mandelbrot}{Mandelbrot} and + the \l{network/blockingfortuneclient}{Blocking Fortune Client} + example. + + \section1 Per-Thread Event Loop + + Each thread can have its own event loop. The initial thread + starts its event loops using QCoreApplication::exec(); other + threads can start an event loop using QThread::exec(). Like + QCoreApplication, QThread provides an + \l{QThread::exit()}{exit(int)} function and a + \l{QThread::quit()}{quit()} slot. + + An event loop in a thread makes it possible for the thread to use + certain non-GUI Qt classes that require the presence of an event + loop (such as QTimer, QTcpSocket, and QProcess). It also makes it + possible to connect signals from any threads to slots of a + specific thread. This is explained in more detail in the + \l{Signals and Slots Across Threads} section below. + + \image threadsandobjects.png Threads, objects, and event loops + + A QObject instance is said to \e live in the thread in which it + is created. Events to that object are dispatched by that thread's + event loop. The thread in which a QObject lives is available using + QObject::thread(). + + Note that for QObjects that are created before QApplication, + QObject::thread() returns zero. This means that the main thread + will only handle posted events for these objects; other event + processing is not done at all for objects with no thread. Use the + QObject::moveToThread() function to change the thread affinity for + an object and its children (the object cannot be moved if it has a + parent). + + Calling \c delete on a QObject from a thread other than the one + that \e owns the object (or accessing the object in other ways) is + unsafe, unless you guarantee that the object isn't processing + events at that moment. Use QObject::deleteLater() instead, and a + \l{QEvent::DeferredDelete}{DeferredDelete} event will be posted, + which the event loop of the object's thread will eventually pick + up. By default, the thread that \e owns a QObject is the thread + that \e creates the QObject, but not after QObject::moveToThread() + has been called. + + If no event loop is running, events won't be delivered to the + object. For example, if you create a QTimer object in a thread but + never call \l{QThread::exec()}{exec()}, the QTimer will never emit + its \l{QTimer::timeout()}{timeout()} signal. Calling + \l{QObject::deleteLater()}{deleteLater()} won't work + either. (These restrictions apply to the main thread as well.) + + You can manually post events to any object in any thread at any + time using the thread-safe function + QCoreApplication::postEvent(). The events will automatically be + dispatched by the event loop of the thread where the object was + created. + + Event filters are supported in all threads, with the restriction + that the monitoring object must live in the same thread as the + monitored object. Similarly, QCoreApplication::sendEvent() + (unlike \l{QCoreApplication::postEvent()}{postEvent()}) can only + be used to dispatch events to objects living in the thread from + which the function is called. + + \section1 Accessing QObject Subclasses from Other Threads + + QObject and all of its subclasses are not thread-safe. This + includes the entire event delivery system. It is important to keep + in mind that the event loop may be delivering events to your + QObject subclass while you are accessing the object from another + thread. + + If you are calling a function on an QObject subclass that doesn't + live in the current thread and the object might receive events, + you must protect all access to your QObject subclass's internal + data with a mutex; otherwise, you may experience crashes or other + undesired behavior. + + Like other objects, QThread objects live in the thread where the + object was created -- \e not in the thread that is created when + QThread::run() is called. It is generally unsafe to provide slots + in your QThread subclass, unless you protect the member variables + with a mutex. + + On the other hand, you can safely emit signals from your + QThread::run() implementation, because signal emission is + thread-safe. + + \section1 Signals and Slots Across Threads + + Qt supports three types of signal-slot connections: + + \list + \o With \l{Qt::DirectConnection}{direct connections}, the + slot gets called immediately when the signal is emitted. The + slot is executed in the thread that emitted the signal (which + is not necessarily the thread where the receiver object + lives). + + \o With \l{Qt::QueuedConnection}{queued connections}, the + slot is invoked when control returns to the event loop of the + thread to which the object belongs. The slot is executed in + the thread where the receiver object lives. + + \o With \l{Qt::AutoConnection}{auto connections} (the default), + the behavior is the same as with direct connections if + the signal is emitted in the thread where the receiver lives; + otherwise, the behavior is that of a queued connection. + \endlist + + The connection type can be specified by passing an additional + argument to \l{QObject::connect()}{connect()}. Be aware that + using direct connections when the sender and receiver live in + different threads is unsafe if an event loop is running in the + receiver's thread, for the same reason that calling any function + on an object living in another thread is unsafe. + + QObject::connect() itself is thread-safe. + + The \l{threads/mandelbrot}{Mandelbrot} example uses a queued + connection to communicate between a worker thread and the main + thread. To avoid freezing the main thread's event loop (and, as a + consequence, the application's user interface), all the + Mandelbrot fractal computation is done in a separate worker + thread. The thread emits a signal when it is done rendering the + fractal. + + Similarly, the \l{network/blockingfortuneclient}{Blocking Fortune + Client} example uses a separate thread for communicating with + a TCP server asynchronously. +*/ + +/*! + \page threads-qtconcurrent.html + \title Concurrent Programming + + \previouspage Threads and QObjects + \contentspage Thread Support in Qt + \nextpage Thread-Support in Qt Modules + + \target qtconcurrent intro + + The QtConcurrent namespace provides high-level APIs that make it + possible to write multi-threaded programs without using low-level + threading primitives such as mutexes, read-write locks, wait + conditions, or semaphores. Programs written with QtConcurrent + automatically adjust the number of threads used according to the + number of processor cores available. This means that applications + written today will continue to scale when deployed on multi-core + systems in the future. + + QtConcurrent includes functional programming style APIs for + parallel list processing, including a MapReduce and FilterReduce + implementation for shared-memory (non-distributed) systems, and + classes for managing asynchronous computations in GUI + applications: + + \list + + \o QtConcurrent::map() applies a function to every item in a container, + modifying the items in-place. + + \o QtConcurrent::mapped() is like map(), except that it returns a new + container with the modifications. + + \o QtConcurrent::mappedReduced() is like mapped(), except that the + modified results are reduced or folded into a single result. + + \o QtConcurrent::filter() removes all items from a container based on the + result of a filter function. + + \o QtConcurrent::filtered() is like filter(), except that it returns a new + container with the filtered results. + + \o QtConcurrent::filteredReduced() is like filtered(), except that the + filtered results are reduced or folded into a single result. + + \o QtConcurrent::run() runs a function in another thread. + + \o QFuture represents the result of an asynchronous computation. + + \o QFutureIterator allows iterating through results available via QFuture. + + \o QFutureWatcher allows monitoring a QFuture using signals-and-slots. + + \o QFutureSynchronizer is a convenience class that automatically + synchronizes several QFutures. + + \endlist + + Qt Concurrent supports several STL-compatible container and iterator types, + but works best with Qt containers that have random-access iterators, such as + QList or QVector. The map and filter functions accept both containers and begin/end iterators. + + STL Iterator support overview: + + \table + \header + \o Iterator Type + \o Example classes + \o Support status + \row + \o Input Iterator + \o + \o Not Supported + \row + \o Output Iterator + \o + \o Not Supported + \row + \o Forward Iterator + \o std::slist + \o Supported + \row + \o Bidirectional Iterator + \o QLinkedList, std::list + \o Supported + \row + \o Random Access Iterator + \o QList, QVector, std::vector + \o Supported and Recommended + \endtable + + Random access iterators can be faster in cases where Qt Concurrent is iterating + over a large number of lightweight items, since they allow skipping to any point + in the container. In addition, using random access iterators allows Qt Concurrent + to provide progress information trough QFuture::progressValue() and QFutureWatcher:: + progressValueChanged(). + + The non in-place modifying functions such as mapped() and filtered() makes a + copy of the container when called. If you are using STL containers this copy operation + might take some time, in this case we recommend specifying the begin and end iterators + for the container instead. +*/ + +/*! + \page threads-modules.html + \title Thread-Support in Qt Modules + + \previouspage Concurrent Programming + \contentspage Thread Support in Qt + + \section1 Threads and the SQL Module + + A connection can only be used from within the thread that created it. + Moving connections between threads or creating queries from a different + thread is not supported. + + In addition, the third party libraries used by the QSqlDrivers can impose + further restrictions on using the SQL Module in a multithreaded program. + Consult the manual of your database client for more information + + \section1 Painting in Threads + + QPainter can be used in a thread to paint onto QImage, QPrinter, and + QPicture paint devices. Painting onto QPixmaps and QWidgets is \e not + supported. On Mac OS X the automatic progress dialog will not be + displayed if you are printing from outside the GUI thread. + + Any number of threads can paint at any given time, however only + one thread at a time can paint on a given paint device. In other + words, two threads can paint at the same time if each paints onto + separate QImages, but the two threads cannot paint onto the same + QImage at the same time. + + Note that on X11 systems without FontConfig support, Qt cannot + render text outside of the GUI thread. You can use the + QFontDatabase::supportsThreadedFontRendering() function to detect + whether or not font rendering can be used outside the GUI thread. + + \section1 Threads and Rich Text Processing + + The QTextDocument, QTextCursor, and \link richtext.html all + related classes\endlink are reentrant. + + Note that a QTextDocument instance created in the GUI thread may + contain QPixmap image resources. Use QTextDocument::clone() to + create a copy of the document, and pass the copy to another thread for + further processing (such as printing). + + \section1 Threads and the SVG module + + The QSvgGenerator and QSvgRenderer classes in the QtSvg module + are reentrant. + + \section1 Threads and Implicitly Shared Classes + + Qt uses an optimization called \l{implicit sharing} for many of + its value class, notably QImage and QString. Beginning with Qt 4, + implicit shared classes can safely be copied across threads, like + any other value classes. They are fully + \l{Reentrancy and Thread-Safety}{reentrant}. The implicit sharing + is really \e implicit. + + In many people's minds, implicit sharing and multithreading are + incompatible concepts, because of the way the reference counting + is typically done. Qt, however, uses atomic reference counting to + ensure the integrity of the shared data, avoiding potential + corruption of the reference counter. + + Note that atomic reference counting does not guarantee + \l{Reentrancy and Thread-Safety}{thread-safety}. Proper locking should be used + when sharing an instance of an implicitly shared class between + threads. This is the same requirement placed on all + \l{Reentrancy and Thread-Safety}{reentrant} classes, shared or not. Atomic reference + counting does, however, guarantee that a thread working on its + own, local instance of an implicitly shared class is safe. We + recommend using \l{Signals and Slots Across Threads}{signals and + slots} to pass data between threads, as this can be done without + the need for any explicit locking. + + To sum it up, implicitly shared classes in Qt 4 are really \e + implicitly shared. Even in multithreaded applications, you can + safely use them as if they were plain, non-shared, reentrant + value-based classes. +*/ diff --git a/doc/src/frameworks-technologies/unicode.qdoc b/doc/src/frameworks-technologies/unicode.qdoc new file mode 100644 index 000000000..fc0a61e9c --- /dev/null +++ b/doc/src/frameworks-technologies/unicode.qdoc @@ -0,0 +1,182 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group string-processing + \title Classes for String Data + + \brief Classes for working with string data. + + These classes are relevant when working with string data. See the + \l{Unicode in Qt}{information about support for Unicode in Qt} for + more information. +*/ + + +/*! + \page unicode.html + \title Unicode in Qt + \brief Information about support for Unicode in Qt. + + \keyword Unicode + + \ingroup frameworks-technologies + + Unicode is a multi-byte character set, portable across all major + computing platforms and with decent coverage over most of the world. + It is also single-locale; it includes no code pages or other + complexities that make software harder to write and test. There is no + competing character set that's reasonably cross-platform. For these + reasons, Unicode 4.0 is used as the native character set for Qt. + + \section1 Qt's Classes for Working with Strings + + These classes are relevant when working with string data. For information + about rendering text, see the \l{Rich Text Processing} overview, and if + your string data is in XML, see the \l{XML Processing} overview. + + \annotatedlist string-processing + + \section1 Information about Unicode on the Web + + The \l{http://www.unicode.org/}{Unicode Consortium} has a number + of documents available, including + + \list + + \i \l{http://www.unicode.org/unicode/standard/principles.html}{A + technical introduction to Unicode} + \i \l{http://www.unicode.org/unicode/standard/standard.html}{The + home page for the standard} + + \endlist + + + \section1 The Standard + + The current version of the standard is \l{http://www.unicode.org/versions/Unicode5.1.0/}{Unicode 5.1.0}. + + Previous printed versions of the specification: + + \list + \o \l{http://www.amazon.com/Unicode-Standard-Version-5-0-5th/dp/0321480910/trolltech/t}{The Unicode Standard, Version 5.0} + \o \l{http://www.amazon.com/exec/obidos/ASIN/0321185781/trolltech/t}{The Unicode Standard, version 4.0} + \o \l{http://www.amazon.com/exec/obidos/ASIN/0201616335/trolltech/t}{The Unicode Standard, version 3.2} + \o \l{http://www.amazon.com/exec/obidos/ASIN/0201473459/trolltech/t}{The Unicode Standard, version 2.0} \mdash + see also the \l{http://www.unicode.org/unicode/reports/tr8.html}{2.1 update} and + \l{http://www.unicode.org/unicode/standard/versions/enumeratedversions.html#Unicode 2.1.9}{the 2.1.9 data files} at + \l{http://www.unicode.org}. + \endlist + + \section1 Unicode in Qt + + In Qt, and in most applications that use Qt, most or all user-visible + strings are stored using Unicode. Qt provides: + + \list + + \i Translation to/from legacy encodings for file I/O: see + QTextCodec and QTextStream. + \i Translation from Input Methods and 8-bit keyboard input. + \i Translation to legacy character sets for on-screen display. + \i A string class, QString, that stores Unicode characters, with + support for migrating from C strings including fast (cached) + translation to and from US-ASCII, and all the usual string + operations. + \i Unicode-aware widgets where appropriate. + \i Unicode support detection on Windows, so that Qt provides Unicode + even on Windows platforms that do not support it natively. + + \endlist + + To fully benefit from Unicode, we recommend using QString for storing + all user-visible strings, and performing all text file I/O using + QTextStream. Use QKeyEvent::text() for keyboard input in any custom + widgets you write; it does not make much difference for slow typists + in Western Europe or North America, but for fast typists or people + using special input methods using text() is beneficial. + + All the function arguments in Qt that may be user-visible strings, + QLabel::setText() and a many others, take \c{const QString &}s. + QString provides implicit casting from \c{const char *} + so that things like + + \snippet doc/src/snippets/code/doc_src_unicode.qdoc 0 + + will work. There is also a function, QObject::tr(), that provides + translation support, like this: + + \snippet doc/src/snippets/code/doc_src_unicode.qdoc 1 + + QObject::tr() maps from \c{const char *} to a Unicode string, and + uses installable QTranslator objects to do the mapping. + + Qt provides a number of built-in QTextCodec classes, that is, + classes that know how to translate between Unicode and legacy + encodings to support programs that must talk to other programs or + read/write files in legacy file formats. + + By default, conversion to/from \c{const char *} uses a + locale-dependent codec. However, applications can easily find codecs + for other locales, and set any open file or network connection to use + a special codec. It is also possible to install new codecs, for + encodings that the built-in ones do not support. (At the time of + writing, Vietnamese/VISCII is one such example.) + + Since US-ASCII and ISO-8859-1 are so common, there are also especially + fast functions for mapping to and from them. For example, to open an + application's icon one might do this: + + \snippet doc/src/snippets/code/doc_src_unicode.qdoc 2 + + or + + \snippet doc/src/snippets/code/doc_src_unicode.qdoc 3 + + Regarding output, Qt will do a best-effort conversion from + Unicode to whatever encoding the system and fonts provide. + Depending on operating system, locale, font availability, and Qt's + support for the characters used, this conversion may be good or bad. + We will extend this in upcoming versions, with emphasis on the most + common locales first. + + \sa {Internationalization with Qt} +*/ |