## wxIcon

An icon is a small rectangular bitmap usually used for denoting a minimized application. It differs from a wxBitmap in always having a mask associated with it for transparent drawing. On some platforms, icons and bitmaps are implemented identically, since there is no real distinction between a wxBitmap with a mask and an icon; and there is no specific icon format on some platforms (X-based applications usually standardize on XPMs for small bitmaps and icons). However, some platforms (such as Windows) make the distinction, so a separate class is provided.

Derived from

wxBitmap
wxGDIObject
wxObject

Include files

<wx/icon.h>

Predefined objects

Objects:

wxNullIcon

Remarks

It is usually desirable to associate a pertinent icon with a frame. Icons can also be used for other purposes, for example with wxTreeCtrl and wxListCtrl.

Icons have different formats on different platforms. Therefore, separate icons will usually be created for the different environments. Platform-specific methods for creating a wxIcon structure are catered for, and this is an occasion where conditional compilation will probably be required.

Note that a new icon must be created for every time the icon is to be used for a new window. In Windows, the icon will not be reloaded if it has already been used. An icon allocated to a frame will be deleted when the frame is deleted.

For more information please see Bitmap and icon overview.

See also

Bitmap and icon overview, supported bitmap file formats, wxDC::DrawIcon, wxCursor

Members

wxIcon::wxIcon
wxIcon::CopyFromBitmap
wxIcon::~wxIcon
wxIcon::GetDepth
wxIcon::GetHeight
wxIcon::GetWidth
wxIcon::LoadFile
wxIcon::Ok
wxIcon::SetDepth
wxIcon::SetHeight
wxIcon::SetWidth
wxIcon::operator =
wxIcon::operator ==
wxIcon::operator !=

### wxIcon::wxIcon

wxIcon()

Default constructor.

wxIcon(const wxIcon& icon)

Copy constructor.

wxIcon(void* data, int type, int width, int height, int depth = -1)

Creates an icon from the given data, which can be of arbitrary type.

wxIcon(const char bits[], int width, int height
int depth = 1)

Creates an icon from an array of bits.

wxIcon(int width, int height, int depth = -1)

Creates a new icon.

wxIcon(char** bits)

wxIcon(const char** bits)

Creates an icon from XPM data.

wxIcon(const wxString& name, wxBitmapType type, int desiredWidth = -1, int desiredHeight = -1)

Loads an icon from a file or resource.

wxIcon(const wxIconLocation& loc)

Loads an icon from the specified location.

Parameters

bits

Specifies an array of pixel values.

width

Specifies the width of the icon.

height

Specifies the height of the icon.

desiredWidth

Specifies the desired width of the icon. This parameter only has an effect in Windows (32-bit) where icon resources can contain several icons of different sizes.

desiredWidth

Specifies the desired height of the icon. This parameter only has an effect in Windows (32-bit) where icon resources can contain several icons of different sizes.

depth

Specifies the depth of the icon. If this is omitted, the display depth of the screen is used.

name

This can refer to a resource name under MS Windows, or a filename under MS Windows and X. Its meaning is determined by the flags parameter.

loc

The object describing the location of the native icon, see wxIconLocation.

type

May be one of the following:

wxBITMAP_TYPE_ICO | Load a Windows icon file.
wxBITMAP_TYPE_ICO_RESOURCE | Load a Windows icon from the resource database.
wxBITMAP_TYPE_GIF | Load a GIF bitmap file.
wxBITMAP_TYPE_XBM | Load an X bitmap file.
wxBITMAP_TYPE_XPM | Load an XPM bitmap file.

The validity of these flags depends on the platform and wxWidgets configuration. If all possible wxWidgets settings are used, the Windows platform supports ICO file, ICO resource, XPM data, and XPM file. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file. Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.

Remarks

The first form constructs an icon object with no data; an assignment or another member function such as Create or LoadFile must be called subsequently.

The second and third forms provide copy constructors. Note that these do not copy the icon data, but instead a pointer to the data, keeping a reference count. They are therefore very efficient operations.

The fourth form constructs an icon from data whose type and value depends on the value of the type argument.

The fifth form constructs a (usually monochrome) icon from an array of pixel values, under both X and Windows.

The sixth form constructs a new icon.

The seventh form constructs an icon from pixmap (XPM) data, if wxWidgets has been configured to incorporate this feature.

