QPointer< T > Class Template Reference

\inmodule QtCore More...

#include <qpointer.h>

Collaboration diagram for QPointer< T >:

Public Member Functions
Q_NODISCARD_CTOR	QPointer ()=default
Q_NODISCARD_CTOR	QPointer (T *p)
	Constructs a guarded pointer that points to the same object that p points to.
template<typename X , if_convertible< X > = true>
Q_NODISCARD_CTOR	QPointer (QPointer< X > &&other) noexcept
template<typename X , if_convertible< X > = true>
Q_NODISCARD_CTOR	QPointer (const QPointer< X > &other) noexcept
void	swap (QPointer &other) noexcept
QPointer< T > &	operator= (T *p)
	Assignment operator.
T *	data () const
T *	get () const
T *	operator-> () const
	Overloaded arrow operator; implements pointer semantics.
T &	operator* () const
	Dereference operator; implements pointer semantics.
	operator T* () const
	Cast operator; implements pointer semantics.
bool	isNull () const
	Returns true if the referenced object has been destroyed or if there is no referenced object; otherwise returns false.
void	clear ()

Friends
template<typename X >
class	QPointer
	Constructs a guarded pointer with value \nullptr.

Detailed Description

template<class T>
class QPointer< T >

\inmodule QtCore

The QPointer class is a template class that provides guarded pointers to QObject.

A guarded pointer, QPointer<T>, behaves like a normal C++ pointer {T *}, except that it is automatically cleared when the referenced object is destroyed (unlike normal C++ pointers, which become "dangling pointers" in such cases). T must be a subclass of QObject.

Guarded pointers are useful whenever you need to store a pointer to a QObject that is owned by someone else, and therefore might be destroyed while you still hold a reference to it. You can safely test the pointer for validity.

Note that Qt 5 introduces a slight change in behavior when using QPointer.

\list

• When using QPointer on a QWidget (or a subclass of QWidget), previously the QPointer would be cleared by the QWidget destructor. Now, the QPointer is cleared by the QObject destructor (since this is when QWeakPointer objects are cleared). Any QPointers tracking a widget will NOT be cleared before the QWidget destructor destroys the children for the widget being tracked.

\endlist

Qt also provides QSharedPointer, an implementation of a reference-counted shared pointer object, which can be used to maintain a collection of references to an individual pointer.

Example:

    QPointer<QLabel> label = new QLabel;
    label->setText("&Status:");

\dots

    if (label)

        label->show();

If the QLabel is deleted in the meantime, the label variable will hold \nullptr instead of an invalid address, and the last line will never be executed.

The functions and operators available with a QPointer are the same as those available with a normal unguarded pointer, except the pointer arithmetic operators ({+}, {-}, {++}, and {–}), which are normally used only with arrays of objects.

Use QPointers like normal pointers and you will not need to read this class documentation.

For creating guarded pointers, you can construct or assign to them from a T* or from another guarded pointer of the same type. You can compare them with each other using operator==() and operator!=(), or test for \nullptr with isNull(). You can dereference them using either the *x or the x->member notation.

A guarded pointer will automatically cast to a T *, so you can freely mix guarded and unguarded pointers. This means that if you have a QPointer<QWidget>, you can pass it to a function that requires a QWidget *. For this reason, it is of little value to declare functions to take a QPointer as a parameter; just use normal pointers. Use a QPointer when you are storing a pointer over time.

Note that class T must inherit QObject, or a compilation or link error will result.

See also

QSharedPointer, QObject, QObjectCleanupHandler

Definition at line 17 of file qpointer.h.

Constructor & Destructor Documentation

QPointer() [1/4]

template<class T >

Q_NODISCARD_CTOR QPointer< T >::QPointer ( )

default

QPointer() [2/4]

template<class T >

template< class T > QPointer< T >::QPointer ( T *  p )

inline

Constructs a guarded pointer that points to the same object that p points to.

Definition at line 33 of file qpointer.h.

QPointer() [3/4]

template<class T >

template<typename X , if_convertible< X > = true>

template< class T > template< class X > QPointer< T >::QPointer ( QPointer< X > &&  other )

inlinenoexcept

Definition at line 39 of file qpointer.h.

QPointer() [4/4]

template<class T >

template<typename X , if_convertible< X > = true>

template< class T > template< class X > QPointer< T >::QPointer ( const QPointer< X > &  other )

inlinenoexcept

Since

6.6

Conversion constructor. Constructs a new QPointer by moving or copying from other.

The moved-from QPointer is reset to nullptr.

Note

