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{wxiconctor}
  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{wxBitmapType}{ type},
  84   \param{int}{ desiredWidth = -1}, \param{int}{ desiredHeight = -1}}
  85
  86 Loads an icon from a file or resource.
  87
  88 \func{}{wxIcon}{\param{const wxIconLocation\& }{loc}}
  89
  90 Loads an icon from the specified \helpref{location}{wxiconlocation}.
  91
  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
 100 \docparam{desiredWidth}{Specifies the desired width 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{desiredWidth}{Specifies the desired height of the icon. This
 105 parameter only has an effect in Windows (32-bit) where icon resources can contain
 106 several icons of different sizes.}
 107
 108 \docparam{depth}{Specifies the depth of the icon. If this is omitted, the display depth of the
 109 screen is used.}
 110
 111 \docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X.
 112 Its meaning is determined by the {\it flags} parameter.}
 113
 114 \docparam{loc}{The object describing the location of the native icon, see
 115 \helpref{wxIconLocation}{wxiconlocation}.}
 116
 117 \docparam{type}{May be one of the following:
 118
 119 \twocolwidtha{5cm}
 120 \begin{twocollist}
 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.}
 127 \end{twocollist}
 128
 129 The validity of these flags depends on the platform and wxWidgets configuration.
 130 If all possible wxWidgets settings are used, the Windows platform supports ICO file, ICO resource,
 131 XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file.
 132 Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.}
 133
 134 \wxheading{Remarks}
 135
 136 The first form constructs an icon object with no data; an assignment or another member function such as Create
 137 or LoadFile must be called subsequently.
 138
 139 The second and third forms provide copy constructors. Note that these do not copy the
 140 icon data, but instead a pointer to the data, keeping a reference count. They are therefore
 141 very efficient operations.
 142
 143 The fourth form constructs an icon from data whose type and value depends on
 144 the value of the {\it type} argument.
 145
 146 The fifth form constructs a (usually monochrome) icon from an array of pixel values, under both
 147 X and Windows.
 148
 149 The sixth form constructs a new icon.
 150
 151 The seventh form constructs an icon from pixmap (XPM) data, if wxWidgets has been configured
 152 to incorporate this feature.
 153
 154 To use this constructor, you must first include an XPM file. For
 155 example, assuming that the file {\tt mybitmap.xpm} contains an XPM array
 156 of character pointers called mybitmap:
 157
 158 \begin{verbatim}
 159 #include "mybitmap.xpm"
 160
 161 ...
 162
 163 wxIcon *icon = new wxIcon(mybitmap);
 164 \end{verbatim}
 165
 166 A macro, wxICON, is available which creates an icon using an XPM
 167 on the appropriate platform, or an icon resource on Windows.
 168
 169 \begin{verbatim}
 170 wxIcon icon(wxICON(mondrian));
 171
 172 // Equivalent to:
 173
 174 #if defined(__WXGTK__) || defined(__WXMOTIF__)
 175 wxIcon icon(mondrian_xpm);
 176 #endif
 177
 178 #if defined(__WXMSW__)
 179 wxIcon icon("mondrian");
 180 #endif
 181 \end{verbatim}
 182
 183 The eighth form constructs an icon from a file or resource. {\it name} can refer
 184 to a resource name under MS Windows, or a filename under MS Windows and X.
 185
 186 Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_ICO\_RESOURCE.
 187 Under X, {\it type} defaults to wxBITMAP\_TYPE\_XPM.
 188
 189 \wxheading{See also}
 190
 191
 192 \membersection{wxIcon::CopyFromBitmap}\label{wxiconcopyfrombitmap}
 193
 194 \func{void}{CopyFromBitmap}{\param{const wxBitmap\&}{ bmp}}
 195
 196 Copies {\it bmp} bitmap to this icon. Under MS Windows the bitmap
 197 must have mask colour set.
 198
 199
 200 \helpref{wxIcon::LoadFile}{wxiconloadfile}
 201
 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 )}
 206 \item{Wx::Icon->newFromBits( bits, width, height, depth = 1 )}
 207 \item{Wx::Icon->newFromXPM( data )}
 208 \end{itemize}
 209 }
 210
 211 \membersection{wxIcon::\destruct{wxIcon}}\label{wxicondtor}
 212
 213 \func{}{\destruct{wxIcon}}{\void}
 214
 215 Destructor.
 216 See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
 217
 218 If the application omits to delete the icon explicitly, the icon will be
 219 destroyed automatically by wxWidgets when the application exits.
 220
 221 Do not delete an icon that is selected into a memory device context.
 222
 223 \membersection{wxIcon::GetDepth}\label{wxicongetdepth}
 224
 225 \constfunc{int}{GetDepth}{\void}
 226
 227 Gets the colour depth of the icon. A value of 1 indicates a
 228 monochrome icon.
 229
 230 \membersection{wxIcon::GetHeight}\label{wxicongetheight}
 231
 232 \constfunc{int}{GetHeight}{\void}
 233
 234 Gets the height of the icon in pixels.
 235
 236 \membersection{wxIcon::GetWidth}\label{wxicongetwidth}
 237
 238 \constfunc{int}{GetWidth}{\void}
 239
 240 Gets 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
 248 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{wxBitmapType}{ type}}
 249
 250 Loads an icon from a file or resource.
 251
 252 \wxheading{Parameters}
 253
 254 \docparam{name}{Either a filename or a Windows resource name.
 255 The 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
 268 The validity of these flags depends on the platform and wxWidgets configuration.}
 269
 270 \wxheading{Return value}
 271
 272 true if the operation succeeded, false otherwise.
 273
 274 \wxheading{See also}
 275
 276 \helpref{wxIcon::wxIcon}{wxiconctor}
 277
 278 \membersection{wxIcon::IsOk}\label{wxiconisok}
 279
 280 \constfunc{bool}{IsOk}{\void}
 281
 282 Returns true if icon data is present.
 283
 284 \begin{comment}
 285 \membersection{wxIcon::SaveFile}\label{wxiconsavefile}
 286
 287 \func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{wxBitmapType}{ type}, \param{wxPalette* }{palette = NULL}}
 288
 289 Saves 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
 305 The validity of these flags depends on the platform and wxWidgets configuration.}
 306
 307 \docparam{palette}{An optional palette used for saving the icon.}
 308
 309 \wxheading{Return value}
 310
 311 true if the operation succeeded, false otherwise.
 312
 313 \wxheading{Remarks}
 314
 315 Depending on how wxWidgets has been configured, not all formats may be available.
 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
 326 Sets 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
 336 Sets the height member (does not affect the icon data).
 337
 338 \wxheading{Parameters}
 339
 340 \docparam{height}{Icon height in pixels.}
 341
 342 \membersection{wxIcon::SetWidth}\label{wxiconsetwidth}
 343
 344 \func{void}{SetWidth}{\param{int }{width}}
 345
 346 Sets the width member (does not affect the icon data).
 347
 348 \wxheading{Parameters}
 349
 350 \docparam{width}{Icon width in pixels.}
 351
 352 \membersection{wxIcon::operator $=$}\label{wxiconassign}
 353
 354 \func{wxIcon\& }{operator $=$}{\param{const wxIcon\& }{icon}}
 355
 356 Assignment operator, using \helpref{reference counting}{trefcount}.
 357
 358 \wxheading{Parameters}
 359
 360 \docparam{icon}{Icon to assign.}
 361
 362 \wxheading{Return value}
 363
 364 Returns 'this' object.
 365
 366