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