]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/object.tex
removed unused wxUSE_XXX options (patch 1759328)
[wxWidgets.git] / docs / latex / wx / object.tex
... / ...
CommitLineData
1\section{\class{wxObject}}\label{wxobject}
2
3This is the root class of all wxWidgets classes.
4It declares a virtual destructor which ensures that
5destructors get called for all derived class objects where necessary.
6
7wxObject is the hub of a dynamic object creation
8scheme, enabling a program to create instances of a class only knowing
9its string class name, and to query the class hierarchy.
10
11The class contains optional debugging versions
12of {\bf new} and {\bf delete}, which can help trace memory allocation
13and deallocation problems.
14
15wxObject can be used to implement \helpref{reference counted}{trefcount} objects,
16such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}).
17
18\wxheading{See also}
19
20\helpref{wxClassInfo}{wxclassinfo}, \helpref{Debugging overview}{debuggingoverview},\rtfsp
21\helpref{wxObjectRefData}{wxobjectrefdata}
22
23\wxheading{Derived from}
24
25No base class
26
27\wxheading{Include files}
28
29<wx/object.h>
30
31\latexignore{\rtfignore{\wxheading{Members}}}
32
33\membersection{wxObject::wxObject}\label{wxobjectctor}
34
35\func{}{wxObject}{\void}
36
37\func{}{wxObject}{\param{const wxObject\&}{ other}}
38
39Default and copy constructors.
40
41\membersection{wxObject::\destruct{wxObject}}\label{wxobjectdtor}
42
43\func{}{wxObject}{\void}
44
45Destructor. Performs dereferencing, for those objects
46that use reference counting.
47
48\membersection{wxObject::m\_refData}\label{wxobjectmrefdata}
49
50\member{wxObjectRefData* }{m\_refData}
51
52Pointer 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
65A virtual function that may be redefined by derived classes to allow dumping of
66memory states.
67
68This function is only defined in debug build and doesn't exist at all if
69{\tt \_\_WXDEBUG\_\_} is not defined.
70
71\wxheading{Parameters}
72
73\docparam{stream}{Stream on which to output dump information.}
74
75\wxheading{Remarks}
76
77Currently wxWidgets does not define Dump for derived classes, but
78programmers may wish to use it for their own applications. Be sure to
79call the Dump member of the class's base class to allow all information to be
80dumped.
81
82The implementation of this function in wxObject just writes the class name of
83the object.
84
85\membersection{wxObject::GetClassInfo}\label{wxobjectgetclassinfo}
86
87\func{wxClassInfo *}{GetClassInfo}{\void}
88
89This virtual function is redefined for every class that requires run-time
90type information, when using DECLARE\_CLASS macros.
91
92\membersection{wxObject::GetRefData}\label{wxobjectgetrefdata}
93
94\constfunc{wxObjectRefData*}{GetRefData}{\void}
95
96Returns 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
108Determines whether this class is a subclass of (or the same class as)
109the given class.
110
111\wxheading{Parameters}
112
113\docparam{info}{A pointer to a class information object, which may be obtained
114by using the CLASSINFO macro.}
115
116\wxheading{Return value}
117
118true if the class represented by {\it info} is the same class as
119this 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
127\membersection{wxObject::IsSameAs}\label{wxobjectissameas}
128
129\func{bool}{IsSameAs}{\param{const wxObject\& }{ obj}}
130
131Returns \true if this object has the same data pointer as \arg{obj}. Notice
132that \true is returned if the data pointers are \NULL in both objects.
133
134This function only does a \emph{shallow} comparison, i.e. it doesn't compare
135the objects pointed to by the data pointers of these objects.
136
137\membersection{wxObject::Ref}\label{wxobjectref}
138
139\func{void}{Ref}{\param{const wxObject\& }{clone}}
140
141Makes 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
149First this function calls \helpref{wxObject::UnRef}{wxobjectunref} on itself
150to decrement (and perhaps free) the data it is currently referring to.
151
152It then sets its own m\_refData to point to that of {\it clone}, and increments the reference count
153inside 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
165Sets 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
177Decrements the reference count in the associated data, and if it is zero, deletes the data.
178The {\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
186\membersection{wxObject::UnShare}\label{wxobjectunshare}
187
188\func{void}{UnShare}{\void}
189
190Ensure that this object's data is not shared with any other object.
191
192if we have no
193data, it is created using CreateRefData() below, if we have shared data
194it is copied using CloneRefData(), otherwise nothing is done.
195
196
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
201The {\it new} operator is defined for debugging versions of the library only, when
202the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory allocation, allowing
203wxDebugContext operations.
204
205\membersection{wxObject::operator delete}\label{wxobjectdelete}
206
207\func{void}{delete}{\param{void }{buf}}
208
209The {\it delete} operator is defined for debugging versions of the library only, when
210the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing
211wxDebugContext operations.
212
213
214
215%% wxObjectRefData
216
217\section{\class{wxObjectRefData}}\label{wxobjectrefdata}
218
219This class is used to store reference-counted data. Derive classes from this to
220store your own data. When retrieving information from a {\bf wxObject}'s reference data,
221you 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
231\wxheading{Derived from}
232
233No base class
234
235\wxheading{Include files}
236
237<wx/object.h>
238
239\latexignore{\rtfignore{\wxheading{Members}}}
240
241
242\membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}
243
244\func{}{wxObjectRefData}{\void}
245
246Default constructor. Initialises the internal reference count to 1.
247
248\membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}
249
250\func{}{wxObjectRefData}{\void}
251
252Destructor. It's declared {\tt protected} so that wxObjectRefData instances will never
253be destroyed directly but only as result of a \helpref{DecRef}{wxobjectrefdatadecref} call.
254
255\membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}
256
257\constfunc{int}{GetRefCount}{\void}
258
259Returns the reference count associated with this shared data.
260When this goes to zero during a \helpref{DecRef}{wxobjectrefdatadecref} call, the object
261will auto-free itself.
262
263\membersection{wxObjectRefData::DecRef}\label{wxobjectrefdatadecref}
264
265\func{void}{DecRef}{\void}
266
267Decrements the reference count associated with this shared data and, if it reaches zero,
268destroys this instance of wxObjectRefData releasing its memory.
269
270Please note that after calling this function, the caller should absolutely avoid to use
271the 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
277Increments the reference count associated with this shared data.
278