From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/qguardedptr.html | 194 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 doc/html/qguardedptr.html (limited to 'doc/html/qguardedptr.html') diff --git a/doc/html/qguardedptr.html b/doc/html/qguardedptr.html new file mode 100644 index 0000000..8cf083e --- /dev/null +++ b/doc/html/qguardedptr.html @@ -0,0 +1,194 @@ + + + + + +QGuardedPtr Class + + + + + + + +

QGuardedPtr Class Reference

+ +

The QGuardedPtr class is a template class that provides guarded pointers to QObjects. +More... +

#include <qguardedptr.h> +

List of all member functions. +

Public Members

QGuardedPtr ()
QGuardedPtr ( T * p )
QGuardedPtr ( const QGuardedPtr<T> & p )
~QGuardedPtr ()
QGuardedPtr<T> & operator= ( const QGuardedPtr<T> & p )
QGuardedPtr<T> & operator= ( T * p )
bool operator== ( const QGuardedPtr<T> & p ) const
bool operator!= ( const QGuardedPtr<T> & p ) const
bool isNull () const
T * operator-> () const
T & operator* () const
operator T * () const

Detailed Description

+ + +The QGuardedPtr class is a template class that provides guarded pointers to QObjects. +

+ +

A guarded pointer, QGuardedPtr<X>, behaves like a normal C++ +pointer X*, except that it is automatically set to 0 when +the referenced object is destroyed (unlike normal C++ pointers, +which become "dangling pointers" in such cases). X 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. +

Example: +

+        QGuardedPtr<QLabel> label = new QLabel( 0, "label" );
+        label->setText( "I like guarded pointers" );
+
+        delete (QLabel*) label; // simulate somebody destroying the label
+
+        if ( label)
+            label->show();
+        else
+            qDebug("The label has been destroyed");
+

+ +

The program will output The label has been destroyed rather +than dereferencing an invalid address in label->show(). +

The functions and operators available with a QGuardedPtr 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 them 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 an X* or from another guarded pointer of the same type. You +can compare them with each other using operator==() and +operator!=(), or test for 0 with isNull(). And you can dereference +them using either the *x or the x->member notation. +

A guarded pointer will automatically cast to an X*, so you can +freely mix guarded and unguarded pointers. This means that if you +have a QGuardedPtr, 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 QGuardedPtr as a parameter; just use +normal pointers. Use a QGuardedPtr when you are storing a pointer +over time. +

Note again that class X must inherit QObject, or a compilation +or link error will result. +

Member Function Documentation

QGuardedPtr::QGuardedPtr () +

+ +

Constructs a 0 guarded pointer. +

QGuardedPtr::QGuardedPtr ( T * p ) +

+ +

Constructs a guarded pointer that points to same object as p +points to. + +

QGuardedPtr::QGuardedPtr ( const QGuardedPtr<T> & p ) +

+ +

Copy one guarded pointer from another. The constructed guarded +pointer points to the same object that p points to (which may +be 0). + +

QGuardedPtr::~QGuardedPtr () +

+ +

Destroys the guarded pointer. Just like a normal pointer, +destroying a guarded pointer does not destroy the object being +pointed to. + +

bool QGuardedPtr::isNull () const +

+ +

Returns TRUE if the referenced object has been destroyed or if +there is no referenced object; otherwise returns FALSE. + +

QGuardedPtr::operator T * () const +

+ +

Cast operator; implements pointer semantics. Because of this +function you can pass a QGuardedPtr<X> to a function where an X* +is required. + +

bool QGuardedPtr::operator!= ( const QGuardedPtr<T> & p ) const +

+ +

Inequality operator; implements pointer semantics, the negation of +operator==(). Returns TRUE if p and this guarded pointer are +not pointing to the same object; otherwise returns FALSE. + +

T & QGuardedPtr::operator* () const +

+ +

Dereference operator; implements pointer semantics. Just use this +operator as you would with a normal C++ pointer. + +

T * QGuardedPtr::operator-> () const +

+ +

Overloaded arrow operator; implements pointer semantics. Just use +this operator as you would with a normal C++ pointer. + +

QGuardedPtr<T> & QGuardedPtr::operator= ( const QGuardedPtr<T> & p ) +

+ +

Assignment operator. This guarded pointer then points to the same +object as p points to. + +

QGuardedPtr<T> & QGuardedPtr::operator= ( T * p ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Assignment operator. This guarded pointer then points to the same +object as p points to. + +

bool QGuardedPtr::operator== ( const QGuardedPtr<T> & p ) const +

+ +

Equality operator; implements traditional pointer semantics. +Returns TRUE if both p and this guarded pointer are 0, or if +both p and this pointer point to the same object; otherwise +returns FALSE. +