wxRuby Documentation Home

# Wx::Icon

An icon is a small rectangular bitmap usually used for denoting a
minimized application. It differs from a Bitmap 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 Bitmap 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

Bitmap

GDIObject

Object

## Predefined objects

Wx::NULL_ICON

## Remarks

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

Icons have different formats on different platforms. Therefore,
separate icons will usually be created for the different environments.
Platform-specific methods for creating a Icon structure are catered
for, and this is an occasion where conditional initialisation 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.

## See also

Bitmap, "Image
DC#draw_icon, Cursor

## Methods

- Icon.new
- Icon.from_bitmap
- Icon#get_depth
- Icon#get_height
- Icon#get_width
- Icon#load_file
- Icon#ok
- Icon#save_file
- Icon#set_depth
- Icon#set_height
- Icon#set_width

### Icon.new

This is the recommended constructor for icons in wxRuby

Icon.new(%(arg-type)String% name, Integer bitmap_type, Integer desiredWidth = -1, Integer desiredHeight = -1)

Loads an icon from a file or resource.

These are not currently available in wxRuby:

Icon.new(%(arg-type)% data, Integer type, Integer width, Integer height, Integer depth = -1)

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

Integer height Integer depth = 1)

Creates an icon from an array of bits.

Icon.new(%(arg-type)Integer% width, Integer height, Integer depth = -1)

Creates a new icon.

Icon.new(%(arg-type)char% bits) Icon.new(%(arg-type)char% bits)

Creates an icon from XPM data.

#### 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
  IconLocation.
- bitmap_type May be one of the following:

BITMAP_TYPE_ICO | Load a Windows icon file.
BITMAP_TYPE_ICO_RESOURCE | Load a Windows icon from the resource database.
BITMAP_TYPE_GIF | Load a GIF bitmap file.
BITMAP_TYPE_XBM | Load an X bitmap file.
BITMAP_TYPE_XPM | Load an XPM bitmap file.

The validity of these flags depends on the platform and Widgets
configuration. If all possible Widgets settings are used, the Windows
platform supports ICO file, ICO resource, XPM data, XPM file and PNG
file. Under GTK, the available formats are BMP file, XPM data, XPM file,
and PNG file. For cross-platform reliability, ensure that the second
argument specifying the type is given.

### Icon#copy_from_bitmap

Icon.from_bitmap(%(arg-type)Bitmap% bmp)

Creates a new Icon from the bitmap bmp. Under MS Windows and OS X the bitmap
must have mask colour set.

### Icon#get_depth

Integer get_depth()

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

### Icon#get_height

Integer get_height()

Gets the height of the icon in pixels.

### Icon#get_width

Integer get_width()

Gets the width of the icon in pixels.

#### See also

Icon#get_height

### Icon#load_file

Boolean load_file(%(arg-type)String% name, BitmapType 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:

BITMAP_TYPE_ICO | Load a Windows icon file.
BITMAP_TYPE_ICO_RESOURCE | Load a Windows icon from the resource database.
BITMAP_TYPE_GIF | Load a GIF bitmap file.
BITMAP_TYPE_XBM | Load an X bitmap file.
BITMAP_TYPE_XPM | Load an XPM bitmap file.

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

#### Return value

true if the operation succeeded, false otherwise.

#### See also

Icon.new

### Icon#ok

Boolean ok()

Returns true if icon data is present.

### Icon#save_file

Boolean save_file(%(arg-type)String% name, BitmapType type, Palette palette = nil)

Saves an icon in the named file.

#### Parameters

- name A filename. The meaning of name is determined by the type parameter.
- type One of the following values:

BITMAP_TYPE_ICO | Save a Windows icon file.
BITMAP_TYPE_XPM | Save an XPM bitmap file.

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

- palette An optional palette used for saving the icon.

#### Return value

true if the operation succeeded, false otherwise.

#### Remarks

Depending on how Widgets has been configured, not all formats may be available.

#### See also

Icon#load_file

### Icon#set_depth

set_depth(%(arg-type)Integer% depth)

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

#### Parameters

- depth Icon depth.

### Icon#set_height

set_height(%(arg-type)Integer% height)

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

#### Parameters

- height Icon height in pixels.

### Icon#set_width

set_width(%(arg-type)Integer% width)

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

#### Parameters

- width Icon width in pixels.

### Icon#=

“Icon& “:icon& .html operator $=$(%(arg-type)”Icon":icon.html% 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.

### Icon#==

Boolean operator $==$(%(arg-type)Icon% 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.

### Icon#!=

Boolean operator $!=$(%(arg-type)Icon% 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.

[This page automatically generated from the Textile source at 2023-06-09 00:45:26 +0000]