Class: Wx::Bitmap

Inherits:
GDIObject show all
Defined in:
lib/wx/doc/gen/bitmap.rb

Overview

Note:

This class is untracked and should not be derived from nor instances extended!

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

If you need direct access the bitmap data instead going through drawing to it using MemoryDC you need to use the PixelData class (either NativePixelData for RGB bitmaps or AlphaPixelData for bitmaps with an additionally alpha channel). Note that many Bitmap functions take a type parameter, which is a value of the BitmapType enumeration. The validity of those values depends however on the platform where your program is running and from the wxWidgets configuration. If all possible wxWidgets settings are used:

  • WXMSW supports BMP and ICO files, BMP and ICO resources;

  • WXGTK supports any file supported by gdk-pixbuf;

  • WXOSX supports PICT resources;

  • WXX11 supports XPM files, XPM data, XBM data;

In addition, Bitmap can load and save all formats that Image can; see Image for more info. Of course, you must have loaded the Image handlers (see init_all_image_handlers and Image.add_handler). Note that all available BitmapHandlers for a given wxWidgets port are automatically loaded at startup so you won’t need to use add_handler. More on the difference between Image and Bitmap: Image is just a buffer of RGB bytes with an optional buffer for the alpha bytes. It is all generic, platform independent and image file format independent code. It includes generic code for scaling, resizing, clipping, and other manipulations of the image data. OTOH, Bitmap is intended to be a wrapper of whatever is the native image format that is quickest/easiest to draw to a DC or to be the target of the drawing operations performed on a MemoryDC. By splitting the responsibilities between Image/Bitmap like this then it’s easier to use generic code shared by all platforms and image types for generic operations and platform specific code where performance or compatibility is needed.

Category: Graphics Device Interface (GDI) Predefined objects/pointers: NULL_BITMAP

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from GDIObject

#clone, #dup

Methods inherited from Object

#clone, #dup, #is_same_as, #un_share

Constructor Details

#initialize ⇒ Wx::Bitmap #initialize(bitmap) ⇒ Wx::Bitmap #initialize(width, height, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Wx::Bitmap #initialize(sz, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Wx::Bitmap #initialize(width, height, dc) ⇒ Wx::Bitmap #initialize(name, type = Wx::BITMAP_DEFAULT_TYPE) ⇒ Wx::Bitmap #initialize(img, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Wx::Bitmap #initialize(img, dc) ⇒ Wx::Bitmap #initialize(cursor) ⇒ Wx::Bitmap

Returns a new instance of Bitmap.

