docs/latex/wx/icon.tex

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