]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \section{\class{wxObject}}\label{wxobject} |
2 | ||
fc2171bd | 3 | This is the root class of all wxWidgets classes. |
a660d684 KB |
4 | It declares a virtual destructor which ensures that |
5 | destructors get called for all derived class objects where necessary. | |
6 | ||
7 | wxObject is the hub of a dynamic object creation | |
8 | scheme, enabling a program to create instances of a class only knowing | |
9 | its string class name, and to query the class hierarchy. | |
10 | ||
11 | The class contains optional debugging versions | |
12 | of {\bf new} and {\bf delete}, which can help trace memory allocation | |
13 | and deallocation problems. | |
14 | ||
a91225b2 RR |
15 | wxObject can be used to implement \helpref{reference counted}{trefcount} objects, |
16 | such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}). | |
a660d684 KB |
17 | |
18 | \wxheading{See also} | |
19 | ||
20 | \helpref{wxClassInfo}{wxclassinfo}, \helpref{Debugging overview}{debuggingoverview},\rtfsp | |
21 | \helpref{wxObjectRefData}{wxobjectrefdata} | |
22 | ||
991ad6cd VZ |
23 | \wxheading{Derived from} |
24 | ||
25 | No base class | |
26 | ||
27 | \wxheading{Include files} | |
28 | ||
29 | <wx/object.h> | |
30 | ||
a660d684 KB |
31 | \latexignore{\rtfignore{\wxheading{Members}}} |
32 | ||
dcbd177f | 33 | \membersection{wxObject::wxObject}\label{wxobjectctor} |
a660d684 KB |
34 | |
35 | \func{}{wxObject}{\void} | |
36 | ||
eb199c51 VZ |
37 | \func{}{wxObject}{\param{const wxObject\&}{ other}} |
38 | ||
39 | Default and copy constructors. | |
a660d684 | 40 | |
dcbd177f | 41 | \membersection{wxObject::\destruct{wxObject}}\label{wxobjectdtor} |
a660d684 KB |
42 | |
43 | \func{}{wxObject}{\void} | |
44 | ||
45 | Destructor. Performs dereferencing, for those objects | |
46 | that use reference counting. | |
47 | ||
48 | \membersection{wxObject::m\_refData}\label{wxobjectmrefdata} | |
49 | ||
50 | \member{wxObjectRefData* }{m\_refData} | |
51 | ||
52 | Pointer to an object which is the object's reference-counted data. | |
53 | ||
54 | \wxheading{See also} | |
55 | ||
56 | \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref},\rtfsp | |
57 | \helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp | |
58 | \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp | |
59 | \helpref{wxObjectRefData}{wxobjectrefdata} | |
60 | ||
61 | \membersection{wxObject::Dump}\label{wxobjectdump} | |
62 | ||
63 | \func{void}{Dump}{\param{ostream\&}{ stream}} | |
64 | ||
eb199c51 | 65 | A virtual function that may be redefined by derived classes to allow dumping of |
a660d684 KB |
66 | memory states. |
67 | ||
eb199c51 VZ |
68 | This function is only defined in debug build and doesn't exist at all if |
69 | {\tt \_\_WXDEBUG\_\_} is not defined. | |
70 | ||
a660d684 KB |
71 | \wxheading{Parameters} |
72 | ||
73 | \docparam{stream}{Stream on which to output dump information.} | |
74 | ||
75 | \wxheading{Remarks} | |
76 | ||
fc2171bd | 77 | Currently wxWidgets does not define Dump for derived classes, but |
a660d684 | 78 | programmers may wish to use it for their own applications. Be sure to |
eb199c51 VZ |
79 | call the Dump member of the class's base class to allow all information to be |
80 | dumped. | |
a660d684 | 81 | |
eb199c51 VZ |
82 | The implementation of this function in wxObject just writes the class name of |
83 | the object. | |
a660d684 KB |
84 | |
85 | \membersection{wxObject::GetClassInfo}\label{wxobjectgetclassinfo} | |
86 | ||
87 | \func{wxClassInfo *}{GetClassInfo}{\void} | |
88 | ||
89 | This virtual function is redefined for every class that requires run-time | |
90 | type information, when using DECLARE\_CLASS macros. | |
91 | ||
92 | \membersection{wxObject::GetRefData}\label{wxobjectgetrefdata} | |
93 | ||
94 | \constfunc{wxObjectRefData*}{GetRefData}{\void} | |
95 | ||
96 | Returns the {\bf m\_refData} pointer. | |
97 | ||
98 | \wxheading{See also} | |
99 | ||
100 | \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp | |
101 | \helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp | |
102 | \helpref{wxObjectRefData}{wxobjectrefdata} | |
103 | ||
104 | \membersection{wxObject::IsKindOf}\label{wxobjectiskindof} | |
105 | ||
106 | \func{bool}{IsKindOf}{\param{wxClassInfo *}{info}} | |
107 | ||
108 | Determines whether this class is a subclass of (or the same class as) | |
109 | the given class. | |
110 | ||
111 | \wxheading{Parameters} | |
112 | ||
113 | \docparam{info}{A pointer to a class information object, which may be obtained | |
114 | by using the CLASSINFO macro.} | |
115 | ||
116 | \wxheading{Return value} | |
117 | ||
cc81d32f | 118 | true if the class represented by {\it info} is the same class as |
a660d684 KB |
119 | this one or is derived from it. |
120 | ||
121 | \wxheading{Example} | |
122 | ||
123 | \begin{verbatim} | |
124 | bool tmp = obj->IsKindOf(CLASSINFO(wxFrame)); | |
125 | \end{verbatim} | |
126 | ||
a3ab1c18 | 127 | \membersection{wxObject::IsSameAs}\label{wxobjectissameas} |
55ccdb93 | 128 | |
a3ab1c18 | 129 | \func{bool}{IsSameAs}{\param{const wxObject\& }{ obj}} |
55ccdb93 | 130 | |
a3ab1c18 VZ |
131 | Returns \true if this object has the same data pointer as \arg{obj}. Notice |
132 | that \true is returned if the data pointers are \NULL in both objects. | |
133 | ||
134 | This function only does a \emph{shallow} comparison, i.e. it doesn't compare | |
135 | the objects pointed to by the data pointers of these objects. | |
55ccdb93 | 136 | |
a660d684 KB |
137 | \membersection{wxObject::Ref}\label{wxobjectref} |
138 | ||
139 | \func{void}{Ref}{\param{const wxObject\& }{clone}} | |
140 | ||
141 | Makes this object refer to the data in {\it clone}. | |
142 | ||
143 | \wxheading{Parameters} | |
144 | ||
145 | \docparam{clone}{The object to `clone'.} | |
146 | ||
147 | \wxheading{Remarks} | |
148 | ||
149 | First this function calls \helpref{wxObject::UnRef}{wxobjectunref} on itself | |
150 | to decrement (and perhaps free) the data it is currently referring to. | |
151 | ||
152 | It then sets its own m\_refData to point to that of {\it clone}, and increments the reference count | |
153 | inside the data. | |
154 | ||
155 | \wxheading{See also} | |
156 | ||
157 | \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp | |
158 | \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp | |
159 | \helpref{wxObjectRefData}{wxobjectrefdata} | |
160 | ||
161 | \membersection{wxObject::SetRefData}\label{wxobjectsetrefdata} | |
162 | ||
163 | \func{void}{SetRefData}{\param{wxObjectRefData*}{ data}} | |
164 | ||
165 | Sets the {\bf m\_refData} pointer. | |
166 | ||
167 | \wxheading{See also} | |
168 | ||
169 | \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp | |
170 | \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp | |
171 | \helpref{wxObjectRefData}{wxobjectrefdata} | |
172 | ||
173 | \membersection{wxObject::UnRef}\label{wxobjectunref} | |
174 | ||
175 | \func{void}{UnRef}{\void} | |
176 | ||
177 | Decrements the reference count in the associated data, and if it is zero, deletes the data. | |
178 | The {\bf m\_refData} member is set to NULL. | |
179 | ||
180 | \wxheading{See also} | |
181 | ||
182 | \helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp | |
183 | \helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp | |
184 | \helpref{wxObjectRefData}{wxobjectrefdata} | |
185 | ||
55ccdb93 VZ |
186 | \membersection{wxObject::UnShare}\label{wxobjectunshare} |
187 | ||
188 | \func{void}{UnShare}{\void} | |
189 | ||
190 | Ensure that this object's data is not shared with any other object. | |
191 | ||
192 | if we have no | |
193 | data, it is created using CreateRefData() below, if we have shared data | |
194 | it is copied using CloneRefData(), otherwise nothing is done. | |
195 | ||
196 | ||
a660d684 KB |
197 | \membersection{wxObject::operator new}\label{wxobjectnew} |
198 | ||
199 | \func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}} | |
200 | ||
201 | The {\it new} operator is defined for debugging versions of the library only, when | |
fe26d444 | 202 | the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory allocation, allowing |
a660d684 KB |
203 | wxDebugContext operations. |
204 | ||
205 | \membersection{wxObject::operator delete}\label{wxobjectdelete} | |
206 | ||
207 | \func{void}{delete}{\param{void }{buf}} | |
208 | ||
209 | The {\it delete} operator is defined for debugging versions of the library only, when | |
fe26d444 | 210 | the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing |
a660d684 KB |
211 | wxDebugContext operations. |
212 | ||
4a11340a RR |
213 | |
214 | ||
215 | %% wxObjectRefData | |
216 | ||
a660d684 KB |
217 | \section{\class{wxObjectRefData}}\label{wxobjectrefdata} |
218 | ||
219 | This class is used to store reference-counted data. Derive classes from this to | |
220 | store your own data. When retrieving information from a {\bf wxObject}'s reference data, | |
221 | you will need to cast to your own derived class. | |
222 | ||
223 | \wxheading{Friends} | |
224 | ||
225 | \helpref{wxObject}{wxobject} | |
226 | ||
227 | \wxheading{See also} | |
228 | ||
229 | \helpref{wxObject}{wxobject} | |
230 | ||
991ad6cd VZ |
231 | \wxheading{Derived from} |
232 | ||
233 | No base class | |
234 | ||
235 | \wxheading{Include files} | |
236 | ||
237 | <wx/object.h> | |
238 | ||
a660d684 KB |
239 | \latexignore{\rtfignore{\wxheading{Members}}} |
240 | ||
a660d684 | 241 | |
dcbd177f | 242 | \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor} |
a660d684 KB |
243 | |
244 | \func{}{wxObjectRefData}{\void} | |
245 | ||
4a11340a | 246 | Default constructor. Initialises the internal reference count to 1. |
a660d684 | 247 | |
dcbd177f | 248 | \membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor} |
a660d684 KB |
249 | |
250 | \func{}{wxObjectRefData}{\void} | |
251 | ||
4a11340a RR |
252 | Destructor. It's declared {\tt protected} so that wxObjectRefData instances will never |
253 | be destroyed directly but only as result of a \helpref{DecRef}{wxobjectrefdatadecref} call. | |
a660d684 | 254 | |
a91225b2 RR |
255 | \membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount} |
256 | ||
257 | \constfunc{int}{GetRefCount}{\void} | |
258 | ||
259 | Returns the reference count associated with this shared data. | |
4a11340a RR |
260 | When this goes to zero during a \helpref{DecRef}{wxobjectrefdatadecref} call, the object |
261 | will auto-free itself. | |
262 | ||
263 | \membersection{wxObjectRefData::DecRef}\label{wxobjectrefdatadecref} | |
264 | ||
265 | \func{void}{DecRef}{\void} | |
266 | ||
267 | Decrements the reference count associated with this shared data and, if it reaches zero, | |
268 | destroys this instance of wxObjectRefData releasing its memory. | |
269 | ||
270 | Please note that after calling this function, the caller should absolutely avoid to use | |
271 | the pointer to this instance since it may not be valid anymore. | |
272 | ||
273 | \membersection{wxObjectRefData::IncRef}\label{wxobjectrefdataincref} | |
274 | ||
275 | \func{void}{IncRef}{\void} | |
276 | ||
277 | Increments the reference count associated with this shared data. | |
a660d684 | 278 |