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