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

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(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(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(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(char bits)

Creates a bitmap from XPM data.

Parameters

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(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(Icon icon)

Creates the bitmap from an icon.

Bitmap#create

Boolean create(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(% data,  %(arg-type)Integer type,  Integer width, 
               Integer height, 
               Integer depth = -1)

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

Parameters

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(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(String name,  BitmapType type)

Loads a bitmap from a file or resource.

Parameters

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(String name,  BitmapType type, 
                  Palette palette = nil)

Saves a bitmap in the named file.

Parameters

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).

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(Integer depth)

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

Parameters

Bitmap#set_height

set_height(Integer height)

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

Parameters

Bitmap#set_mask

set_mask(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(Palette palette)

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

Parameters

See also

Palette

Bitmap#set_width

set_width(Integer width)

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

Parameters

Bitmap#=

Bitmap&% .html operator $=$(Bitmap 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

Return value

Returns ‘this’ object.

Bitmap#==

Boolean operator $==$(Bitmap bitmap)

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

Parameters

Return value

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

Bitmap#!=

Boolean operator $!=$(Bitmap bitmap)

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

Parameters

Return value

Returns true if the bitmaps were unequal, false otherwise.

[This page automatically generated from the Textile source at Wed Sep 09 02:21:01 +0100 2009]