Programming with wxIcon

A wxIcon is a small bitmap that always has a mask. Its uses include

Setting the icon for a frame or dialog
Adding icons to a wxTReeCtrl, wxListCtrl, or wxNotebook via the wxImageList class (see more information later in this chapter)
Drawing an icon on a device context with wxDC::DrawIcon

Table 10-3 summarizes the major icon functions.

Table 10-3. `wxIcon` Functions
`wxIcon`	An icon can be created given another icon, XPM data (`char**`), raw data (`char[]`), or a file name and type.
`CopyFromBitmap`	Creates the icon from a `wxBitmap`.
`GetWidth`, `GetHeight`	Returns the icon's size.
`Getdepth`	Returns the icon's depth.
`LoadFile`	Files can be loaded.
`Ok`	Returns `TRue` if the icon's data is present.

Creating a wxIcon

A wxIcon object can be created from XPM data included in the application, from a wxBitmap object, from raw data, or by loading the icon from a file, such as a transparent XPM file. wxWidgets provides the wxICON macro, which is similar to the wxBITMAP macro described earlier; the icon is loaded either from a platform-specific resource or from XPM data.

On Windows, LoadFile and the equivalent constructor will work for Windows bitmap (BMP) and icon (ICO) resources and files. If you want to load other formats, load the file into a wxBitmap and convert it to an icon.

On Mac OS X and Unix/Linux with GTK+, wxIcon has the same file loading capabilities as wxBitmap.

The following code fragment shows four different ways to create a wxIcon object.

 // Method 1: load from XPM data #include "icon1.xpm" wxIcon icon1(icon1_xpm); // Method 2: load from an ICO resource (Window and OS/2 only) wxIcon icon2(wxT("icon2")); // Method 3: load from an ICO file (Windows and OS/2 only) // You can specify the desired width since an icon may // contain multiple images. wxIcon icon3(wxT("icon3.ico"), wxBITMAP_TYPE_ICO, 16, 16); // Method 4: create from a bitmap wxIcon icon4; wxBitmap bitmap(wxT("icon4.png"), wxBITMAP_TYPE_PNG); icon4.CopyFromBitmap(bitmap);

Using wxIcon

The following code shows three different ways to use wxIcon: setting a frame icon, adding an icon to an image list, and drawing an icon on a device context.

 #include "myicon.xpm" wxIcon icon(myicon_xpm); // 1: Set a frame icon frame->SetIcon(icon); // 2: Add an icon to a wxImageList wxImageList* imageList = new wxImageList(16, 16); imageList->Add(icon); // 3: Draw the icon at (10, 10) wxClientDC dc(window); dc.DrawIcon(icon, 10, 10);

Associating an Icon with an Application

Associating an icon with an application (so the operating system can present a clickable graphic to the user) cannot be done from within the wxWidgets toolkit, and this is one of the few areas where you need to use a different technique for each platform.

On Windows, you need to add a resource script (extension .rc) to your makefile or project file and add an ICON statement to the .rc filefor example:

 aardvarkpro ICON aardvarkpro.ico #include "wx/msw/wx.rc"

Here, aardvarkpro.ico is the name of a Windows icon file with multiple resolutions and depths (typically at 48x48, 32x32 and 16x16 resolutions). When showing the icon in Windows Explorer, Windows looks alphabetically for the first resource, so you may want to prepend a few a's to your chosen resource, just to make sure it'll be found first; otherwise, you'll see an unexpected icon on the desktop or in a folder.

On the Mac, you need to prepare an application bundle containing some ICNS files. See the installation section in Chapter 20, "Perfecting Your Application," for more on bundles; the relevant sections of a bundle's Info.plist file might look like this:

   <key>CFBundleDocumentTypes</key>   <array>          <dict>                <key>CFBundleTypeExtensions</key>                <array>                         <string>pjd</string>                  </array>                  <key>CFBundleTypeIconFile</key>                  <string>dialogblocks-doc.icns</string>                  <key>CFBundleTypeName</key>                  <string>pjdfile</string>                  <key>CFBundleTypeRole</key>                  <string>Editor</string>            </dict>     </array>     <key>CFBundleIconFile</key>     <string>dialogblocks-app.icns</string> ...

The icons for the application and its document types are specified with the CFBundleIconFile and CFBundleTypeIconFile properties. You can create ICNS files with the icon editor that Apple provides. If you predominantly work on another platform, you might want to create a number of different icons in 16x16, 32x32, 48x48, and 128x128 resolutions, save them as PNGs, copy them to the Mac, and then open each file and copy and paste its contents into the appropriate icon editor location. Make sure that each PNG file has a mask that the editor can use to construct the icon.

On Linux, the GNOME and KDE environments have their own methods for providing an icon to use with the application, described briefly in Chapter 20.

Programming with wxIcon