To use this constructor, you must first include an XPM file. For example, assuming that the file `mybitmap.xpm` contains an XPM array of character pointers called mybitmap:

    #include "mybitmap.xpm"

    ...

    wxIcon *icon = new wxIcon(mybitmap);

A macro, wxICON, is available which creates an icon using an XPM on the appropriate platform, or an icon resource on Windows.

    wxIcon icon(wxICON(mondrian));

    // Equivalent to:

    #if defined(__WXGTK__) || defined(__WXMOTIF__)
    wxIcon icon(mondrian_xpm);
    #endif

    #if defined(__WXMSW__)
    wxIcon icon("mondrian");
    #endif

The eighth form constructs an icon from a file or resource. name can refer to a resource name under MS Windows, or a filename under MS Windows and X.

Under Windows, type defaults to wxBITMAP_TYPE_ICO_RESOURCE. Under X, type defaults to wxBITMAP_TYPE_XPM.

See also

### wxIcon::CopyFromBitmap

void CopyFromBitmap(const wxBitmap& bmp)

Copies bmp bitmap to this icon. Under MS Windows the bitmap must have mask colour set.

wxIcon::LoadFile

wxPerl note: Constructors supported by wxPerl are:

- Wx::Icon->new( width, height, depth = -1 )
- Wx::Icon->new( name, type, desiredWidth = -1, desiredHeight = -1 )
- Wx::Icon->newFromBits( bits, width, height, depth = 1 )
- Wx::Icon->newFromXPM( data )

### wxIcon::~wxIcon

~wxIcon()

Destroys the wxIcon object and possibly the underlying icon data. Because reference counting is used, the icon may not actually be destroyed at this point - only when the reference count is zero will the data be deleted.

If the application omits to delete the icon explicitly, the icon will be destroyed automatically by wxWidgets when the application exits.

Do not delete an icon that is selected into a memory device context.

### wxIcon::GetDepth

int GetDepth() const

Gets the colour depth of the icon. A value of 1 indicates a monochrome icon.

### wxIcon::GetHeight

int GetHeight() const

Gets the height of the icon in pixels.

### wxIcon::GetWidth

int GetWidth() const

Gets the width of the icon in pixels.

See also

wxIcon::GetHeight

### wxIcon::LoadFile

bool LoadFile(const wxString& name, wxBitmapType type)

Loads an icon from a file or resource.

Parameters

name

Either a filename or a Windows resource name. The meaning of name is determined by the type parameter.

type

One of the following values:

wxBITMAP_TYPE_ICO | Load a Windows icon file.
wxBITMAP_TYPE_ICO_RESOURCE | Load a Windows icon from the resource database.
wxBITMAP_TYPE_GIF | Load a GIF bitmap file.
wxBITMAP_TYPE_XBM | Load an X bitmap file.
wxBITMAP_TYPE_XPM | Load an XPM bitmap file.

The validity of these flags depends on the platform and wxWidgets configuration.

Return value

true if the operation succeeded, false otherwise.

See also

wxIcon::wxIcon

### wxIcon::Ok

bool Ok() const

Returns true if icon data is present.

### wxIcon::SetDepth

void SetDepth(int depth)

Sets the depth member (does not affect the icon data).

Parameters

depth

Icon depth.

### wxIcon::SetHeight

void SetHeight(int height)

Sets the height member (does not affect the icon data).

Parameters

height

Icon height in pixels.

### wxIcon::SetWidth

void SetWidth(int width)

Sets the width member (does not affect the icon data).

Parameters

width

Icon width in pixels.

### wxIcon::operator =

wxIcon& operator =(const wxIcon& icon)

Assignment operator. This operator does not copy any data, but instead passes a pointer to the data in icon and increments a reference counter. It is a fast operation.

Parameters

icon

Icon to assign.

Return value

Returns 'this' object.

### wxIcon::operator ==

bool operator ==(const wxIcon& icon)

Equality operator. This operator tests whether the internal data pointers are equal (a fast test).

Parameters

icon

Icon to compare with 'this'

Return value

Returns true if the icons were effectively equal, false otherwise.

### wxIcon::operator !=

bool operator !=(const wxIcon& icon)

Inequality operator. This operator tests whether the internal data pointers are unequal (a fast test).

Parameters

icon

Icon to compare with 'this'

Return value

Returns true if the icons were unequal, false otherwise.