 |
Qt 4.8
|
|
Qt 4.8
|
The QWeakPointer class holds a weak reference to a shared pointer. More...
#include <qsharedpointer.h>
Public Functions | |
| void | clear () |
| Clears this QWeakPointer object, dropping the reference that it may have had to the pointer. More... | |
| T * | data () const |
| bool | isNull () const |
| Returns true if this object is holding a reference to a null pointer. More... | |
| operator bool () const | |
| Returns true if this object is not null. More... | |
| bool | operator! () const |
| Returns true if this object is null. More... | |
| QWeakPointer< T > | operator= (const QWeakPointer< T > &other) |
| Makes this object share other's pointer. More... | |
| QWeakPointer< T > | operator= (const QSharedPointer< T > &other) |
| Makes this object share other's pointer. More... | |
| QWeakPointer< T > | operator= (const QObject *other) |
| QWeakPointer () | |
| Creates a QWeakPointer that points to nothing. More... | |
| QWeakPointer (const QWeakPointer< T > &other) | |
| Creates a QWeakPointer that holds a weak reference to the pointer referenced by other. More... | |
| QWeakPointer (const QSharedPointer< T > &other) | |
| Creates a QWeakPointer that holds a weak reference to the pointer referenced by other. More... | |
| QWeakPointer (const QObject *other) | |
| QSharedPointer< T > | toStrongRef () const |
| Promotes this weak reference to a strong one and returns a QSharedPointer object holding that reference. More... | |
| ~QWeakPointer () | |
| Destroys this QWeakPointer object. More... | |
Related Functions | |
(Note that these are not member functions.) | |
| bool | operator!= (const QSharedPointer< T > &ptr1, const QWeakPointer< X > &ptr2) |
| Returns true if the pointer referenced by ptr1 is not the same pointer as that referenced by ptr2. More... | |
| bool | operator!= (const QWeakPointer< T > &ptr1, const QSharedPointer< X > &ptr2) |
| Returns true if the pointer referenced by ptr1 is not the same pointer as that referenced by ptr2. More... | |
| bool | operator== (const QSharedPointer< T > &ptr1, const QWeakPointer< X > &ptr2) |
| Returns true if the pointer referenced by ptr1 is the same pointer as that referenced by ptr2. More... | |
| bool | operator== (const QWeakPointer< T > &ptr1, const QSharedPointer< X > &ptr2) |
| Returns true if the pointer referenced by ptr1 is the same pointer as that referenced by ptr2. More... | |
| QSharedPointer< X > | qSharedPointerCast (const QWeakPointer< T > &other) |
Returns a shared pointer to the pointer held by other, cast to type X. More... | |
| QSharedPointer< X > | qSharedPointerConstCast (const QWeakPointer< T > &other) |
Returns a shared pointer to the pointer held by other, cast to type X. More... | |
| QSharedPointer< X > | qSharedPointerDynamicCast (const QWeakPointer< T > &other) |
Returns a shared pointer to the pointer held by other, using a dynamic cast to type X to obtain an internal pointer of the appropriate type. More... | |
| QSharedPointer< X > | qSharedPointerObjectCast (const QWeakPointer< T > &other) |
| The qSharedPointerObjectCast function is for casting a shared pointer. More... | |
| QWeakPointer< X > | qWeakPointerCast (const QWeakPointer< T > &other) |
Returns a weak pointer to the pointer held by other, cast to type X. More... | |
The QWeakPointer class holds a weak reference to a shared pointer.
The QWeakPointer is an automatic weak reference to a pointer in C++. It cannot be used to dereference the pointer directly, but it can be used to verify if the pointer has been deleted or not in another context.
QWeakPointer objects can only be created by assignment from a QSharedPointer. The exception is pointers derived from QObject: in that case, QWeakPointer serves as a replacement to QPointer.
It's important to note that QWeakPointer provides no automatic casting operators to prevent mistakes from happening. Even though QWeakPointer tracks a pointer, it should not be considered a pointer itself, since it doesn't guarantee that the pointed object remains valid.
Therefore, to access the pointer that QWeakPointer is tracking, you must first promote it to QSharedPointer and verify if the resulting object is null or not. QSharedPointer guarantees that the object isn't deleted, so if you obtain a non-null object, you may use the pointer. See QWeakPointer::toStrongRef() for an example.
QWeakPointer also provides the QWeakPointer::data() method that returns the tracked pointer without ensuring that it remains valid. This function is provided if you can guarantee by external means that the object will not get deleted (or if you only need the pointer value) and the cost of creating a QSharedPointer using toStrongRef() is too high.
That function can also be used to obtain the tracked pointer for QWeakPointers that cannot be promoted to QSharedPointer, such as those created directly from a QObject pointer (not via QSharedPointer).
QWeakPointer can be used to track deletion of classes that derive from QObject, even if they are not managed by QSharedPointer. When used in that role, QWeakPointer replaces the older QPointer in all use-cases. QWeakPointer is also more efficient than QPointer, so it should be preferred in all new code.
To do that, QWeakPointer provides a special constructor that is only available if the template parameter T is either QObject or a class deriving from it. Trying to use that constructor if T does not derive from QObject will result in compilation errors.
To obtain the QObject being tracked by QWeakPointer, you must use the QWeakPointer::data() function, but only if you can guarantee that the object cannot get deleted by another context. It should be noted that QPointer had the same constraint, so use of QWeakPointer forces you to consider whether the pointer is still valid.
QObject-derived classes can only be deleted in the thread they have affinity to (which is the thread they were created in or moved to, using QObject::moveToThread()). In special, QWidget-derived classes cannot be created in non-GUI threads nor moved there. Therefore, guaranteeing that the tracked QObject has affinity to the current thread is enough to also guarantee that it won't be deleted asynchronously.
Note that QWeakPointer's size and data layout do not match QPointer, so it cannot replace that class in a binary-compatible manner.
Care must also be taken with QWeakPointers created directly from QObject pointers when dealing with code that was compiled with Qt versions prior to 4.6. Those versions may not track the reference counters correctly, so QWeakPointers created from QObject should never be passed to code that hasn't been recompiled.
QWeakPointer shares most of its internal functionality with QSharedPointer, so see that class's internal documentation for more information.
QWeakPointer requires an external reference counter in order to operate. Therefore, it is incompatible by design with QSharedData-derived classes.
It has a special QObject constructor, which works by calling QtSharedPointer::ExternalRefCountData::getAndRef, which retrieves the d-pointer from QObjectPrivate. If one isn't set yet, that function creates the d-pointer and atomically sets it.
If getAndRef needs to create a d-pointer, it sets the strongref to -1, indicating that the QObject is not shared: QWeakPointer is used only to determine whether the QObject has been deleted. In that case, it cannot be upgraded to QSharedPointer (see the previous section).
Definition at line 97 of file qsharedpointer.h.
| QWeakPointer< T >::QWeakPointer | ( | ) |
Creates a QWeakPointer that points to nothing.
| QWeakPointer< T >::QWeakPointer | ( | const QWeakPointer< T > & | other | ) |
Creates a QWeakPointer that holds a weak reference to the pointer referenced by other.
If T is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.
| QWeakPointer< T >::QWeakPointer | ( | const QSharedPointer< T > & | other | ) |
Creates a QWeakPointer that holds a weak reference to the pointer referenced by other.
If T is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.
| QWeakPointer< T >::~QWeakPointer | ( | ) |
Destroys this QWeakPointer object.
The pointer referenced by this object will not be deleted.
| QWeakPointer< T >::QWeakPointer | ( | const QObject * | obj | ) |
Creates a QWeakPointer that holds a weak reference directly to the QObject obj. This constructor is only available if the template type T is QObject or derives from it (otherwise a compilation error will result).
You can use this constructor with any QObject, even if they were not created with QSharedPointer .
Note that QWeakPointers created this way on arbitrary QObjects usually cannot be promoted to QSharedPointer.
| void QWeakPointer< T >::clear | ( | ) |
Clears this QWeakPointer object, dropping the reference that it may have had to the pointer.
Referenced by QDeclarativeTransitionManager::cancel(), QmlJSDebugger::BoundingRectHighlighter::freeBoundingBox(), qt_cleanup(), and QmlJSDebugger::BoundingBox::~BoundingBox().
| T * QWeakPointer< T >::data | ( | ) | const |
Returns the value of the pointer being tracked by this QWeakPointer, without ensuring that it cannot get deleted. To have that guarantee, use toStrongRef(), which returns a QSharedPointer object. If this function can determine that the pointer has already been deleted, it returns 0.
It is ok to obtain the value of the pointer and using that value itself, like for example in debugging statements:
However, dereferencing the pointer is only allowed if you can guarantee by external means that the pointer does not get deleted. For example, if you can be certain that no other thread can delete it, nor the functions that you may call.
If that is the case, then the following code is valid:
Use this function with care.
Referenced by QDeclarativeState::addEntriesToRevertList(), QDeclarativeTransitionManagerPrivate::applyBindings(), QDeclarativeSimpleAction::binding(), QmlJSDebugger::BoundingRectHighlighter::boxFor(), QDeclarativeTransitionManager::cancel(), QmlJSDebugger::LiveSelectionIndicator::clear(), QDialog::contextMenuEvent(), QAbstractItemView::dataChanged(), QmlJSDebugger::BoundingRectHighlighter::freeBoundingBox(), QGraphicsScenePrivate::gestureEventHandler(), QmlJSDebugger::BoundingRectHighlighter::highlightAll(), QPluginLoader::instance(), QmlJSDebugger::BoundingRectHighlighter::itemDestroyed(), QNetworkRequest::originatingObject(), qt_cleanup(), qt_qpa_set_cursor(), QAbstractItemView::reset(), QmlJSDebugger::QDeclarativeViewInspectorPrivate::selectedItems(), QmlJSDebugger::LiveSelectionTool::selectedItemsChanged(), QDeclarativeEngineDebugService::setBinding(), QCalendarPopup::setCalendarWidget(), QmlJSDebugger::LiveSelectionIndicator::setItems(), QmlJSDebugger::QDeclarativeViewInspectorPrivate::setSelectedItems(), QmlJSDebugger::QDeclarativeViewInspectorPrivate::setSelectedItemsForTools(), QWidgetPrivate::setStyle_helper(), QDeclarativeTransitionManager::transition(), QApplicationPrivate::translateRawTouchEvent(), QLibraryPrivate::unload(), QCalendarPopup::verifyCalendarInstance(), and QmlJSDebugger::LiveSelectionRectangle::~LiveSelectionRectangle().
| bool QWeakPointer< T >::isNull | ( | ) | const |
Returns true if this object is holding a reference to a null pointer.
Note that, due to the nature of weak references, the pointer that QWeakPointer references can become null at any moment, so the value returned from this function can change from false to true from one call to the next.
Referenced by QDeclarativeState::addEntriesToRevertList(), QDeclarativeTransitionManagerPrivate::applyBindings(), QDeclarativeTransitionManager::cancel(), QmlJSDebugger::LiveSelectionIndicator::clear(), QmlJSDebugger::BoundingRectHighlighter::createBoundingBox(), QmlJSDebugger::BoundingRectHighlighter::freeBoundingBox(), QmlJSDebugger::BoundingRectHighlighter::highlightAll(), QApplication::notify(), qt_cleanup(), QmlJSDebugger::LiveSelectionTool::selectedItemsChanged(), QDeclarativeTransitionManager::transition(), and QCalendarPopup::verifyCalendarInstance().
| QWeakPointer< T >::operator bool | ( | ) | const |
Returns true if this object is not null.
This function is suitable for use in if-constructs, like:
Note that, due to the nature of weak references, the pointer that QWeakPointer references can become null at any moment, so the value returned from this function can change from true to false from one call to the next.
| bool QWeakPointer< T >::operator! | ( | ) | const |
Returns true if this object is null.
This function is suitable for use in if-constructs, like:
Note that, due to the nature of weak references, the pointer that QWeakPointer references can become null at any moment, so the value returned from this function can change from false to true from one call to the next.
| QWeakPointer & QWeakPointer< T >::operator= | ( | const QWeakPointer< T > & | other | ) |
Makes this object share other's pointer.
The current pointer reference is discarded but is not deleted.
If T is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.
| QWeakPointer & QWeakPointer< T >::operator= | ( | const QSharedPointer< T > & | other | ) |
Makes this object share other's pointer.
The current pointer reference is discarded but is not deleted.
If T is a derived type of the template parameter of this class, QWeakPointer will perform an automatic cast. Otherwise, you will get a compiler error.
| QWeakPointer & QWeakPointer< T >::operator= | ( | const QObject * | obj | ) |
Makes this QWeakPointer hold a weak reference directly to the QObject obj. This function is only available if the template type T is QObject or derives from it.
| QSharedPointer< T > QWeakPointer< T >::toStrongRef | ( | ) | const |
Promotes this weak reference to a strong one and returns a QSharedPointer object holding that reference.
When promoting to QSharedPointer, this function verifies if the object has been deleted already or not. If it hasn't, this function increases the reference count to the shared object, thus ensuring that it will not get deleted.
Since this function can fail to obtain a valid strong reference to the shared object, you should always verify if the conversion succeeded, by calling QSharedPointer::isNull() on the returned object.
For example, the following code promotes a QWeakPointer that was held to a strong reference and, if it succeeded, it prints the value of the integer that was held:
Referenced by QSharedNetworkSessionManager::getSession().
|
related |
Returns true if the pointer referenced by ptr1 is not the same pointer as that referenced by ptr2.
If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic static_cast to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.
|
related |
Returns true if the pointer referenced by ptr1 is not the same pointer as that referenced by ptr2.
If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic static_cast to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.
|
related |
Returns true if the pointer referenced by ptr1 is the same pointer as that referenced by ptr2.
If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic static_cast to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.
|
related |
Returns true if the pointer referenced by ptr1 is the same pointer as that referenced by ptr2.
If ptr2's template parameter is different from ptr1's, QSharedPointer will attempt to perform an automatic static_cast to ensure that the pointers being compared are equal. If ptr2's template parameter is not a base or a derived type from ptr1's, you will get a compiler error.
|
related |
Returns a shared pointer to the pointer held by other, cast to type X.
The types T and X must belong to one hierarchy for the static_cast to succeed.
The other object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function returns a null QSharedPointer.
Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.
|
related |
Returns a shared pointer to the pointer held by other, cast to type X.
The types T and X must belong to one hierarchy for the const_cast to succeed. The const and volatile differences between T and X are ignored.
The other object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function returns a null QSharedPointer.
|
related |
Returns a shared pointer to the pointer held by other, using a dynamic cast to type X to obtain an internal pointer of the appropriate type.
If the dynamic_cast fails, the object returned will be null.
The other object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function also returns a null QSharedPointer.
Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.
|
related |
The qSharedPointerObjectCast function is for casting a shared pointer.
Returns a shared pointer to the pointer held by other, using a qobject_cast() to type X to obtain an internal pointer of the appropriate type. If the qobject_cast fails, the object returned will be null.
The other object is converted first to a strong reference. If that conversion fails (because the object it's pointing to has already been deleted), this function also returns a null QSharedPointer.
Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.
|
related |
Returns a weak pointer to the pointer held by other, cast to type X.
The types T and X must belong to one hierarchy for the static_cast to succeed.
Note that X must have the same cv-qualifiers (const and volatile) that T has, or the code will fail to compile. Use qSharedPointerConstCast to cast away the constness.