]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/icon.tex
don't make read-only text controls editable when enabled
[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
2fd284a4
JS
4minimized application. It differs from a wxBitmap in always
5having a mask associated with it for transparent drawing. On some platforms,
6icons and bitmaps are implemented identically, since there is no real distinction between
7a wxBitmap with a mask and an icon; and there is no specific icon format on
8some platforms (X-based applications usually standardize on XPMs for small bitmaps
9and icons). However, some platforms (such as Windows) make the distinction, so
10a separate class is provided.
a660d684 11
20e85460
JS
12\wxheading{Derived from}
13
14\helpref{wxBitmap}{wxbitmap}\\
15\helpref{wxGDIObject}{wxgdiobject}\\
16\helpref{wxObject}{wxobject}
17
18\wxheading{Include files}
19
20<wx/icon.h>
21
22\wxheading{Predefined objects}
23
24Objects:
25
26{\bf wxNullIcon}
27
a660d684
KB
28\wxheading{Remarks}
29
2fd284a4
JS
30It is usually desirable to associate a pertinent icon with a frame. Icons
31can also be used for other purposes, for example with \helpref{wxTreeCtrl}{wxtreectrl}
32and \helpref{wxListCtrl}{wxlistctrl}.
33
34Icons have different formats on different platforms.
35Therefore, separate icons will usually be created for the different
a660d684
KB
36environments. Platform-specific methods for creating a {\bf wxIcon}\rtfsp
37structure are catered for, and this is an occasion where conditional
38compilation will probably be required.
39
40Note that a new icon must be created for every time the icon is to be
2fd284a4 41used for a new window. In Windows, the icon will not be
a660d684
KB
42reloaded if it has already been used. An icon allocated to a frame will
43be deleted when the frame is deleted.
44
2fd284a4 45For more information please see \helpref{Bitmap and icon overview}{wxbitmapoverview}.
a660d684 46
a660d684
KB
47\wxheading{See also}
48
2fd284a4
JS
49\helpref{Bitmap and icon overview}{wxbitmapoverview}, \helpref{supported bitmap file formats}{supportedbitmapformats},
50\helpref{wxDC::DrawIcon}{wxdcdrawicon}, \helpref{wxCursor}{wxcursor}
a660d684
KB
51
52\latexignore{\rtfignore{\wxheading{Members}}}
53
f0e8a2d0 54\membersection{wxIcon::wxIcon}\label{wxiconctor}
a660d684
KB
55
56\func{}{wxIcon}{\void}
57
58Default constructor.
59
60\func{}{wxIcon}{\param{const wxIcon\& }{icon}}
61
1e6d9499 62Copy constructor.
a660d684 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
fa482912
JS
77\func{}{wxIcon}{\param{char**}{ bits}}
78
a660d684
KB
79\func{}{wxIcon}{\param{const char**}{ bits}}
80
81Creates an icon from XPM data.
82
0f353563 83\func{}{wxIcon}{\param{const wxString\& }{name}, \param{wxBitmapType}{ type},
f60d0f94 84 \param{int}{ desiredWidth = -1}, \param{int}{ desiredHeight = -1}}
a660d684
KB
85
86Loads an icon from a file or resource.
87
aaf7ab43
VZ
88\func{}{wxIcon}{\param{const wxIconLocation\& }{loc}}
89
90Loads an icon from the specified \helpref{location}{wxiconlocation}.
91
a660d684
KB
92\wxheading{Parameters}
93
94\docparam{bits}{Specifies an array of pixel values.}
95
96\docparam{width}{Specifies the width of the icon.}
97
98\docparam{height}{Specifies the height of the icon.}
99
f60d0f94
JS
100\docparam{desiredWidth}{Specifies the desired width of the icon. This
101parameter only has an effect in Windows (32-bit) where icon resources can contain
102several icons of different sizes.}
103
104\docparam{desiredWidth}{Specifies the desired height of the icon. This
105parameter only has an effect in Windows (32-bit) where icon resources can contain
106several icons of different sizes.}
107
a660d684
KB
108\docparam{depth}{Specifies the depth of the icon. If this is omitted, the display depth of the
109screen is used.}
110
111\docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
112Its meaning is determined by the {\it flags} parameter.}
113
aaf7ab43
VZ
114\docparam{loc}{The object describing the location of the native icon, see
115\helpref{wxIconLocation}{wxiconlocation}.}
116
a660d684
KB
117\docparam{type}{May be one of the following:
118
119\twocolwidtha{5cm}
120\begin{twocollist}
f690fb04
GT
121\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file.}
122\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO\_RESOURCE}}{Load a Windows icon from the resource database.}
123\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
124\twocolitem{\indexit{wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
125\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
126%\twocolitem{\indexit{wxBITMAP\_TYPE\_RESOURCE}}{Load a Windows resource name.}
a660d684
KB
127\end{twocollist}
128
fc2171bd
JS
129The validity of these flags depends on the platform and wxWidgets configuration.
130If all possible wxWidgets settings are used, the Windows platform supports ICO file, ICO resource,
2fd284a4
JS
131XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file.
132Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.}
a660d684
KB
133
134\wxheading{Remarks}
135
136The first form constructs an icon object with no data; an assignment or another member function such as Create
137or LoadFile must be called subsequently.
138
139The second and third forms provide copy constructors. Note that these do not copy the
140icon data, but instead a pointer to the data, keeping a reference count. They are therefore
141very efficient operations.
142
143The fourth form constructs an icon from data whose type and value depends on
144the value of the {\it type} argument.
145
146The fifth form constructs a (usually monochrome) icon from an array of pixel values, under both
147X and Windows.
148
149The sixth form constructs a new icon.
150
fc2171bd 151The seventh form constructs an icon from pixmap (XPM) data, if wxWidgets has been configured
a660d684
KB
152to incorporate this feature.
153
154To use this constructor, you must first include an XPM file. For
155example, assuming that the file {\tt mybitmap.xpm} contains an XPM array
156of character pointers called mybitmap:
157
158\begin{verbatim}
159#include "mybitmap.xpm"
160
161...
162
163wxIcon *icon = new wxIcon(mybitmap);
164\end{verbatim}
165
2fd284a4
JS
166A macro, wxICON, is available which creates an icon using an XPM
167on the appropriate platform, or an icon resource on Windows.
168
169\begin{verbatim}
170wxIcon icon(wxICON(mondrian));
171
172// Equivalent to:
173
174#if defined(__WXGTK__) || defined(__WXMOTIF__)
175wxIcon icon(mondrian_xpm);
176#endif
177
178#if defined(__WXMSW__)
179wxIcon icon("mondrian");
180#endif
181\end{verbatim}
182
a660d684
KB
183The eighth form constructs an icon from a file or resource. {\it name} can refer
184to a resource name under MS Windows, or a filename under MS Windows and X.
185
186Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_ICO\_RESOURCE.
2fd284a4 187Under X, {\it type} defaults to wxBITMAP\_TYPE\_XPM.
a660d684
KB
188
189\wxheading{See also}
190
019faef4
VS
191
192\membersection{wxIcon::CopyFromBitmap}\label{wxiconcopyfrombitmap}
193
194\func{void}{CopyFromBitmap}{\param{const wxBitmap\&}{ bmp}}
195
196Copies {\it bmp} bitmap to this icon. Under MS Windows the bitmap
197must have mask colour set.
198
199
a660d684
KB
200\helpref{wxIcon::LoadFile}{wxiconloadfile}
201
5873607e
VZ
202\perlnote{Constructors supported by wxPerl are:\par
203\begin{itemize}
204\item{Wx::Icon->new( width, height, depth = -1 )}
205\item{Wx::Icon->new( name, type, desiredWidth = -1, desiredHeight = -1 )}
d3f3e857
MB
206\item{Wx::Icon->newFromBits( bits, width, height, depth = 1 )}
207\item{Wx::Icon->newFromXPM( data )}
5873607e
VZ
208\end{itemize}
209}
210
f0e8a2d0 211\membersection{wxIcon::\destruct{wxIcon}}\label{wxicondtor}
a660d684
KB
212
213\func{}{\destruct{wxIcon}}{\void}
214
55ccdb93
VZ
215Destructor.
216See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
a660d684
KB
217
218If the application omits to delete the icon explicitly, the icon will be
fc2171bd 219destroyed automatically by wxWidgets when the application exits.
a660d684
KB
220
221Do not delete an icon that is selected into a memory device context.
222
f0e8a2d0 223\membersection{wxIcon::GetDepth}\label{wxicongetdepth}
a660d684
KB
224
225\constfunc{int}{GetDepth}{\void}
226
227Gets the colour depth of the icon. A value of 1 indicates a
228monochrome icon.
229
230\membersection{wxIcon::GetHeight}\label{wxicongetheight}
231
232\constfunc{int}{GetHeight}{\void}
233
234Gets the height of the icon in pixels.
235
236\membersection{wxIcon::GetWidth}\label{wxicongetwidth}
237
238\constfunc{int}{GetWidth}{\void}
239
240Gets the width of the icon in pixels.
241
242\wxheading{See also}
243
244\helpref{wxIcon::GetHeight}{wxicongetheight}
245
246\membersection{wxIcon::LoadFile}\label{wxiconloadfile}
247
0f353563 248\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{wxBitmapType}{ type}}
a660d684
KB
249
250Loads an icon from a file or resource.
251
252\wxheading{Parameters}
253
254\docparam{name}{Either a filename or a Windows resource name.
255The meaning of {\it name} is determined by the {\it type} parameter.}
256
257\docparam{type}{One of the following values:
258
259\twocolwidtha{5cm}
260\begin{twocollist}
261\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file.}
262\twocolitem{{\bf wxBITMAP\_TYPE\_ICO\_RESOURCE}}{Load a Windows icon from the resource database.}
263\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
264\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.}
265\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM bitmap file.}
266\end{twocollist}
267
fc2171bd 268The validity of these flags depends on the platform and wxWidgets configuration.}
a660d684
KB
269
270\wxheading{Return value}
271
cc81d32f 272true if the operation succeeded, false otherwise.
a660d684
KB
273
274\wxheading{See also}
275
f0e8a2d0 276\helpref{wxIcon::wxIcon}{wxiconctor}
a660d684 277
b7cacb43 278\membersection{wxIcon::IsOk}\label{wxiconisok}
a660d684 279
b7cacb43 280\constfunc{bool}{IsOk}{\void}
a660d684 281
cc81d32f 282Returns true if icon data is present.
a660d684
KB
283
284\begin{comment}
285\membersection{wxIcon::SaveFile}\label{wxiconsavefile}
286
0f353563 287\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{wxBitmapType}{ type}, \param{wxPalette* }{palette = NULL}}
a660d684
KB
288
289Saves an icon in the named file.
290
291\wxheading{Parameters}
292
293\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
294
295\docparam{type}{One of the following values:
296
297\twocolwidtha{5cm}
298\begin{twocollist}
299\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Save a Windows icon file.}
300%\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Save a GIF icon file.}
301%\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Save an X bitmap file.}
302\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM bitmap file.}
303\end{twocollist}
304
fc2171bd 305The validity of these flags depends on the platform and wxWidgets configuration.}
a660d684 306
5b6aa0ff 307\docparam{palette}{An optional palette used for saving the icon.}
a660d684
KB
308
309\wxheading{Return value}
310
cc81d32f 311true if the operation succeeded, false otherwise.
a660d684
KB
312
313\wxheading{Remarks}
314
fc2171bd 315Depending on how wxWidgets has been configured, not all formats may be available.
a660d684
KB
316
317\wxheading{See also}
318
319\helpref{wxIcon::LoadFile}{wxiconloadfile}
320\end{comment}
321
322\membersection{wxIcon::SetDepth}\label{wxiconsetdepth}
323
324\func{void}{SetDepth}{\param{int }{depth}}
325
326Sets the depth member (does not affect the icon data).
327
328\wxheading{Parameters}
329
330\docparam{depth}{Icon depth.}
331
332\membersection{wxIcon::SetHeight}\label{wxiconsetheight}
333
334\func{void}{SetHeight}{\param{int }{height}}
335
336Sets the height member (does not affect the icon data).
337
338\wxheading{Parameters}
339
340\docparam{height}{Icon height in pixels.}
341
f0e8a2d0 342\membersection{wxIcon::SetWidth}\label{wxiconsetwidth}
a660d684
KB
343
344\func{void}{SetWidth}{\param{int }{width}}
345
346Sets the width member (does not affect the icon data).
347
348\wxheading{Parameters}
349
350\docparam{width}{Icon width in pixels.}
351
f0e8a2d0 352\membersection{wxIcon::operator $=$}\label{wxiconassign}
a660d684
KB
353
354\func{wxIcon\& }{operator $=$}{\param{const wxIcon\& }{icon}}
355
55ccdb93 356Assignment operator, using \helpref{reference counting}{trefcount}.
a660d684
KB
357
358\wxheading{Parameters}
359
360\docparam{icon}{Icon to assign.}
361
362\wxheading{Return value}
363
364Returns 'this' object.
365
a660d684 366