diff options
Diffstat (limited to 'doc/src/corelib/objectmodel')
| -rw-r--r-- | doc/src/corelib/objectmodel/metaobjects.qdoc | 137 | ||||
| -rw-r--r-- | doc/src/corelib/objectmodel/object.qdoc | 124 | ||||
| -rw-r--r-- | doc/src/corelib/objectmodel/objecttrees.qdoc | 102 | ||||
| -rw-r--r-- | doc/src/corelib/objectmodel/properties.qdoc | 273 | ||||
| -rw-r--r-- | doc/src/corelib/objectmodel/signalsandslots.qdoc | 468 |
5 files changed, 0 insertions, 1104 deletions
diff --git a/doc/src/corelib/objectmodel/metaobjects.qdoc b/doc/src/corelib/objectmodel/metaobjects.qdoc deleted file mode 100644 index c92f6f2f09..0000000000 --- a/doc/src/corelib/objectmodel/metaobjects.qdoc +++ /dev/null @@ -1,137 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page metaobjects.html - \title The Meta-Object System - \brief An overview of Qt's meta-object system and introspection capabilities. - - \ingroup qt-basic-concepts - \keyword meta-object - \target Meta-Object System - - Qt's meta-object system provides the signals and slots mechanism for - inter-object communication, run-time type information, and the dynamic - property system. - - The meta-object system is based on three things: - - \list 1 - \li The \l QObject class provides a base class for objects that can - take advantage of the meta-object system. - \li The Q_OBJECT macro inside the private section of the class - declaration is used to enable meta-object features, such as - dynamic properties, signals, and slots. - \li The \l{moc}{Meta-Object Compiler} (\c moc) supplies each - QObject subclass with the necessary code to implement - meta-object features. - \endlist - - The \c moc tool reads a C++ source file. 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 each of those classes. This generated source file is - either \c{#include}'d into the class's source file or, more - usually, compiled and linked with the class's implementation. - - In addition to providing the \l{signals and slots} mechanism for - communication between objects (the main reason for introducing - the system), the meta-object code provides the following - additional features: - - \list - \li QObject::metaObject() returns the associated - \l{QMetaObject}{meta-object} for the class. - \li QMetaObject::className() returns the class name as a - string at run-time, without requiring native run-time type information - (RTTI) support through the C++ compiler. - \li QObject::inherits() function returns whether an object is an - instance of a class that inherits a specified class within the - QObject inheritance tree. - \li QObject::tr() and QObject::trUtf8() translate strings for - \l{Internationalization with Qt}{internationalization}. - \li QObject::setProperty() and QObject::property() - dynamically set and get properties by name. - \li QMetaObject::newInstance() constructs a new instance of the class. - \endlist - - \target qobjectcast - It is also possible to perform dynamic casts using qobject_cast() - on QObject classes. The qobject_cast() function behaves similarly - to the standard C++ \c dynamic_cast(), with the advantages - that it doesn't require RTTI support and it works across dynamic - library boundaries. It attempts to cast its argument to the pointer - type specified in angle-brackets, returning a non-zero pointer if the - object is of the correct type (determined at run-time), or 0 - if the object's type is incompatible. - - For example, let's assume \c MyWidget inherits from QWidget and - is declared with the Q_OBJECT macro: - - \snippet doc/src/snippets/qtcast/qtcast.cpp 0 - - The \c obj variable, of type \c{QObject *}, actually refers to a - \c MyWidget object, so we can cast it appropriately: - - \snippet doc/src/snippets/qtcast/qtcast.cpp 1 - - The cast from QObject to QWidget is successful, because the - object is actually a \c MyWidget, which is a subclass of QWidget. - Since we know that \c obj is a \c MyWidget, we can also cast it to - \c{MyWidget *}: - - \snippet doc/src/snippets/qtcast/qtcast.cpp 2 - - The cast to \c MyWidget is successful because qobject_cast() - makes no distinction between built-in Qt types and custom types. - - \snippet doc/src/snippets/qtcast/qtcast.cpp 3 - \snippet doc/src/snippets/qtcast/qtcast.cpp 4 - - The cast to QLabel, on the other hand, fails. The pointer is then - set to 0. This makes it possible to handle objects of different - types differently at run-time, based on the type: - - \snippet doc/src/snippets/qtcast/qtcast.cpp 5 - \snippet doc/src/snippets/qtcast/qtcast.cpp 6 - - While it is possible to use QObject as a base class without the - Q_OBJECT macro and without meta-object code, neither signals - and slots nor the other features described here will be available - if the Q_OBJECT macro is not used. From the meta-object - system's point of view, a QObject subclass without meta code is - equivalent to its closest ancestor with meta-object code. This - means for example, that QMetaObject::className() will not return - the actual name of your class, but the class name of this - ancestor. - - Therefore, we strongly recommend that all subclasses of QObject - use the Q_OBJECT macro regardless of whether or not they - actually use signals, slots, and properties. - - \sa QMetaObject, {Qt's Property System}, {Signals and Slots} -*/ diff --git a/doc/src/corelib/objectmodel/object.qdoc b/doc/src/corelib/objectmodel/object.qdoc deleted file mode 100644 index 4e212b37dd..0000000000 --- a/doc/src/corelib/objectmodel/object.qdoc +++ /dev/null @@ -1,124 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page object.html - \title Object Model - \ingroup qt-basic-concepts - \brief A description of the powerful features made possible by Qt's dynamic object model. - - The standard C++ object model provides very efficient runtime - support for the object paradigm. But its static nature is - inflexibile in certain problem domains. Graphical user interface - programming is a domain that requires both runtime efficiency and - a high level of flexibility. Qt provides this, by combining the - speed of C++ with the flexibility of the Qt Object Model. - - Qt adds these features to C++: - - \list - \li a very powerful mechanism for seamless object - communication called \l{signals and slots} - \li queryable and designable \l{Qt's Property System}{object - properties} - \li powerful \l{The Event System}{events and event filters} - \li contextual \l{i18n}{string translation for internationalization} - \li sophisticated interval driven \l timers that make it possible - to elegantly integrate many tasks in an event-driven GUI - \li hierarchical and queryable \l{Object Trees & Ownership}{object - trees} that organize object ownership in a natural way - \li guarded pointers (QPointer) that are automatically - set to 0 when the referenced object is destroyed, unlike normal C++ - pointers which become dangling pointers when their objects are destroyed - \li a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across - library boundaries. - \endlist - - Many of these Qt features are implemented with standard C++ - techniques, based on inheritance from QObject. Others, like the - object communication mechanism and the dynamic property system, - require the \l{Meta-Object System} provided - by Qt's own \l{moc}{Meta-Object Compiler (moc)}. - - The meta-object system is a C++ extension that makes the language - better suited to true component GUI programming. Although - templates can be used to extend C++, the meta-object system - provides benefits using standard C++ that cannot be achieved with - templates; see \l{Why Doesn't Qt Use Templates for Signals and - Slots?} - - \section1 Important Classes - - These classes form the basis of the Qt Object Model. - - \annotatedlist objectmodel - - \target Identity vs Value - \section1 Qt Objects: Identity vs Value - - Some of the added features listed above for the Qt Object Model, - require that we think of Qt Objects as identities, not values. - Values are copied or assigned; identities are cloned. Cloning - means to create a new identity, not an exact copy of the old - one. For example, twins have different identities. They may look - identical, but they have different names, different locations, and - may have completely different social networks. - - Then cloning an identity is a more complex operation than copying - or assigning a value. We can see what this means in the Qt Object - Model. - - \b{A Qt Object...} - - \list - - \li might have a unique \l{QObject::objectName()}. If we copy a Qt - Object, what name should we give the copy? - - \li has a location in an \l{Object Trees & Ownership} - {object hierarchy}. If we copy a Qt Object, where should the copy - be located? - - \li can be connected to other Qt Objects to emit signals to them or - to receive signals emitted by them. If we copy a Qt Object, how - should we transfer these connections to the copy? - - \li can have \l{Qt's Property System} {new properties} added to it - at runtime that are not declared in the C++ class. If we copy a Qt - Object, should the copy include the properties that were added to - the original? - - \endlist - - For these reasons, Qt Objects should be treated as identities, not - as values. Identities are cloned, not copied or assigned, and - cloning an identity is a more complex operation than copying or - assigning a value. Therefore, QObject and all subclasses of - QObject (direct or indirect) have their \l{No copy constructor} - {copy constructor and assignment operator} disabled. - - */ diff --git a/doc/src/corelib/objectmodel/objecttrees.qdoc b/doc/src/corelib/objectmodel/objecttrees.qdoc deleted file mode 100644 index 3e51eeba83..0000000000 --- a/doc/src/corelib/objectmodel/objecttrees.qdoc +++ /dev/null @@ -1,102 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page objecttrees.html - \title Object Trees & Ownership - \ingroup qt-basic-concepts - \brief Information about the parent-child pattern used to describe - object ownership in Qt. - - \section1 Overview - - \link QObject QObjects\endlink organize themselves in object trees. - When you create a QObject with another object as parent, it's added to - the parent's \link QObject::children() children() \endlink list, and - is deleted when the parent is. It turns out that this approach fits - the needs of GUI objects very well. For example, a \l QShortcut - (keyboard shortcut) is a child of the relevant window, so when the - user closes that window, the shorcut is deleted too. - - \l QWidget, the base class of everything that appears on the screen, - extends the parent-child relationship. A child normally also becomes a - child widget, i.e. it is displayed in its parent's coordinate system - and is graphically clipped by its parent's boundaries. For example, - when the application deletes a message box after it has been - closed, the message box's buttons and label are also deleted, just as - we'd want, because the buttons and label are children of the message - box. - - You can also delete child objects yourself, and they will remove - themselves from their parents. For example, when the user removes a - toolbar it may lead to the application deleting one of its \l QToolBar - objects, in which case the tool bar's \l QMainWindow parent would - detect the change and reconfigure its screen space accordingly. - - The debugging functions \l QObject::dumpObjectTree() and \l - QObject::dumpObjectInfo() are often useful when an application looks or - acts strangely. - - \target note on the order of construction/destruction of QObjects - \section1 Construction/Destruction Order of QObjects - - When \l {QObject} {QObjects} are created on the heap (i.e., created - with \e new), a tree can be constructed from them in any order, and - later, the objects in the tree can be destroyed in any order. When any - QObject in the tree is deleted, if the object has a parent, the - destructor automatically removes the object from its parent. If the - object has children, the destructor automatically deletes each - child. No QObject is deleted twice, regardless of the order of - destruction. - - When \l {QObject} {QObjects} are created on the stack, the same - behavior applies. Normally, the order of destruction still doesn't - present a problem. Consider the following snippet: - - \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 0 - - The parent, \c window, and the child, \c quit, are both \l {QObject} - {QObjects} because QPushButton inherits QWidget, and QWidget inherits - QObject. This code is correct: the destructor of \c quit is \e not - called twice because the C++ language standard \e {(ISO/IEC 14882:2003)} - specifies that destructors of local objects are called in the reverse - order of their constructors. Therefore, the destructor of - the child, \c quit, is called first, and it removes itself from its - parent, \c window, before the destructor of \c window is called. - - But now consider what happens if we swap the order of construction, as - shown in this second snippet: - - \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 1 - - In this case, the order of destruction causes a problem. The parent's - destructor is called first because it was created last. It then calls - the destructor of its child, \c quit, which is incorrect because \c - quit is a local variable. When \c quit subsequently goes out of scope, - its destructor is called again, this time correctly, but the damage has - already been done. -*/ diff --git a/doc/src/corelib/objectmodel/properties.qdoc b/doc/src/corelib/objectmodel/properties.qdoc deleted file mode 100644 index 4d090af8fc..0000000000 --- a/doc/src/corelib/objectmodel/properties.qdoc +++ /dev/null @@ -1,273 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page properties.html - \title The Property System - \brief An overview of Qt's property system. - - \ingroup qt-basic-concepts - \target Qt's Property System - - Qt provides a sophisticated property system similar to the ones - supplied by some compiler vendors. However, as a compiler- and - platform-independent library, Qt does not rely on non-standard - compiler features like \c __property or \c [property]. The Qt - solution works with \e any standard C++ compiler on every platform - Qt supports. It is based on the \l {Meta-Object System} that also - provides inter-object communication via \l{signals and slots}. - - \section1 Requirements for Declaring Properties - - To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()} - macro in a class that inherits QObject. - - \snippet doc/src/snippets/code/doc_src_properties.cpp 0 - - Here are some typical examples of property declarations taken from - class QWidget. - - \snippet doc/src/snippets/code/doc_src_properties.cpp 1 - - A property behaves like a class data member, but it has additional - features accessible through the \l {Meta-Object System}. - - \list - - \li A \c READ accessor function is required. It is for reading the - property value. Ideally, a const function is used for this purpose, - and it must return either the property's type or a pointer or - reference to that type. e.g., QWidget::focus is a read-only property - with \c READ function, QWidget::hasFocus(). - - \li A \c WRITE accessor function is optional. It is for setting the - property value. It must return void and must take exactly one - argument, either of the property's type or a pointer or reference - to that type. e.g., QWidget::enabled has the \c WRITE function - QWidget::setEnabled(). Read-only properties do not need \c WRITE - functions. e.g., QWidget::focus has no \c WRITE function. - - \li A \c RESET function is optional. It is for setting the property - back to its context specific default value. e.g., QWidget::cursor - has the typical \c READ and \c WRITE functions, QWidget::cursor() - and QWidget::setCursor(), and it also has a \c RESET function, - QWidget::unsetCursor(), since no call to QWidget::setCursor() can - mean \e {reset to the context specific cursor}. The \c RESET - function must return void and take no parameters. - - \li A \c NOTIFY signal is optional. If defined, it should specify one - existing signal in that class that is emitted whenever the value - of the property changes. - - \li A \c REVISION number is optional. If included, it defines the - the property and its notifier signal to be used in a particular - revision of the API that is exposed to QML. - - \li The \c DESIGNABLE attribute indicates whether the property - should be visible in the property editor of GUI design tool (e.g., - \l {Qt Designer}). Most properties are \c DESIGNABLE (default - true). Instead of true or false, you can specify a boolean - member function. - - \li The \c SCRIPTABLE attribute indicates whether this property - should be accessible by a scripting engine (default true). - Instead of true or false, you can specify a boolean member - function. - - \li The \c STORED attribute indicates whether the property should - be thought of as existing on its own or as depending on other - values. It also indicates whether the property value must be saved - when storing the object's state. Most properties are \c STORED - (default true), but e.g., QWidget::minimumWidth() has \c STORED - false, because its value is just taken from the width component - of property QWidget::minimumSize(), which is a QSize. - - \li The \c USER attribute indicates whether the property is - designated as the user-facing or user-editable property for the - class. Normally, there is only one \c USER property per class - (default false). e.g., QAbstractButton::checked is the user - editable property for (checkable) buttons. Note that QItemDelegate - gets and sets a widget's \c USER property. - - \li The presence of the \c CONSTANT attibute indicates that the property - value is constant. For a given object instance, the READ method of a - constant property must return the same value every time it is called. This - constant value may be different for different instances of the object. A - constant property cannot have a WRITE method or a NOTIFY signal. - - \li The presence of the \c FINAL attribute indicates that the property - will not be overridden by a derived class. This can be used for performance - optimizations in some cases, but is not enforced by moc. Care must be taken - never to override a \c FINAL property. - - \endlist - - The \c READ, \c WRITE, and \c RESET functions can be inherited. - They can also be virtual. When they are inherited in classes where - multiple inheritance is used, they must come from the first - inherited class. - - The property type can be any type supported by QVariant, or it can - be a user-defined type. In this example, class QDate is considered - to be a user-defined type. - - \snippet doc/src/snippets/code/doc_src_properties.cpp 2 - - Because QDate is user-defined, you must include the \c{<QDate>} - header file with the property declaration. - - For QMap, QList, and QValueList properties, the property value is - a QVariant whose value is the entire list or map. Note that the - Q_PROPERTY string cannot contain commas, because commas separate - macro arguments. Therefore, you must use \c QMap as the property - type instead of \c QMap<QString,QVariant>. For consistency, also - use \c QList and \c QValueList instead of \c QList<QVariant> and - \c QValueList<QVariant>. - - \section1 Reading and Writing Properties with the Meta-Object System - - A property can be read and written using the generic functions - QObject::property() and QObject::setProperty(), without knowing - anything about the owning class except the property's name. In - the code snippet below, the call to QAbstractButton::setDown() and - the call to QObject::setProperty() both set property "down". - - \snippet doc/src/snippets/code/doc_src_properties.cpp 3 - - Accessing a property through its \c WRITE accessor is the better - of the two, because it is faster and gives better diagnostics at - compile time, but setting the property this way requires that you - know about the class at compile time. Accessing properties by name - lets you access classes you don't know about at compile time. You - can \e discover a class's properties at run time by querying its - QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}. - - \snippet doc/src/snippets/code/doc_src_properties.cpp 4 - - In the above snippet, QMetaObject::property() is used to get \l - {QMetaProperty} {metadata} about each property defined in some - unknown class. The property name is fetched from the metadata and - passed to QObject::property() to get the \l {QVariant} {value} of - the property in the current \l {QObject}{object}. - - \section1 A Simple Example - - Suppose we have a class MyClass, which is derived from QObject and - which uses the Q_OBJECT macro in its private section. We want to - declare a property in MyClass to keep track of a priorty - value. The name of the property will be \e priority, and its type - will be an enumeration type named \e Priority, which is defined in - MyClass. - - We declare the property with the Q_PROPERTY() macro in the private - section of the class. The required \c READ function is named \c - priority, and we include a \c WRITE function named \c setPriority. - The enumeration type must be registered with the \l {Meta-Object - System} using the Q_ENUMS() macro. Registering an enumeration type - makes the enumerator names available for use in calls to - QObject::setProperty(). We must also provide our own declarations - for the \c READ and \c WRITE functions. The declaration of MyClass - then might look like this: - - \snippet doc/src/snippets/code/doc_src_properties.cpp 5 - - The \c READ function is const and returns the property type. The - \c WRITE function returns void and has exactly one parameter of - the property type. The meta-object compiler enforces these - requirements. - - Given a pointer to an instance of MyClass or a pointer to a - QObject that is an instance of MyClass, we have two ways to set - its priority property: - - \snippet doc/src/snippets/code/doc_src_properties.cpp 6 - - In the example, the enumeration type that is the property type is - declared in MyClass and registered with the \l{Meta-Object System} - using the Q_ENUMS() macro. This makes the enumeration values - available as strings for use as in the call to setProperty(). Had - the enumeration type been declared in another class, its fully - qualified name (i.e., OtherClass::Priority) would be required, and - that other class would also have to inherit QObject and register - the enumeration type there using the Q_ENUMS() macro. - - A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it - registers an enumeration type, but it marks the type as being a - set of \e flags, i.e. values that can be OR'd together. An I/O - class might have enumeration values \c Read and \c Write and then - QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS() - should be used to register this enumeration type. - - \section1 Dynamic Properties - - QObject::setProperty() can also be used to add \e new properties - to an instance of a class at runtime. When it is called with a - name and a value, if a property with the given name exists in the - QObject, and if the given value is compatible with the property's - type, the value is stored in the property, and true is returned. - If the value is \e not compatible with the property's type, the - property is \e not changed, and false is returned. But if the - property with the given name doesn't exist in the QObject (i.e., - if it wasn't declared with Q_PROPERTY(), a new property with the - given name and value is automatically added to the QObject, but - false is still returned. This means that a return of false can't - be used to determine whether a particular property was actually - set, unless you know in advance that the property already exists - in the QObject. - - Note that \e dynamic properties are added on a per instance basis, - i.e., they are added to QObject, not QMetaObject. A property can - be removed from an instance by passing the property name and an - invalid QVariant value to QObject::setProperty(). The default - constructor for QVariant constructs an invalid QVariant. - - Dynamic properties can be queried with QObject::property(), just - like properties declared at compile time with Q_PROPERTY(). - - \sa {Meta-Object System}, {Signals and Slots} - - \section1 Properties and Custom Types - - Custom types used by properties need to be registered using the - Q_DECLARE_METATYPE() macro so that their values can be stored in - QVariant objects. This makes them suitable for use with both - static properties declared using the Q_PROPERTY() macro in class - definitions and dynamic properties created at run-time. - - \sa Q_DECLARE_METATYPE(), QMetaType, QVariant - - \section1 Adding Additional Information to a Class - - Connected to the property system is an additional macro, - Q_CLASSINFO(), that can be used to attach additional - \e{name}--\e{value} pairs to a class's meta-object, for example: - - \snippet doc/src/snippets/code/doc_src_properties.cpp 7 - - Like other meta-data, class information is accessible at run-time - through the meta-object; see QMetaObject::classInfo() for details. -*/ diff --git a/doc/src/corelib/objectmodel/signalsandslots.qdoc b/doc/src/corelib/objectmodel/signalsandslots.qdoc deleted file mode 100644 index 9100980121..0000000000 --- a/doc/src/corelib/objectmodel/signalsandslots.qdoc +++ /dev/null @@ -1,468 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page signalsandslots.html - \title Signals & Slots - \ingroup qt-basic-concepts - \brief An overview of Qt's signals and slots inter-object - communication mechanism. - - Signals and slots are used for communication between objects. The - signals and slots mechanism is a central feature of Qt and - probably the part that differs most from the features provided by - other frameworks. - - \tableofcontents - - \section1 Introduction - - In GUI programming, when we change one widget, we often want - another widget to be notified. More generally, we want objects of - any kind to be able to communicate with one another. For example, - if a user clicks a \gui{Close} button, we probably want the - window's \l{QWidget::close()}{close()} function to be called. - - Older toolkits achieve this kind of communication using - callbacks. A callback is a pointer to a function, so if you want - a processing function to notify you about some event you pass a - pointer to another function (the callback) to the processing - function. The processing function then calls the callback when - appropriate. Callbacks have two fundamental flaws: Firstly, they - are not type-safe. We can never be certain that the processing - function will call the callback with the correct arguments. - Secondly, the callback is strongly coupled to the processing - function since the processing function must know which callback - to call. - - \section1 Signals and Slots - - In Qt, we have an alternative to the callback technique: We use - signals and slots. A signal is emitted when a particular event - occurs. Qt's widgets have many predefined signals, but we can - always subclass widgets to add our own signals to them. A slot - is a function that is called in response to a particular signal. - Qt's widgets have many pre-defined slots, but it is common - practice to subclass widgets and add your own slots so that you - can handle the signals that you are interested in. - - \img abstract-connections.png - \omit - \caption An abstract view of some signals and slots connections - \endomit - - The signals and slots mechanism is type safe: The signature of a - signal must match the signature of the receiving slot. (In fact a - slot may have a shorter signature than the signal it receives - because it can ignore extra arguments.) Since the signatures are - compatible, the compiler can help us detect type mismatches. - Signals and slots are loosely coupled: A class which emits a - signal neither knows nor cares which slots receive the signal. - Qt's signals and slots mechanism ensures that if you connect a - signal to a slot, the slot will be called with the signal's - parameters at the right time. Signals and slots can take any - number of arguments of any type. They are completely type safe. - - All classes that inherit from QObject or one of its subclasses - (e.g., QWidget) can contain signals and slots. Signals are emitted by - objects when they change their state in a way that may be interesting - to other objects. This is all the object does to communicate. It - does not know or care whether anything is receiving the signals it - emits. This is true information encapsulation, and ensures that the - object can be used as a software component. - - Slots can be used for receiving signals, but they are also normal - member functions. Just as an object does not know if anything receives - its signals, a slot does not know if it has any signals connected to - it. This ensures that truly independent components can be created with - Qt. - - You can connect as many signals as you want to a single slot, and a - signal can be connected to as many slots as you need. It is even - possible to connect a signal directly to another signal. (This will - emit the second signal immediately whenever the first is emitted.) - - Together, signals and slots make up a powerful component programming - mechanism. - - \section1 A Small Example - - A minimal C++ class declaration might read: - - \snippet doc/src/snippets/signalsandslots/signalsandslots.h 0 - - A small QObject-based class might read: - - \snippet doc/src/snippets/signalsandslots/signalsandslots.h 1 - \codeline - \snippet doc/src/snippets/signalsandslots/signalsandslots.h 2 - \snippet doc/src/snippets/signalsandslots/signalsandslots.h 3 - - The QObject-based version has the same internal state, and provides - public methods to access the state, but in addition it has support - for component programming using signals and slots. This class can - tell the outside world that its state has changed by emitting a - signal, \c{valueChanged()}, and it has a slot which other objects - can send signals to. - - All classes that contain signals or slots must mention - Q_OBJECT at the top of their declaration. They must also derive - (directly or indirectly) from QObject. - - Slots are implemented by the application programmer. - Here is a possible implementation of the \c{Counter::setValue()} - slot: - - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 0 - - The \c{emit} line emits the signal \c valueChanged() from the - object, with the new value as argument. - - In the following code snippet, we create two \c Counter objects - and connect the first object's \c valueChanged() signal to the - second object's \c setValue() slot using QObject::connect(): - - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 1 - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 2 - \codeline - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 3 - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 4 - - Calling \c{a.setValue(12)} makes \c{a} emit a - \c{valueChanged(12)} signal, which \c{b} will receive in its - \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then - \c{b} emits the same \c{valueChanged()} signal, but since no slot - has been connected to \c{b}'s \c{valueChanged()} signal, the - signal is ignored. - - Note that the \c{setValue()} function sets the value and emits - the signal only if \c{value != m_value}. This prevents infinite - looping in the case of cyclic connections (e.g., if - \c{b.valueChanged()} were connected to \c{a.setValue()}). - - By default, for every connection you make, a signal is emitted; - two signals are emitted for duplicate connections. You can break - all of these connections with a single disconnect() call. - If you pass the Qt::UniqueConnection \a type, the connection will only - be made if it is not a duplicate. If there is already a duplicate - (exact same signal to the exact same slot on the same objects), - the connection will fail and connect will return false - - This example illustrates that objects can work together without needing to - know any information about each other. To enable this, the objects only - need to be connected together, and this can be achieved with some simple - QObject::connect() function calls, or with \c{uic}'s - \l{Using a Designer UI File in Your Application#Automatic Connections} - {automatic connections} feature. - - \section1 Building the Example - - The C++ preprocessor changes or removes the \c{signals}, - \c{slots}, and \c{emit} keywords so that the compiler is - presented with standard C++. - - By running the \l moc on class definitions that contain signals - or slots, a C++ source file is produced which should be compiled - and linked with the other object files for the application. If - you use \l qmake, the makefile rules to automatically invoke \c - moc will be added to your project's makefile. - - \section1 Signals - - Signals are emitted by an object when its internal state has changed - in some way that might be interesting to the object's client or owner. - Signals are public access functions and can be emitted from anywhere, - but we recommend to only emit them from the class that defines the - signal and its subclasses. - - When a signal is emitted, the slots connected to it are usually - executed immediately, just like a normal function call. When this - happens, the signals and slots mechanism is totally independent of - any GUI event loop. Execution of the code following the \c emit - statement will occur once all slots have returned. The situation is - slightly different when using \l{Qt::ConnectionType}{queued - connections}; in such a case, the code following the \c emit keyword - will continue immediately, and the slots will be executed later. - - If several slots are connected to one signal, the slots will be - executed one after the other, in the order they have been connected, - when the signal is emitted. - - Signals are automatically generated by the \l moc and must not be - implemented in the \c .cpp file. They can never have return types - (i.e. use \c void). - - A note about arguments: Our experience shows that signals and slots - are more reusable if they do not use special types. If - QScrollBar::valueChanged() were to use a special type such as the - hypothetical QScrollBar::Range, it could only be connected to - slots designed specifically for QScrollBar. Connecting different - input widgets together would be impossible. - - \section1 Slots - - A slot is called when a signal connected to it is emitted. Slots are - normal C++ functions and can be called normally; their only special - feature is that signals can be connected to them. - - Since slots are normal member functions, they follow the normal C++ - rules when called directly. However, as slots, they can be invoked - by any component, regardless of its access level, via a signal-slot - connection. This means that a signal emitted from an instance of an - arbitrary class can cause a private slot to be invoked in an instance - of an unrelated class. - - You can also define slots to be virtual, which we have found quite - useful in practice. - - Compared to callbacks, signals and slots are slightly slower - because of the increased flexibility they provide, although the - difference for real applications is insignificant. In general, - emitting a signal that is connected to some slots, is - approximately ten times slower than calling the receivers - directly, with non-virtual function calls. This is the overhead - required to locate the connection object, to safely iterate over - all connections (i.e. checking that subsequent receivers have not - been destroyed during the emission), and to marshall any - parameters in a generic fashion. While ten non-virtual function - calls may sound like a lot, it's much less overhead than any \c - new or \c delete operation, for example. As soon as you perform a - string, vector or list operation that behind the scene requires - \c new or \c delete, the signals and slots overhead is only - responsible for a very small proportion of the complete function - call costs. The same is true whenever you do a system call in a slot; - or indirectly call more than ten functions. - The simplicity and flexibility of the signals and slots mechanism is - well worth the overhead, which your users won't even notice. - - Note that other libraries that define variables called \c signals - or \c slots may cause compiler warnings and errors when compiled - alongside a Qt-based application. To solve this problem, \c - #undef the offending preprocessor symbol. - - \section1 Meta-Object Information - - The meta-object compiler (\l moc) parses the class declaration in - a C++ file and generates C++ code that initializes the - meta-object. The meta-object contains the names of all the signal - and slot members, as well as pointers to these functions. - - The meta-object contains additional information such as the - object's \link QObject::className() class name\endlink. You can - also check if an object \link QObject::inherits() - inherits\endlink a specific class, for example: - - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 5 - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 6 - - The meta-object information is also used by qobject_cast<T>(), which - is similar to QObject::inherits() but is less error-prone: - - \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 7 - - See \l{Meta-Object System} for more information. - - \section1 A Real Example - - Here is a simple commented example of a widget. - - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 0 - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 1 - \codeline - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 2 - \codeline - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 3 - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 4 - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 5 - - \c LcdNumber inherits QObject, which has most of the signal-slot - knowledge, via QFrame and QWidget. It is somewhat similar to the - built-in QLCDNumber widget. - - The Q_OBJECT macro is expanded by the preprocessor to declare - several member functions that are implemented by the \c{moc}; if - you get compiler errors along the lines of "undefined reference - to vtable for \c{LcdNumber}", you have probably forgotten to - \l{moc}{run the moc} or to include the moc output in the link - command. - - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 6 - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 7 - - It's not obviously relevant to the moc, but if you inherit - QWidget you almost certainly want to have the \c parent argument - in your constructor and pass it to the base class's constructor. - - Some destructors and member functions are omitted here; the \c - moc ignores member functions. - - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 8 - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 9 - - \c LcdNumber emits a signal when it is asked to show an impossible - value. - - If you don't care about overflow, or you know that overflow - cannot occur, you can ignore the \c overflow() signal, i.e. don't - connect it to any slot. - - If on the other hand you want to call two different error - functions when the number overflows, simply connect the signal to - two different slots. Qt will call both (in the order they were connected). - - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 10 - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 11 - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 12 - \codeline - \snippet doc/src/snippets/signalsandslots/lcdnumber.h 13 - - A slot is a receiving function used to get information about - state changes in other widgets. \c LcdNumber uses it, as the code - above indicates, to set the displayed number. Since \c{display()} - is part of the class's interface with the rest of the program, - the slot is public. - - Several of the example programs connect the - \l{QScrollBar::valueChanged()}{valueChanged()} signal of a - QScrollBar to the \c display() slot, so the LCD number - continuously shows the value of the scroll bar. - - Note that \c display() is overloaded; Qt will select the - appropriate version when you connect a signal to the slot. With - callbacks, you'd have to find five different names and keep track - of the types yourself. - - Some irrelevant member functions have been omitted from this - example. - - \section1 Signals And Slots With Default Arguments - - The signatures of signals and slots may contain arguments, and the - arguments can have default values. Consider QObject::destroyed(): - - \code - void destroyed(QObject* = 0); - \endcode - - When a QObject is deleted, it emits this QObject::destroyed() - signal. We want to catch this signal, wherever we might have a - dangling reference to the deleted QObject, so we can clean it up. - A suitable slot signature might be: - - \code - void objectDestroyed(QObject* obj = 0); - \endcode - - To connect the signal to the slot, we use QObject::connect(). - There are several ways to connect signal and slots. The first is to use - function pointers: - \code - connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed); - \endcode - - There are several advantages to using connect() with function pointers. - First, it allows the compiler to check that the signal's arguments are - compatible with the slot's arguments. Arguments can also be implicitly - converted by the compiler, if needed. - - You can also connect to functors or C++11 lamdas: - - \code - connect(sender, &QObject::destroyed, [=](){ this->m_objects.remove(sender); }); - \endcode - - Note that if your compiler does not support C++11 variadic templates, - this syntax only works if the signal and slot have 6 arguments or less. - - The other way to connect a signal to a slot is to use QObject::connect() - and the \c{SIGNAL} and \c{SLOT} macros. - The rule about whether to - include arguments or not in the \c{SIGNAL()} and \c{SLOT()} - macros, if the arguments have default values, is that the - signature passed to the \c{SIGNAL()} macro must \e not have fewer - arguments than the signature passed to the \c{SLOT()} macro. - - All of these would work: - \code - connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*))); - connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed())); - connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed())); - \endcode - But this one won't work: - \code - connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*))); - \endcode - - ...because the slot will be expecting a QObject that the signal - will not send. This connection will report a runtime error. - - Note that signal and slot arguments are not checked by the compiler when - using this QObject::connect() overload. - - \section1 Advanced Signals and Slots Usage - - For cases where you may require information on the sender of the - signal, Qt provides the QObject::sender() function, which returns - a pointer to the object that sent the signal. - - The QSignalMapper class is provided for situations where many - signals are connected to the same slot and the slot needs to - handle each signal differently. - - Suppose you have three push buttons that determine which file you - will open: "Tax File", "Accounts File", or "Report File". - - In order to open the correct file, you use QSignalMapper::setMapping() to - map all the clicked() signals to a QSignalMapper object. Then you connect - the file's QPushButton::clicked() signal to the QSignalMapper::map() slot. - - \snippet doc/src/snippets/signalmapper/filereader.cpp 0 - - Then, you connect the \l{QSignalMapper::}{mapped()} signal to - \c{readFile()} where a different file will be opened, depending on - which push button is pressed. - - \snippet doc/src/snippets/signalmapper/filereader.cpp 1 - - \sa {Meta-Object System}, {Qt's Property System} - - \target 3rd Party Signals and Slots - \section2 Using Qt with 3rd Party Signals and Slots - - It is possible to use Qt with a 3rd party signal/slot mechanism. - You can even use both mechanisms in the same project. Just add the - following line to your qmake project (.pro) file. - - \snippet doc/src/snippets/code/doc_src_containers.cpp 22 - - It tells Qt not to define the moc keywords \c{signals}, \c{slots}, - and \c{emit}, because these names will be used by a 3rd party - library, e.g. Boost. Then to continue using Qt signals and slots - with the \c{no_keywords} flag, simply replace all uses of the Qt - moc keywords in your sources with the corresponding Qt macros - Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT. -*/ |