1\section{\class{wxScopedPtr}}\label{wxscopedptr} 2 3This is a simple scoped smart pointer implementation that is similar to 4the \urlref{Boost}{http://www.boost.org/} smart pointers but rewritten to 5use macros instead. 6 7A smart pointer holds a pointer to an object. The memory used by the object is 8deleted when the smart pointer goes out of scope. This class is different from 9the \texttt{std::auto\_ptr<>} in so far as it doesn't provide copy constructor 10nor assignment operator. This limits what you can do with it but is much less 11surprizing than the ``destructive copy'' behaviour of the standard class. 12 13\wxheading{Example} 14 15Below is an example of using a wxWidgets scoped smart pointer and 16pointer array. 17 18\begin{verbatim} 19 class MyClass { /* ... */ }; 20 21 // declare a smart pointer to a MyClass called wxMyClassPtr 22 wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr) 23 // declare a smart pointer to an array of chars 24 wxDECLARE_SCOPED_ARRAY(char, wxCharArray) 25 26 ... 27 28 // define the first pointer class, must be complete 29 wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr) 30 // define the second pointer class 31 wxDEFINE_SCOPED_ARRAY(char, wxCharArray) 32 33 // create an object with a new pointer to MyClass 34 wxMyClassPtr theObj(new MyClass()); 35 // reset the pointer (deletes the previous one) 36 theObj.reset(new MyClass()); 37 38 // access the pointer 39 theObj->MyFunc(); 40 41 // create an object with a new array of chars 42 wxCharArray theCharObj(new char[100]); 43 44 // access the array 45 theCharObj[0] = "!"; 46\end{verbatim} 47 48\wxheading{Declaring new smart pointer types} 49 50To declare the smart pointer class \texttt{CLASSNAME} containing pointes to a 51(possibly incomplete) type \texttt{TYPE} you should use 52 53\begin{verbatim} 54 wxDECLARE_SCOPED_PTR( TYPE, // type of the values 55 CLASSNAME ); // name of the class 56\end{verbatim} 57 58And later, when \texttt{TYPE} is fully defined, you must also use 59 60\begin{verbatim} 61 wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME ); 62\end{verbatim} 63to implement the scoped pointer class. 64 65The first argument of these macro is the pointer type, the second is the name 66of the new smart pointer class being created. Below we will use wxScopedPtr to 67represent the scoped pointer class, but the user may create the class with any 68legal name. 69 70Alternatively, if you don't have to separate the point of declaration and 71definition of this class and if you accept the standard naming convention, that 72is that the scoped pointer for the class \texttt{Foo} is called 73\texttt{FooPtr}, you can use a single macro which replaces two macros above: 74 75\begin{verbatim} 76 wxDEFINE_SCOPED_PTR_TYPE( TYPE ); 77\end{verbatim} 78 79Once again, in this cass \texttt{CLASSNAME} will be \texttt{TYPEPtr}. 80 81\wxheading{Include files} 82 83<wx/ptr\_scpd.h> 84 85\wxheading{See also} 86 87\helpref{wxScopedArray}{wxscopedarray}\rtfsp 88 89\latexignore{\rtfignore{\wxheading{Members}}} 90 91\membersection{wxScopedPtr::wxScopedPtr}\label{wxscopedptrctor} 92 93\func{}{explicit wxScopedPtr}{\param{type}{ * T = NULL}} 94 95Creates the smart pointer with the given pointer or none if {\tt NULL}. On 96compilers that support it, this uses the explicit keyword. 97 98 99\membersection{wxScopedPtr::\destruct{wxScopedPtr}}\label{wxscopedptrdtor} 100 101\func{}{\destruct{wxScopedPtr}}{\void} 102 103Destructor frees the pointer help by this object if it is not {\tt NULL}. 104 105 106\membersection{wxScopedPtr::release}\label{wxscopedptrrelease} 107 108\func{T *}{release}{\void} 109 110Returns the currently hold pointer and resets the smart pointer object to 111{\tt NULL}. After a call to this function the caller is responsible for 112deleting the pointer. 113 114 115\membersection{wxScopedPtr::reset}\label{wxscopedptrreset} 116 117\func{\void}{reset}{\param{T}{ p * = NULL}} 118 119Deletes the currently held pointer and sets it to {\it p} or to NULL if no 120arguments are specified. This function does check to make sure that the 121pointer you are assigning is not the same pointer that is already stored. 122 123 124\membersection{wxScopedPtr::operator *}\label{wxscopedptrptr} 125 126\func{const T\&}{operator *}{\void} 127 128This operator works like the standard C++ pointer operator to return the object 129being pointed to by the pointer. If the pointer is NULL or invalid this will 130crash. 131 132 133\membersection{wxScopedPtr::operator -$>$}\label{wxscopedptrref} 134 135\func{const T*}{operator -$>$}{\void} % TODO 136 137This operator works like the standard C++ pointer operator to return the pointer 138in the smart pointer or NULL if it is empty. 139 140 141\membersection{wxScopedPtr::get}\label{wxscopedptrget} 142 143\func{const T*}{get}{\void} 144 145This operator gets the pointer stored in the smart pointer or returns NULL if 146there is none. 147 148 149\membersection{wxScopedPtr::swap}\label{wxscopedptrswap} 150 151\func{\void}{swap}{\param{wxScopedPtr}{ \& other}} 152 153Swap the pointer inside the smart pointer with {\it other}. The pointer being 154swapped must be of the same type (hence the same class name). 155 156 157 158 159%%%%%%% wxScopedTiedPtr %%%%%%% 160\section{\class{wxScopedTiedPtr}}\label{wxscopedtiedptr} 161 162This is a variation on the topic of \helpref{wxScopedPtr}{wxscopedptr}. This 163class is also a smart pointer but in addition it ``ties'' the pointer value to 164another variable. In other words, during the life time of this class the value 165of that variable is set to be the same as the value of the pointer itself and 166it is reset to its old value when the object is destroyed. This class is 167especially useful when converting the existing code (which may already store 168the pointers value in some variable) to the smart pointers. 169 170\wxheading{Example} 171 172\wxheading{Derives from} 173 174\helpref{wxScopedPtr}{wxscopedptr} 175 176\wxheading{Include files} 177 178<wx/ptr\_scpd.h> 179 180\latexignore{\rtfignore{\wxheading{Members}}} 181 182\membersection{wxScopedTiedPtr::wxScopedTiedPtr}\label{wxscopedtiedptrctor} 183 184\func{}{wxScopedTiedPtr}{\param{T **}{ppTie}, \param{T *}{ptr}} 185 186Constructor creates a smart pointer initialized with \arg{ptr} and stores 187\arg{ptr} in the location specified by \arg{ppTie} which must not be 188{\tt NULL}. 189 190\membersection{wxScopedTiedPtr::\destruct{wxScopedTiedPtr}}\label{wxscopedtiedptrdtor} 191 192\func{}{\destruct{wxScopedTiedPtr}}{\void} 193 194Destructor frees the pointer help by this object and restores the value stored 195at the tied location (as specified in the \helpref{constructor}{wxscopedtiedptrctor}) 196to the old value. 197 198Warning: this location may now contain an uninitialized value if it hadn't been 199initialized previously, in particular don't count on it magically being 200{\tt NULL}! 201 202 203