QWeakPointer Class Reference

Member Function Documentation

QWeakPointer::QWeakPointer ()

Creates a QWeakPointer that points to nothing.

QWeakPointer::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::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::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.

This function was introduced in Qt 4.6.

See also QSharedPointer and QWeakPointer#tracking-qobject.

QWeakPointer::~QWeakPointer ()

Destroys this QWeakPointer object. The pointer referenced by this object will not be deleted.

void QWeakPointer::clear ()

Clears this QWeakPointer object, dropping the reference that it may have had to the pointer.

T * QWeakPointer::data () const

Returns the value of the pointer being tracked by this QWeakPointer, \b 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:

 qDebug("Tracking %p", weakref.data());

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:

 // this pointer cannot be used in another thread
 // so other threads cannot delete it
 QWeakPointer<int> weakref = obtainReference();

 Object *obj = weakref.data();
 if (obj) {
     // if the pointer wasn't deleted yet, we know it can't get
     // deleted by our own code here nor the functions we call
     otherFunction(obj);
 }

Use this function with care.

This function was introduced in Qt 4.6.

See also isNull() and toStrongRef().

bool QWeakPointer::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.

QSharedPointer<T> QWeakPointer::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:

 QWeakPointer<int> weakref;

 // ...

 QSharedPointer<int> strong = weakref.toStrongRef();
 if (strong)
     qDebug() << "The value is:" << *strong;
 else
     qDebug() << "The value has already been deleted";

See also QSharedPointer::QSharedPointer().

QWeakPointer::operator bool () const

Returns true if this object is not null. This function is suitable for use in if-constructs, like:

 if (weakref) { ... }

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.

See also isNull().

bool QWeakPointer::operator! () const

Returns true if this object is null. This function is suitable for use in if-constructs, like:

 if (!weakref) { ... }

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.

See also isNull().

QWeakPointer<T> QWeakPointer::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<T> QWeakPointer::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<T> QWeakPointer::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.

This function was introduced in Qt 4.6.

See also QWeakPointer#tracking-qobject.