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