These constructors participate in overload resolution only if {X*} is convertible to {T*}.

Definition at line 43 of file qpointer.h.

Member Function Documentation

clear()

template<class T >

template< class T > void QPointer< T >::clear ( )

inline

Since

5.0

Clears this QPointer object.

See also

isNull()

Definition at line 70 of file qpointer.h.

References QWeakPointer< T >::clear().

Referenced by QDeclarativeGeoMap::~QDeclarativeGeoMap(), QDragManager::drag(), QXcbDrag::endDrag(), QQuickColorDialogImplPrivate::eyeDropperLeave(), QCocoaMenuBar::handleReparent(), QPcscSlot::processStateChange(), QMdiSubWindowPrivate::restoreFocus(), QtWaylandClient::QWaylandInputContext::setFocusObject(), QtWaylandClient::QWaylandInputMethodContext::setFocusObject(), QtWaylandClient::QWaylandInputContext::update(), and QtWaylandClient::QWaylandInputMethodContext::update().

Here is the call graph for this function:

Here is the caller graph for this function:

data()

template<class T >

template< class T > T * QPointer< T >::data ( ) const

inline

Since

4.4

Returns the pointer to the object being guarded.

Definition at line 56 of file qpointer.h.

Referenced by QtWayland::WlShellIntegration::WlShellIntegration(), QDeclarativeGeoMap::~QDeclarativeGeoMap(), QMenuPrivate::~QMenuPrivate(), QDeclarativeGeoMapQuickItem::afterChildrenChanged(), QCocoaMenuBar::cocoaWindow(), QQuick3DRepeater::componentComplete(), QDeclarativeGeoMapCopyrightNotice::connectMap(), QQuickStyleItem::control(), QGeoTileFetcherNokia::copyrightsFetched(), QQmlPreviewFileEngineHandler::create(), QWindowsSystemTrayIcon::createMenu(), QAbstractItemView::dataChanged(), QQuick3DParticleModelParticle::delegate(), QQuick3DObjectPrivate::derefSceneManager(), QDragManager::drag(), QAbstractItemViewPrivate::editor(), QQuickWidgetPrivate::ensureEngine(), QQuickItemGrabResultPrivate::ensureImageInCache(), QHostInfoResult::event(), QXcbDrag::eventFilter(), QQuickViewPrivate::execute(), QQuickWidgetPrivate::execute(), QWindowsSystemTrayIcon::formatDebug(), QGraphicsScenePrivate::gestureEventHandler(), QPointer< T >::get(), QGrabWindowSurfaceCapture::Grabber::grabFrame(), QXcbDrag::handleDrop(), QWidgetWindow::handleEnterLeaveEvent(), QXcbDrag::handleLeave(), QQuickOverlayPrivate::handleMouseEvent(), QTableViewPrivate::heightHintForIndex(), QQuickWidgetPrivate::init(), QQuickViewPrivate::init(), QDeclarativeGeoMap::initialize(), QPlaceManagerEngineNokiaV2::initializeCategories(), QQuickStyleItem::initStyleOptionBase(), QWindowsWindow::menuBar(), QtAndroidInput::mouseMove(), QtAndroidInput::mouseUp(), QtAndroidInput::mouseWheel(), QWindowsPopupMenu::notifyAboutToShow(), QWindowsPopupMenu::notifyTriggered(), QQmlDelegateModelPrivate::object(), QPointer< const QObject >::operator const QObject *(), QPointer< T >::operator*(), QPointer< T >::operator->(), QNetworkRequest::originatingObject(), QLibraryPrivate::pluginInstance(), QGuiApplicationPrivate::processWindowScreenChangedEvent(), QGuiApplicationPrivate::processWindowStateChangedEvent(), QWindowsOleDropSource::QueryContinueDrag(), QCalendarPopup::setCalendarWidget(), QQuick3DRepeater::setDelegate(), QtWaylandClient::QWaylandInputContext::setFocusObject(), QtWaylandClient::QWaylandInputMethodContext::setFocusObject(), QQuick3DRepeater::setModel(), QQuickMenuPrivate::setParentMenu(), QDeclarativeGeoMapQuickItem::setSourceItem(), QXcbDrag::startDrag(), QLibraryPrivate::unload(), QQuickTreeViewDelegatePrivate::updateIndicatorPointerHandlers(), QDeclarativeGeoMapQuickItem::updatePolish(), QGeoTileFetcherNokia::versionFetched(), QTableViewPrivate::widthHintForIndex(), QTreeViewPrivate::widthHintForIndex(), QWindowsMouseHandler::windowUnderMouse(), and QWindowsPointerHandler::windowUnderMouse().

