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