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