Overloads:

  • #initialize ⇒ Wx::Bitmap

    Default constructor.

    Constructs a bitmap object with no data; an assignment or another member function such as #create or #load_file must be called subsequently.

  • #initialize(bitmap) ⇒ Wx::Bitmap

    Copy constructor, uses reference counting.

    To make a real copy, you can use:

    newBitmap = oldBitmap.get_sub_bitmap(
                  Wx::Rect.new(0, 0, oldBitmap.width, oldBitmap.height))

    Parameters:

  • #initialize(width, height, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Wx::Bitmap

    Creates a new bitmap.

    A depth of Wx::BITMAP_SCREEN_DEPTH indicates the depth of the current screen or visual. Some platforms only support 1 for monochrome and Wx::BITMAP_SCREEN_DEPTH for the current colour setting. A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.

    Parameters:

    • width (Integer) —

      The width of the bitmap in pixels, must be strictly positive.

    • height (Integer) —

      The height of the bitmap in pixels, must be strictly positive.

    • depth (Integer) (defaults to: Wx::BITMAP_SCREEN_DEPTH) —

      The number of bits used to represent each bitmap pixel.

  • #initialize(sz, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Wx::Bitmap

    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

    Parameters:

    • sz (Array(Integer, Integer), Wx::Size)
    • depth (Integer) (defaults to: Wx::BITMAP_SCREEN_DEPTH)
  • #initialize(width, height, dc) ⇒ Wx::Bitmap

    Create a bitmap compatible with the given DC, inheriting its magnification factor.

    Parameters:

    • width (Integer) —

      The width of the bitmap in pixels, must be strictly positive.

    • height (Integer) —

      The height of the bitmap in pixels, must be strictly positive.

    • dc (Wx::DC) —

      DC from which the scaling factor is inherited

  • #initialize(name, type = Wx::BITMAP_DEFAULT_TYPE) ⇒ Wx::Bitmap

    Loads a bitmap from a file or resource.

    Parameters:

    • name (String) —

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

    • type (Wx::BitmapType) (defaults to: Wx::BITMAP_DEFAULT_TYPE) —

      May be one of the Wx::BitmapType values and indicates which type of bitmap should be loaded. See the note in the class detailed description. Note that the Wx::BITMAP_DEFAULT_TYPE constant has different value under different wxWidgets ports. See the bitmap.h header for the value it takes for a specific port.

    See Also:

  • #initialize(img, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Wx::Bitmap

    Creates this bitmap object from the given 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 Wx::BITMAP_SCREEN_DEPTH) which entails that a colour reduction may take place. On Windows, if there is a palette present (set with SetPalette), it will be used when creating the Wx::Bitmap (most useful in 8-bit display mode). On other platforms, the palette is currently ignored.

    Parameters:

    • img (Wx::Image) —

      Platform-independent Image object.

    • depth (Integer) (defaults to: Wx::BITMAP_SCREEN_DEPTH) —

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

  • #initialize(img, dc) ⇒ Wx::Bitmap

    Creates a bitmap compatible with the given DC from the given image.

    This constructor initializes the bitmap with the data of the given image, which must be valid, but inherits the scaling factor from the given device context instead of simply using the default factor of 1.

    Parameters:

    • img (Wx::Image) —

      Platform-independent Image object.

    • dc (Wx::DC) —

      DC from which the scaling factor is inherited

  • #initialize(cursor) ⇒ Wx::Bitmap

    Creates bitmap corresponding to the given cursor.

    This can be useful to display a cursor as it cannot be drawn directly on a window.

    Parameters:



111
 
# File 'lib/wx/doc/gen/bitmap.rb', line 111

def initialize(*args) end

Class Method Details

.rescale(bmp, sizeNeeded) ⇒ void

This method returns an undefined value.

Rescale the given bitmap to the requested size.

This function is just a convenient wrapper for Image#rescale used to resize the given bmp to the requested size. If you need more control over resizing, e.g. to specify the quality option different from ImageResizeQuality::IMAGE_QUALITY_NEAREST used by this function, please use the Image function directly instead. Both the bitmap itself and size must be valid.

Parameters:



412
 
# File 'lib/wx/doc/gen/bitmap.rb', line 412

def self.rescale(bmp, sizeNeeded) end

Instance Method Details

#convert_to_disabled(brightness = 255) ⇒ Wx::Bitmap

Returns disabled (dimmed) version of the bitmap.

This method is not available when wxUSE_IMAGE == 0.

Parameters:

  • brightness (Integer) (defaults to: 255)

Returns:



118
 
# File 'lib/wx/doc/gen/bitmap.rb', line 118

def convert_to_disabled(brightness=255) end

#convert_to_image ⇒ Wx::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.

Returns:



124
 
# File 'lib/wx/doc/gen/bitmap.rb', line 124

def convert_to_image; end

#copy_from_icon(icon) ⇒ Boolean

Creates the bitmap from an icon.

Parameters:

Returns:

  • (Boolean) 


129
 
# File 'lib/wx/doc/gen/bitmap.rb', line 129

def copy_from_icon(icon) end

#create(width, height, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean #create(sz, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean #create(width, height, dc) ⇒ Boolean

