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