wxRuby Documentation Home

# Wx::Bitmap

This class encapsulates the concept of a platform-dependent bitmap,
either monochrome, colour, or colour with alpha channel (transparency)
support.

wxRuby provides two classes for handling images. Bitmap is
used for drawing upon the screen, for example using a
DeviceContext. The other class Image cannot be
drawn directly upon the screen, but supports a variety of image
manipulation functions such as rescaling, blurring, and directly
manipulating pixels.

Note that because this class wraps a platform-specific GUI resource, you
shouldn’t create instances of it until the app is running; ie until
after you have called App#main_loop or App.run.

## Derived from

GDIObject

Object

## Predefined objects

Objects:

NullBitmap

## See also

Bitmap overview,
supported bitmap file formats,
DC#blit,
Icon, Cursor, Image,
MemoryDC

## Methods

- Bitmap.new
- Bitmap.from_image
- Bitmap#clean_up_handlers
- Bitmap#convert_to_image
- Bitmap#copy_from_icon
- Bitmap#create
- Bitmap#get_depth
- Bitmap#get_height
- Bitmap#get_palette
- Bitmap#get_mask
- Bitmap#get_width
- Bitmap#get_sub_bitmap
- Bitmap#load_file
- Bitmap#is_ok
- Bitmap#save_file
- Bitmap#set_depth
- Bitmap#set_height
- Bitmap#set_mask
- Bitmap#set_palette
- Bitmap#set_width

### Bitmap.new

The two main constructors for this class are used to create a blank
bitmap, or to load a bitmap from a file. from_image
can be used to convert an Image into a bitmap.

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

Creates a new bitmap. A depth of -1 indicates the depth of the current screen
or visual. Some platforms only support 1 for monochrome and -1 for the current
colour setting.

Bitmap.new(%(arg-type)String% name, Integer type)

Loads a bitmap from a file or resource.

The following constructors are not fully supported or tested:

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

Creates a bitmap from the given data which is interpreted in platform-dependent
manner.

Bitmap.new(%(arg-type)char% bits[], Integer width, Integer height Integer depth = 1)

Creates a bitmap from an array of bits.

You should only use this function for monochrome bitmaps (depth 1) in
portable programs: in this case the bits parameter should contain an XBM
image.

For other bit depths, the behaviour is platform dependent: under Windows, the
data is passed without any changes to the underlying `CreateBitmap()` API.
Under other platforms, only monochrome bitmaps may be created using this
constructor and Image should be used for creating colour
bitmaps from static data.

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

Creates a bitmap from XPM data.

#### Parameters

- bits Specifies an array of pixel values.
- width Specifies the width of the bitmap.
- height Specifies the height of the bitmap.
- depth Specifies the depth of the bitmap. 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 type parameter.
- type May be one of the following:

BITMAP_TYPE_BMP | Load a Windows bitmap file.
BITMAP_TYPE_BMP_RESOURCE | Load a Windows bitmap resource from the executable. Windows only.
BITMAP_TYPE_PICT_RESOURCE | Load a PICT image resource from the executable. Mac OS only.
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 BMP file, BMP resource, XPM data, and XPM. Under GTK,
the available formats are BMP file, XPM data, XPM file, and PNG file.
Under Motif, the available formats are XBM data, XBM file, XPM data, XPM
file.

In addition, Bitmap can read all formats that Image can,
which currently include BITMAP_TYPE_JPEG, BITMAP_TYPE_TIF,
BITMAP_TYPE_PNG, BITMAP_TYPE_GIF, BITMAP_TYPE_PCX, and
BITMAP_TYPE_PNM. Of course, you must have Image handlers loaded. *
img Platform-independent Image object.

#### Remarks

Under Windows, type defaults to BITMAP_TYPE_BMP_RESOURCE. Under X,
type defaults to BITMAP_TYPE_XPM.

#### See also

Bitmap#load_file

### Bitmap.from_image

Bitmap.from_image(%(arg-type)Image% img, Integer depth = -1)

Creates bitmap object from the image. This has to be done
to actually display an image as you cannot draw an image directly on a window.
The resulting bitmap will use the provided colour depth (or that of the
current system if depth is -1) which entails that a colour reduction has
to take place.

When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created
on program start-up to look up colors. This ensures a very fast conversion, but
the image quality won’t be perfect (and could be better for photo images using more
sophisticated dithering algorithms).

On Windows, if there is a palette present (set with SetPalette), it will be used when
creating the Bitmap (most useful in 8-bit display mode). On other platforms,
the palette is currently ignored.

destructor()

Destroys the Bitmap object and possibly the underlying bitmap data.
Because reference counting is used, the bitmap 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 bitmap explicitly, the bitmap will be
destroyed automatically by Widgets when the application exits.

Do not delete a bitmap that is selected into a memory device context,
for example during a call to draw .

### Bitmap#convert_to_image

Image convert_to_image()

Creates an image from a platform-dependent bitmap. This preserves
mask information so that bitmaps and images can be converted back
and forth without loss in that respect.

### Bitmap#copy_from_icon

Boolean copy_from_icon(%(arg-type)Icon% icon)