Overloads:

  • #create(width, height, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean

    Creates a fresh bitmap.

    If the final argument is omitted, the display depth of the screen is used.

    true if the creation was successful.

    Parameters:

    • width (Integer) —

      The width of the bitmap in pixels, must be strictly positive.

    • height (Integer) —

      The height of the bitmap in pixels, must be strictly positive.

    • depth (Integer) (defaults to: Wx::BITMAP_SCREEN_DEPTH) —

      The number of bits used to represent each bitmap pixel.

    Returns:

    • (Boolean)
  • #create(sz, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean

    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

    Parameters:

    • sz (Array(Integer, Integer), Wx::Size)
    • depth (Integer) (defaults to: Wx::BITMAP_SCREEN_DEPTH)

    Returns:

    • (Boolean)
  • #create(width, height, dc) ⇒ Boolean

    Create a bitmap compatible with the given DC, inheriting its magnification factor.

    true if the creation was successful.

    Parameters:

    • width (Integer) —

      The width of the bitmap in pixels, must be strictly positive.

    • height (Integer) —

      The height of the bitmap in pixels, must be strictly positive.

    • dc (Wx::DC) —

      DC from which the scaling factor is inherited

    Returns:

    • (Boolean) 


154
 
# File 'lib/wx/doc/gen/bitmap.rb', line 154

def create(*args) end

#create_scaled(width, height, depth, logicalScale) ⇒ Boolean

Create a bitmap with a scale factor.

This is an older synonym for #create_with_dip_size, use the new function in the new code.

true if the creation was successful.

Parameters:

  • width (Integer) —

    The width of the bitmap in pixels, must be strictly positive.

  • height (Integer) —

    The height of the bitmap in pixels, must be strictly positive.

  • depth (Integer) —

    The number of bits used to represent each bitmap pixel.

  • logicalScale (Float) —

    Scale factor used by the bitmap, see #set_scale_factor.

Returns:

  • (Boolean) 


190
 
# File 'lib/wx/doc/gen/bitmap.rb', line 190

def create_scaled(width, height, depth, logicalScale) end

#create_with_dip_size(size, scale, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean #create_with_dip_size(width, height, scale, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean

Overloads:

  • #create_with_dip_size(size, scale, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean

    Create a bitmap specifying its size in DPI-independent pixels and the scale factor to use.

    The physical size of the bitmap is obtained by multiplying the given size by scale and rounding it to the closest integer. After using this function the following postconditions are true:

    true if the creation was successful.

    Parameters:

    • size (Array(Integer, Integer), Wx::Size) —

      The size of the bitmap in DPI-independent pixels. Both width and height must be strictly positive.

    • scale (Float) —

      Scale factor used by the bitmap, see #set_scale_factor.

    • depth (Integer) (defaults to: Wx::BITMAP_SCREEN_DEPTH) —

      The number of bits used to represent each bitmap pixel.

    Returns:

    • (Boolean)
  • #create_with_dip_size(width, height, scale, depth = Wx::BITMAP_SCREEN_DEPTH) ⇒ Boolean

    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

    Parameters:

    • width (Integer)
    • height (Integer)
    • scale (Float)
    • depth (Integer) (defaults to: Wx::BITMAP_SCREEN_DEPTH)

    Returns:

    • (Boolean) 


178
 
# File 'lib/wx/doc/gen/bitmap.rb', line 178

def create_with_dip_size(*args) end

#get_depth ⇒ Integer Also known as: depth

Gets the colour depth of the bitmap.

A value of 1 indicates a monochrome bitmap.

Returns:

  • (Integer) 


196
 
# File 'lib/wx/doc/gen/bitmap.rb', line 196

def get_depth; end

#get_dip_size ⇒ Wx::Size Also known as: dip_size

Returns the size of bitmap in DPI-independent units.

