]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/icon.tex
Sorry, I went and removed consts as per the style guide :-)
[wxWidgets.git] / docs / latex / wx / icon.tex
CommitLineData
a660d684
KB
1\section{\class{wxIcon}}\label{wxicon}
2
3An icon is a small rectangular bitmap usually used for denoting a
4minimized application.
5
6\wxheading{Remarks}
7
8It is optional (but desirable) to associate a
9pertinent icon with a frame. Obviously icons in X and MS Windows are
10created in a different manner, and colour icons in X are difficult
11to arrange. Therefore, separate icons will be created for the different
12environments. Platform-specific methods for creating a {\bf wxIcon}\rtfsp
13structure are catered for, and this is an occasion where conditional
14compilation will probably be required.
15
16Note that a new icon must be created for every time the icon is to be
17used for a new window. In X, this will ensure that fresh X resources
18are allocated for this frame. In MS Windows, the icon will not be
19reloaded if it has already been used. An icon allocated to a frame will
20be deleted when the frame is deleted.
21
22The following shows the conditional compilation required to define an
23icon in X and in MS Windows. The alternative is to use the string
24version of the icon constructor, which loads a file under X and a
25resource under MS Windows, but has the disadvantage of requiring the
26X icon file to be available at run-time.
27
28\begin{verbatim}
29#ifdef wx_x
30#include "aiai.xbm"
31#endif
32#ifdef wx_msw
33 wxIcon *icon = new wxIcon("aiai");
34#endif
35#ifdef wx_x
36 wxIcon *icon = new wxIcon(aiai_bits, aiai_width, aiai_height);
37#endif
38\end{verbatim}
39
40\wxheading{Derived from}
41
42\helpref{wxBitmap}{wxbitmap}\\
43\helpref{wxGDIObject}{wxgdiobject}\\
44\helpref{wxObject}{wxobject}
45
46\wxheading{See also}
47
48\helpref{wxIcon overview}{wxiconoverview}, \helpref{wxDC::DrawIcon}{wxdcdrawicon}, \helpref{wxCursor}{wxcursor}
49
50\latexignore{\rtfignore{\wxheading{Members}}}
51
52\membersection{wxIcon::wxIcon}\label{wxiconconstr}
53
54\func{}{wxIcon}{\void}
55
56Default constructor.
57
58\func{}{wxIcon}{\param{const wxIcon\& }{icon}}
59
60\func{}{wxIcon}{\param{const wxIcon* }{icon}}
61
62Copy constructors.
63
eaaa6a06 64\func{}{wxIcon}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
a660d684
KB
65
66Creates an icon from the given data, which can be of arbitrary type.
67
eaaa6a06
JS
68\func{}{wxIcon}{\param{const char}{ bits[]}, \param{int}{ width}, \param{int}{ height}\\
69 \param{int}{ depth = 1}}
a660d684
KB
70
71Creates an icon from an array of bits.
72
eaaa6a06 73\func{}{wxIcon}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
a660d684
KB
74
75Creates a new icon.
76
77\func{}{wxIcon}{\param{const char**}{ bits}}
78
79Creates an icon from XPM data.
80
eaaa6a06 81\func{}{wxIcon}{\param{const wxString\& }{name}, \param{long}{ type}}
a660d684
KB
82
83Loads an icon from a file or resource.
84
85\wxheading{Parameters}
86
87\docparam{bits}{Specifies an array of pixel values.}
88
89\docparam{width}{Specifies the width of the icon.}
90
91\docparam{height}{Specifies the height of the icon.}
92
93\docparam{depth}{Specifies the depth of the icon. If this is omitted, the display depth of the
94screen is used.}
95
96\docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
97Its meaning is determined by the {\it flags} parameter.}
98
99\docparam{type}{May be one of the following:
100
101\twocolwidtha{5cm}
102\begin{twocollist}
103\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_ICO}}}{Load a Windows icon file.}
104\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_ICO\_RESOURCE}}}{Load a Windows icon from the resource database.}
105\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
106\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XBM}}}{Load an X bitmap file.}
107\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XPM}}}{Load an XPM bitmap file.}
108%\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_RESOURCE}}}{Load a Windows resource name.}
109\end{twocollist}
110
111The validity of these flags depends on the platform and wxWindows configuration.
112If all possible wxWindows settings are used, the Windows platform supports ICO, ICO\_RESOURCE,
113XPM\_DATA, and XPM. Under X, the available formats are BMP, GIF, XBM, and XPM.}
114
115\wxheading{Remarks}
116
117The first form constructs an icon object with no data; an assignment or another member function such as Create
118or LoadFile must be called subsequently.
119
120The second and third forms provide copy constructors. Note that these do not copy the
121icon data, but instead a pointer to the data, keeping a reference count. They are therefore
122very efficient operations.
123
124The fourth form constructs an icon from data whose type and value depends on
125the value of the {\it type} argument.
126
127The fifth form constructs a (usually monochrome) icon from an array of pixel values, under both
128X and Windows.
129
130The sixth form constructs a new icon.
131
132The seventh form constructs an icon from pixmap (XPM) data, if wxWindows has been configured
133to incorporate this feature.
134
135To use this constructor, you must first include an XPM file. For
136example, assuming that the file {\tt mybitmap.xpm} contains an XPM array
137of character pointers called mybitmap:
138
139\begin{verbatim}
140#include "mybitmap.xpm"
141
142...
143
144wxIcon *icon = new wxIcon(mybitmap);
145\end{verbatim}
146
147The eighth form constructs an icon from a file or resource. {\it name} can refer
148to a resource name under MS Windows, or a filename under MS Windows and X.
149
150Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_ICO\_RESOURCE.
151Under X, {\it type} defaults to wxBITMAP\_TYPE\_XBM.
152
153\wxheading{See also}
154
155\helpref{wxIcon::LoadFile}{wxiconloadfile}
156
157\membersection{wxIcon::\destruct{wxIcon}}
158
159\func{}{\destruct{wxIcon}}{\void}
160
161Destroys the wxIcon object and possibly the underlying icon data.
162Because reference counting is used, the icon may not actually be
163destroyed at this point - only when the reference count is zero will the
164data be deleted.
165
166If the application omits to delete the icon explicitly, the icon will be
167destroyed automatically by wxWindows when the application exits.
168
169Do not delete an icon that is selected into a memory device context.
170
171\begin{comment}
172\membersection{wxIcon::Create}\label{wxiconcreate}
173
eaaa6a06 174\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
a660d684
KB
175
176Creates a fresh icon. If the final argument is omitted, the display depth of
177the screen is used.
178
eaaa6a06 179\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
a660d684
KB
180
181Creates an icon from the given data, which can be of arbitrary type.
182
183\wxheading{Parameters}
184
185\docparam{width}{The width of the icon in pixels.}
186
187\docparam{height}{The height of the icon in pixels.}
188
189\docparam{depth}{The depth of the icon in pixels. If this is -1, the screen depth is used.}
190
191\docparam{data}{Data whose type depends on the value of {\it type}.}
192
193\docparam{type}{An icon type identifier - see \helpref{wxIcon::wxIcon}{wxiconconstr} for a list
194of possible values.}
195
196\wxheading{Return value}
197
198TRUE if the call succeeded, FALSE otherwise.
199
200\wxheading{Remarks}
201
202The first form works on all platforms. The portability of the second form depends on the
203type of data.
204
205\wxheading{See also}
206
207\helpref{wxIcon::wxIcon}{wxiconconstr}
208
209\end{comment}
210
211\membersection{wxIcon::GetDepth}
212
213\constfunc{int}{GetDepth}{\void}
214
215Gets the colour depth of the icon. A value of 1 indicates a
216monochrome icon.
217
218\membersection{wxIcon::GetHeight}\label{wxicongetheight}
219
220\constfunc{int}{GetHeight}{\void}
221
222Gets the height of the icon in pixels.
223
224\membersection{wxIcon::GetWidth}\label{wxicongetwidth}
225
226\constfunc{int}{GetWidth}{\void}
227
228Gets the width of the icon in pixels.
229
230\wxheading{See also}
231
232\helpref{wxIcon::GetHeight}{wxicongetheight}
233
234\membersection{wxIcon::LoadFile}\label{wxiconloadfile}
235
eaaa6a06 236\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}
a660d684
KB
237
238Loads an icon from a file or resource.
239
240\wxheading{Parameters}
241
242\docparam{name}{Either a filename or a Windows resource name.
243The meaning of {\it name} is determined by the {\it type} parameter.}
244
245\docparam{type}{One of the following values:
246
247\twocolwidtha{5cm}
248\begin{twocollist}
249\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file.}
250\twocolitem{{\bf wxBITMAP\_TYPE\_ICO\_RESOURCE}}{Load a Windows icon from the resource database.}
251\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
252\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
253\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
254\end{twocollist}
255
256The validity of these flags depends on the platform and wxWindows configuration.}
257
258\wxheading{Return value}
259
260TRUE if the operation succeeded, FALSE otherwise.
261
262\wxheading{See also}
263
264\helpref{wxIcon::wxIcon}{wxiconconstr}
265
266\membersection{wxIcon::Ok}\label{wxiconok}
267
268\constfunc{bool}{Ok}{\void}
269
270Returns TRUE if icon data is present.
271
272\begin{comment}
273\membersection{wxIcon::SaveFile}\label{wxiconsavefile}
274
275\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}, \param{wxPalette* }{palette = NULL}}
276
277Saves an icon in the named file.
278
279\wxheading{Parameters}
280
281\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
282
283\docparam{type}{One of the following values:
284
285\twocolwidtha{5cm}
286\begin{twocollist}
287\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Save a Windows icon file.}
288%\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Save a GIF icon file.}
289%\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Save an X bitmap file.}
290\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM bitmap file.}
291\end{twocollist}
292
293The validity of these flags depends on the platform and wxWindows configuration.}
294
295\docparam{palette}{An optional palette used for saving the icon. TODO: this parameter should
296probably be eliminated; instead the app should set the palette before saving.}
297
298\wxheading{Return value}
299
300TRUE if the operation succeeded, FALSE otherwise.
301
302\wxheading{Remarks}
303
304Depending on how wxWindows has been configured, not all formats may be available.
305
306\wxheading{See also}
307
308\helpref{wxIcon::LoadFile}{wxiconloadfile}
309\end{comment}
310
311\membersection{wxIcon::SetDepth}\label{wxiconsetdepth}
312
313\func{void}{SetDepth}{\param{int }{depth}}
314
315Sets the depth member (does not affect the icon data).
316
317\wxheading{Parameters}
318
319\docparam{depth}{Icon depth.}
320
321\membersection{wxIcon::SetHeight}\label{wxiconsetheight}
322
323\func{void}{SetHeight}{\param{int }{height}}
324
325Sets the height member (does not affect the icon data).
326
327\wxheading{Parameters}
328
329\docparam{height}{Icon height in pixels.}
330
331\membersection{wxIcon::SetOk}
332
333\func{void}{SetOk}{\param{int }{isOk}}
334
335Sets the validity member (does not affect the icon data).
336
337\wxheading{Parameters}
338
339\docparam{isOk}{Validity flag.}
340
341\membersection{wxIcon::SetWidth}
342
343\func{void}{SetWidth}{\param{int }{width}}
344
345Sets the width member (does not affect the icon data).
346
347\wxheading{Parameters}
348
349\docparam{width}{Icon width in pixels.}
350
351\membersection{wxIcon::operator $=$}
352
353\func{wxIcon\& }{operator $=$}{\param{const wxIcon\& }{icon}}
354
355Assignment operator. This operator does not copy any data, but instead
356passes a pointer to the data in {\it icon} and increments a reference
357counter. It is a fast operation.
358
359\wxheading{Parameters}
360
361\docparam{icon}{Icon to assign.}
362
363\wxheading{Return value}
364
365Returns 'this' object.
366
367\membersection{wxIcon::operator $==$}
368
369\func{bool}{operator $==$}{\param{const wxIcon\& }{icon}}
370
371Equality operator. This operator tests whether the internal data pointers are
372equal (a fast test).
373
374\wxheading{Parameters}
375
376\docparam{icon}{Icon to compare with 'this'}
377
378\wxheading{Return value}
379
380Returns TRUE if the icons were effectively equal, FALSE otherwise.
381
382\membersection{wxIcon::operator $!=$}
383
384\func{bool}{operator $!=$}{\param{const wxIcon\& }{icon}}
385
386Inequality operator. This operator tests whether the internal data pointers are
387unequal (a fast test).
388
389\wxheading{Parameters}
390
391\docparam{icon}{Icon to compare with 'this'}
392
393\wxheading{Return value}
394
395Returns TRUE if the icons were unequal, FALSE otherwise.
396
397