Creates the bitmap from an icon.

### Bitmap#create

Boolean create(%(arg-type)Integer% width, Integer height, Integer depth = -1)

Creates a fresh bitmap. If the final argument is omitted, the display depth of
the screen is used.

Boolean create(%(arg-type)% data, Integer type, Integer width, Integer height, Integer depth = -1)

Creates a bitmap from the given data, which can be of arbitrary type.

#### Parameters

- width The width of the bitmap in pixels.
- height The height of the bitmap in pixels.
- depth The depth of the bitmap in pixels. If this is -1, the screen depth is used.
- data Data whose type depends on the value of type.
- type A bitmap type identifier – see Bitmap.new for a list
  of possible values.

#### Return value

true if the call succeeded, false otherwise.

#### Remarks

The first form works on all platforms. The portability of the second form depends on the
type of data.

#### See also

Bitmap.new

### Bitmap#draw

draw() { | device_context | … }

Allows drawing directly onto a Bitmap. Accepts a block which will be
passed a MemoryDC device context, which can be used to
draw lines, shapes and text upon a bitmap. See DC for the full
range of drawing methods that are available.

Using this call ensures that the device context is properly set up for
use before drawing starts, and disposed of when drawing is
finished. It’s recommended you use this draw method rather than
instantiating MemoryDC directly.

### Bitmap#get_depth

Integer get_depth()

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

### Bitmap#get_height

Integer get_height()

Gets the height of the bitmap in pixels.

### Bitmap#get_palette

Palette get_palette()

Gets the associated palette (if any) which may have been loaded from a file
or set for the bitmap.

#### See also

Palette

### Bitmap#get_mask

Mask get_mask()

Gets the associated mask (if any) which may have been loaded from a file
or set for the bitmap.

#### See also

Bitmap#set_mask, Mask

### Bitmap#get_width

Integer get_width()

Gets the width of the bitmap in pixels.

#### See also

Bitmap#get_height

### Bitmap#get_sub_bitmap

Bitmap get_sub_bitmap(%(arg-type)Rect% rect)

Returns a sub bitmap of the current one as long as the rect belongs entirely to
the bitmap. This function preserves bit depth and mask information.

### Bitmap#load_file

Boolean load_file(%(arg-type)String% name, BitmapType type)

Loads a bitmap 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_BMP | Load a Windows bitmap file.
BITMAP_TYPE_BMP_RESOURCE | Load a Windows bitmap resource from the executable.
BITMAP_TYPE_PICT_RESOURCE | Load a PICT image resource from the executable. Mac OS only.
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.

In addition, Bitmap can read all formats that Image can
(BITMAP_TYPE_JPEG, BITMAP_TYPE_PNG, BITMAP_TYPE_GIF, BITMAP_TYPE_PCX,
BITMAP_TYPE_PNM).

#### Return value

true if the operation succeeded, false otherwise.

#### Remarks

A palette may be associated with the bitmap if one exists (especially for
colour Windows bitmaps), and if the code supports it. You can check
if one has been created by using the get_palette member.

#### See also

Bitmap#save_file

### Bitmap#is_ok

Boolean is_ok()

Returns true if bitmap data is present.

### Bitmap#save_file

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

Saves a bitmap 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_BMP | Save a Windows bitmap file.
BITMAP_TYPE_GIF | Save a GIF bitmap file.
BITMAP_TYPE_XBM | Save an X bitmap file.
BITMAP_TYPE_XPM | Save an XPM bitmap file.

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

In addition, Bitmap can save all formats that Image can
(BITMAP_TYPE_JPEG, BITMAP_TYPE_PNG).

- palette An optional palette used for saving the bitmap.

#### 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

Bitmap#load_file

### Bitmap#set_depth

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

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

#### Parameters

- depth Bitmap depth.

### Bitmap#set_height

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

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

#### Parameters

- height Bitmap height in pixels.

### Bitmap#set_mask

set_mask(%(arg-type)Mask% mask)

Sets the mask for this bitmap.

#### Remarks

The bitmap object owns the mask once this has been called.

#### See also

Bitmap#get_mask, Mask

### Bitmap#set_palette

set_palette(%(arg-type)Palette% palette)

Sets the associated palette. (Not implemented under GTK+).

#### Parameters

- palette The palette to set.

#### See also

Palette

### Bitmap#set_width

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

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

#### Parameters

- width Bitmap width in pixels.

### Bitmap#=

“Bitmap& “:bitmap& .html operator $=$(%(arg-type)”Bitmap":bitmap.html% bitmap)

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

#### Parameters

- bitmap Bitmap to assign.

#### Return value

Returns ‘this’ object.

### Bitmap#==

Boolean operator $==$(%(arg-type)Bitmap% bitmap)

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

#### Parameters

- bitmap Bitmap to compare with ‘this’

#### Return value

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

### Bitmap#!=

Boolean operator $!=$(%(arg-type)Bitmap% bitmap)

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

#### Parameters

- bitmap Bitmap to compare with ‘this’

#### Return value

Returns true if the bitmaps were unequal, false otherwise.

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