This assumes that the bitmap was created using the value of scale factor corresponding to the current DPI (see #create_with_dip_size and #set_scale_factor) and returns its physical size divided by this scale factor. Unlike #get_logical_size, this function returns the same value under all platforms and so its result should not be used as window or device context coordinates.

Returns:



204
 
# File 'lib/wx/doc/gen/bitmap.rb', line 204

def get_dip_size; end

#get_height ⇒ Integer Also known as: height

Returns the height of the bitmap in physical pixels.

Returns:

  • (Integer)

See Also:



214
 
# File 'lib/wx/doc/gen/bitmap.rb', line 214

def get_height; end

#get_logical_height ⇒ Float Also known as: logical_height

Returns the height of the bitmap in logical pixels.

See #get_logical_size for more information.

Returns:

  • (Float)

See Also:



223
 
# File 'lib/wx/doc/gen/bitmap.rb', line 223

def get_logical_height; end

#get_logical_size ⇒ Wx::Size Also known as: logical_size

Returns the size of the bitmap in logical pixels.

For the platforms using DPI-independent pixels, i.e. those where HAS_DPI_INDEPENDENT_PIXELS is defined, such as WXOSX or WXGTK 3, this function returns the physical size of the bitmap, as returned by #get_size, divided by its scale factor, as returned by #get_scale_factor, while for the other platforms, it simply returns the same thing as #get_size. This ensures that the result of this function is always expressed in the pixel coordinates appropriate for the current platform, i.e. its return value is always in logical pixels, used for window and DC coordinates, whether these pixels are the same as physical pixels, which are returned by #get_size, or not.

Returns:

See Also:



234
 
# File 'lib/wx/doc/gen/bitmap.rb', line 234

def get_logical_size; end

#get_logical_width ⇒ Float Also known as: logical_width

Returns the width of the bitmap in logical pixels.

See #get_logical_size for more information.

Returns:

  • (Float)

See Also:



243
 
# File 'lib/wx/doc/gen/bitmap.rb', line 243

def get_logical_width; end

#get_mask ⇒ Wx::Mask Also known as: mask

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

Returns:

See Also:



252
 
# File 'lib/wx/doc/gen/bitmap.rb', line 252

def get_mask; end

#get_scale_factor ⇒ Float Also known as: scale_factor

Returns the scale factor of this bitmap.

Scale factor is 1 by default, but can be greater to indicate that the size of bitmap in logical, DPI-independent pixels is smaller than its actual size in physical pixels. Bitmaps with scale factor greater than 1 must be used in high DPI to appear sharp on the screen. Note that the scale factor is only used in the ports where logical pixels are not the same as physical ones, such as WXOSX or WXGTK3, and this function always returns 1 under the other platforms.

Returns:

  • (Float)

See Also:



272
 
# File 'lib/wx/doc/gen/bitmap.rb', line 272

def get_scale_factor; end

#get_scaled_height ⇒ Float Also known as: scaled_height

Returns the height of the bitmap in logical pixels.

This is an older synonym for #get_logical_height, use the new function in the new code.

Returns:

  • (Float) 


279
 
# File 'lib/wx/doc/gen/bitmap.rb', line 279

def get_scaled_height; end

#get_scaled_size ⇒ Wx::Size Also known as: scaled_size

Returns the size of the bitmap in logical pixels.

This is an older synonym for #get_logical_size, use the new function in the new code.

Returns:



286
 
# File 'lib/wx/doc/gen/bitmap.rb', line 286

def get_scaled_size; end

#get_scaled_width ⇒ Float Also known as: scaled_width

Returns the width of the bitmap in logical pixels.

This is an older synonym for #get_logical_width, use the new function in the new code.

Returns:

  • (Float) 


293
 
# File 'lib/wx/doc/gen/bitmap.rb', line 293

def get_scaled_width; end

#get_size ⇒ Wx::Size Also known as: size

Returns the size of the bitmap in physical pixels.

The return value of this function doesn’t depend on the scale factor, it is always the physical size of the bitmap, i.e. corresponding to the actual number of pixels in it.

Returns:

See Also:



303
 
# File 'lib/wx/doc/gen/bitmap.rb', line 303

def get_size; end

#get_sub_bitmap(rect) ⇒ Wx::Bitmap Also known as: sub_bitmap

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.

Parameters:

Returns:



260
 
# File 'lib/wx/doc/gen/bitmap.rb', line 260

def get_sub_bitmap(rect) end

#get_width ⇒ Integer Also known as: width

Returns the width of the bitmap in physical pixels.

Returns:

  • (Integer)

See Also:



313
 
# File 'lib/wx/doc/gen/bitmap.rb', line 313

def get_width; end

#has_alpha ⇒ Boolean Also known as: has_alpha?

Returns true if the bitmap has an alpha channel.

Note that the fact that a bitmap has an alpha channel doesn’t necessarily mean that it has any transparency, as all of its pixels could be using ALPHA_OPAQUE value. To actually examine the alpha values, the bitmap can be converted to Image.

Returns:

  • (Boolean) 


320
 
# File 'lib/wx/doc/gen/bitmap.rb', line 320

def has_alpha; end

#is_ok ⇒ Boolean Also known as: ok?

Returns true if bitmap data is present.

Returns:

  • (Boolean) 


325
 
# File 'lib/wx/doc/gen/bitmap.rb', line 325

def is_ok; end

#load_file(name, type = Wx::BITMAP_DEFAULT_TYPE) ⇒ Boolean

Loads a bitmap from a file or resource.

true if the operation succeeded, false otherwise.

Remark:

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.

Parameters:

  • name (String) —

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

  • type (Wx::BitmapType) (defaults to: Wx::BITMAP_DEFAULT_TYPE) —

    One of the Wx::BitmapType values; see the note in the class detailed description. Note that the Wx::BITMAP_DEFAULT_TYPE constant has different value under different wxWidgets ports. See the bitmap.h header for the value it takes for a specific port.

Returns:

  • (Boolean)

See Also:



341
 
# File 'lib/wx/doc/gen/bitmap.rb', line 341

def load_file(name, type=Wx::BITMAP_DEFAULT_TYPE) end

#reset_alpha ⇒ void

This method returns an undefined value.

Remove alpha channel from the bitmap.

This is the same as calling #use_alpha with false argument.



347
 
# File 'lib/wx/doc/gen/bitmap.rb', line 347

def reset_alpha; end

#save_file(name, type, palette = nil) ⇒ Boolean

Saves a bitmap in the named file.

true if the operation succeeded, false otherwise.

Remark:

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

Parameters:

  • name (String) —

    A filename. The meaning of name is determined by the type parameter.

  • type (Wx::BitmapType) —

    One of the Wx::BitmapType values; see the note in the class detailed description.

  • palette (Wx::Palette) (defaults to: nil) —

    An optional palette used for saving the bitmap.

Returns:

  • (Boolean)

See Also:



363
 
# File 'lib/wx/doc/gen/bitmap.rb', line 363

def save_file(name, type, palette=nil) end

#set_mask(mask) ⇒ void Also known as: mask=

This method returns an undefined value.

Sets the mask for this bitmap.

Remark:

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

Note:

A mask can be set also for bitmap with an alpha channel but doing so under WXMSW is not recommended because performance of drawing such bitmap is not very good.

Parameters:

See Also:



391
 
# File 'lib/wx/doc/gen/bitmap.rb', line 391

def set_mask(mask) end

#set_scale_factor(scale) ⇒ void Also known as: scale_factor=

This method returns an undefined value.

Sets the bitmap scale factor.

This doesn’t change the bitmap actual size or its contents, but changes its scale factor, so that it appears in a smaller size when it is drawn on screen: e.g. setting scale to 2 means that the bitmap will be twice smaller (in each direction) when drawn on screen in the ports in which logical and physical pixels differ (i.e. WXOSX and WXGTK3, but not WXMSW). When creating a new bitmap, #create_with_dip_size can be used to specify the correct scale factor from the beginning.

Parameters:

  • scale (Float) 


371
 
# File 'lib/wx/doc/gen/bitmap.rb', line 371

def set_scale_factor(scale) end

#use_alpha(use = true) ⇒ Boolean

Enable or disable use of alpha channel in this bitmap.

This function is only useful for 32bpp bitmaps and changes their format to use, or not use, the fourth byte of the pixel data for the alpha channel. It currently is only implemented in WXMSW and WXOSX and simply always returns false under the other platforms. true if the operation succeeded, false otherwise, e.g. when trying to enable alpha channel support for a non-32bpp bitmap or if this operation is simply not supported by the current platform.

Parameters:

  • use (Boolean) (defaults to: true)

Returns:

  • (Boolean)

See Also:



403
 
# File 'lib/wx/doc/gen/bitmap.rb', line 403

def use_alpha(use=true) end