get()

template<class T >

template< class T > T * QPointer< T >::get ( ) const

inline

Since

6.0

Same as data(). This function is provided for STL compatibility.

Definition at line 58 of file qpointer.h.

References QPointer< T >::data().

Referenced by QQnxMediaPlayer::setAudioOutput().

Here is the call graph for this function:

Here is the caller graph for this function:

isNull()

template<class T >

template< class T > bool QPointer< T >::isNull ( ) const

inline

Returns true if the referenced object has been destroyed or if there is no referenced object; otherwise returns false.

Definition at line 67 of file qpointer.h.

References QWeakPointer< T >::isNull().

Referenced by QCocoaMenuBar::~QCocoaMenuBar(), QMenuPrivate::~QMenuPrivate(), QGraphicsProxyWidgetPrivate::_q_removeWidgetSlot(), QAction::activate(), QHeaderDataProxyModel::columnCount(), QWindowsSystemTrayIcon::createMenu(), QHeaderDataProxyModel::data(), QPdfPageSelectorPrivate::documentStatusChanged(), QDragManager::drag(), QQuickWidgetPrivate::ensureEngine(), QGeoTiledMapNokia::evaluateCopyrights(), QDialog::exec(), QMenuPrivate::exec(), QQuickColorDialogImplPrivate::eyeDropperEnter(), QWidgetPrivate::handleClose(), QCocoaMenuBar::handleReparent(), QPcscSlot::hasCard(), QQuickWidgetPrivate::init(), QQuickViewPrivate::init(), QWaylandViewPrivate::markSurfaceAsDestroyed(), QNetworkReplyImplPrivate::metaDataChanged(), QApplication::notify(), QWindowsPopupMenu::notifyAboutToShow(), QWindowsPopupMenu::notifyTriggered(), QDBusConnectionPrivate::processFinishedCall(), QGuiApplicationPrivate::processSafeAreaMarginsChangedEvent(), QPcscSlot::processStateChange(), QGuiApplicationPrivate::processWindowDevicePixelRatioChangedEvent(), QWindowsOleDropSource::QueryContinueDrag(), QQuick3DObjectPrivate::refSceneManager(), QGeoTileRequestManagerPrivate::requestTiles(), QMdiSubWindowPrivate::restoreFocus(), RetryFuture::retry(), QHeaderDataProxyModel::rowCount(), QDeclarativeGeoMap::setCopyrightsVisible(), QWindowsMouseHandler::translateMouseEvent(), QWindowsPointerHandler::translateMouseEvent(), QQuickActionPrivate::trigger(), and QQmlOpenMetaObjectPrivate::Property::value().

Here is the call graph for this function:

Here is the caller graph for this function:

operator T*()

template<class T >

template< class T > QPointer< T >::operator T* ( ) const

inline

Cast operator; implements pointer semantics.

Because of this function you can pass a QPointer<T> to a function where a T* is required.

Definition at line 64 of file qpointer.h.

operator*()

template<class T >

template< class T > T & QPointer< T >::operator* ( ) const

inline

Dereference operator; implements pointer semantics.

Just use this operator as you would with a normal C++ pointer.

Definition at line 62 of file qpointer.h.

References QPointer< T >::data().

Here is the call graph for this function:

operator->()

template<class T >

template< class T > T * QPointer< T >::operator-> ( ) const

inline

Overloaded arrow operator; implements pointer semantics.

Just use this operator as you would with a normal C++ pointer.

Definition at line 60 of file qpointer.h.

References QPointer< T >::data().

Here is the call graph for this function:

operator=()

template<class T >

template< class T > QPointer< T > & QPointer< T >::operator= ( T *  p )

inline

Assignment operator.

This guarded pointer will now point to the same object that p points to.

Definition at line 53 of file qpointer.h.

swap()

template<class T >

template< class T > void QPointer< T >::swap ( QPointer< T > &  other )

inlinenoexcept

Since

5.6

Swaps the contents of this QPointer with the contents of other. This operation is very fast and never fails.

Definition at line 51 of file qpointer.h.

References other(), and QWeakPointer< T >::swap().

Here is the call graph for this function:

Friends And Related Symbol Documentation

QPointer

template<class T >

template<typename X >

template< class T > QPointer< T >::QPointer

friend

Constructs a guarded pointer with value \nullptr.

See also

isNull()

Definition at line 24 of file qpointer.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/corelib/kernel/qpointer.h
• qtbase/src/corelib/kernel/qpointer.cpp