1\section{\class{wxIcon}}\label{wxicon} 2 3An icon is a small rectangular bitmap usually used for denoting a 4minimized application. It differs from a wxBitmap in always 5having a mask associated with it for transparent drawing. On some platforms, 6icons and bitmaps are implemented identically, since there is no real distinction between 7a wxBitmap with a mask and an icon; and there is no specific icon format on 8some platforms (X-based applications usually standardize on XPMs for small bitmaps 9and icons). However, some platforms (such as Windows) make the distinction, so 10a 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 24Objects: 25 26{\bf wxNullIcon} 27 28\wxheading{Remarks} 29 30It is usually desirable to associate a pertinent icon with a frame. Icons 31can also be used for other purposes, for example with \helpref{wxTreeCtrl}{wxtreectrl} 32and \helpref{wxListCtrl}{wxlistctrl}. 33 34Icons have different formats on different platforms. 35Therefore, separate icons will usually be created for the different 36environments. Platform-specific methods for creating a {\bf wxIcon}\rtfsp 37structure are catered for, and this is an occasion where conditional 38compilation will probably be required. 39 40Note that a new icon must be created for every time the icon is to be 41used for a new window. In Windows, the icon will not be 42reloaded if it has already been used. An icon allocated to a frame will 43be deleted when the frame is deleted. 44 45For 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 58Default constructor. 59 60\func{}{wxIcon}{\param{const wxIcon\& }{icon}} 61 62Copy constructor. 63 64\func{}{wxIcon}{\param{void*}{ data}, \param{int}{ type}, \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} 65 66Creates 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 71Creates an icon from an array of bits. 72 73\func{}{wxIcon}{\param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} 74 75Creates a new icon. 76 77\func{}{wxIcon}{\param{char**}{ bits}} 78 79\func{}{wxIcon}{\param{const char**}{ bits}} 80 81Creates 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 86Loads an icon from a file or resource. 87 88\func{}{wxIcon}{\param{const wxIconLocation\& }{loc}} 89 90Loads 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 101parameter only has an effect in Windows (32-bit) where icon resources can contain 102several icons of different sizes.} 103 104\docparam{desiredWidth}{Specifies the desired height of the icon. This 105parameter only has an effect in Windows (32-bit) where icon resources can contain 106several icons of different sizes.} 107 108\docparam{depth}{Specifies the depth of the icon. If this is omitted, the display depth of the 109screen is used.} 110 111\docparam{name}{This can refer to a resource name under MS Windows, or a filename under MS Windows and X. 112Its 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 129The validity of these flags depends on the platform and wxWidgets configuration. 130If all possible wxWidgets settings are used, the Windows platform supports ICO file, ICO resource, 131XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file. 132Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.} 133 134\wxheading{Remarks} 135 136The first form constructs an icon object with no data; an assignment or another member function such as Create 137or LoadFile must be called subsequently. 138 139The second and third forms provide copy constructors. Note that these do not copy the 140icon data, but instead a pointer to the data, keeping a reference count. They are therefore 141very efficient operations. 142 143The fourth form constructs an icon from data whose type and value depends on 144the value of the {\it type} argument. 145 146The fifth form constructs a (usually monochrome) icon from an array of pixel values, under both 147X and Windows. 148 149The sixth form constructs a new icon. 150 151The seventh form constructs an icon from pixmap (XPM) data, if wxWidgets has been configured 152to incorporate this feature. 153 154To use this constructor, you must first include an XPM file. For 155example, assuming that the file {\tt mybitmap.xpm} contains an XPM array 156of character pointers called mybitmap: 157 158\begin{verbatim} 159#include "mybitmap.xpm" 160 161... 162 163wxIcon *icon = new wxIcon(mybitmap); 164\end{verbatim} 165 166A macro, wxICON, is available which creates an icon using an XPM 167on the appropriate platform, or an icon resource on Windows. 168 169\begin{verbatim} 170wxIcon icon(wxICON(mondrian)); 171 172// Equivalent to: 173 174#if defined(__WXGTK__) || defined(__WXMOTIF__) 175wxIcon icon(mondrian_xpm); 176#endif 177 178#if defined(__WXMSW__) 179wxIcon icon("mondrian"); 180#endif 181\end{verbatim} 182 183The eighth form constructs an icon from a file or resource. {\it name} can refer 184to a resource name under MS Windows, or a filename under MS Windows and X. 185 186Under Windows, {\it type} defaults to wxBITMAP\_TYPE\_ICO\_RESOURCE. 187Under 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 196Copies {\it bmp} bitmap to this icon. Under MS Windows the bitmap 197must 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 215Destructor. 216See \helpref{reference-counted object destruction}{refcountdestruct} for more info. 217 218If the application omits to delete the icon explicitly, the icon will be 219destroyed automatically by wxWidgets when the application exits. 220 221Do 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 227Gets the colour depth of the icon. A value of 1 indicates a 228monochrome icon. 229 230\membersection{wxIcon::GetHeight}\label{wxicongetheight} 231 232\constfunc{int}{GetHeight}{\void} 233 234Gets the height of the icon in pixels. 235 236\membersection{wxIcon::GetWidth}\label{wxicongetwidth} 237 238\constfunc{int}{GetWidth}{\void} 239 240Gets 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 250Loads an icon from a file or resource. 251 252\wxheading{Parameters} 253 254\docparam{name}{Either a filename or a Windows resource name. 255The 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 268The validity of these flags depends on the platform and wxWidgets configuration.} 269 270\wxheading{Return value} 271 272true 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 282Returns 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 289Saves 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 305The 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 311true if the operation succeeded, false otherwise. 312 313\wxheading{Remarks} 314 315Depending 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 326Sets 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 336Sets 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 346Sets 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 356Assignment operator, using \helpref{reference counting}{trefcount}. 357 358\wxheading{Parameters} 359 360\docparam{icon}{Icon to assign.} 361 362\wxheading{Return value} 363 364Returns 'this' object. 365 366 367