phoenix_title wx.Bitmap

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 wx.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 wx.Bitmap functions take a type parameter, which is a value of the wx.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;

  • Mac supports PICT resources;

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

In addition, wx.Bitmap can load and save all formats that wx.Image can; see wx.Image for more info. Of course, you must have loaded the wx.Image handlers (see wx.InitAllImageHandlers and wx.Image.AddHandler ). Note that all available BitmapHandlers for a given wxWidgets port are automatically loaded at startup so you won’t need to use wx.Bitmap.AddHandler .

More on the difference between wx.Image and wx.Bitmap: wx.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, wx.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 wx.MemoryDC. By splitting the responsibilities between Image/wxBitmap 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.


class_hierarchy Class Hierarchy

Inheritance diagram for class Bitmap:

method_summary Methods Summary

__init__

Default constructor.

ConvertToDisabled

Returns disabled (dimmed) version of the bitmap.

ConvertToImage

Creates an image from a platform-dependent bitmap.

CopyFromBuffer

Copy data from a buffer object to replace the bitmap pixel data.

CopyFromIcon

Creates the bitmap from an icon.

CopyToBuffer

Copy pixel data to a buffer object. See CopyFromBuffer for buffer

Create

Creates a fresh bitmap.

CreateScaled

Create a bitmap with a scale factor, width and height are multiplied with that factor.

FromBuffer

Creates a wx.Bitmap from in-memory data. The data parameter

FromBufferAndAlpha

Creates a wx.Bitmap from in-memory data. The data and alpha

FromBufferRGBA

Creates a wx.Bitmap from in-memory data. The data parameter

FromRGBA

Creates a new empty 32-bit wx.Bitmap where every pixel has been

GetDepth

Gets the colour depth of the bitmap.

GetHandle

MSW-only method to fetch the windows handle for the bitmap.

GetHeight

Gets the height of the bitmap in pixels.

GetMask

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

GetPalette

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

GetSize

Returns the size of the bitmap in pixels.

GetSubBitmap

Returns a sub bitmap of the current one as long as the rect belongs entirely to the bitmap.

GetWidth

Gets the width of the bitmap in pixels.

IsOk

Returns True if bitmap data is present.

LoadFile

Loads a bitmap from a file or resource.

NewFromPNGData

Loads a bitmap from the memory containing image data in PNG format.

SaveFile

Saves a bitmap in the named file.

SetDepth

SetHandle

MSW-only method to set the windows handle for the bitmap.

SetHeight

SetMask

Sets the mask for this bitmap.

SetMaskColour

SetPalette

Sets the associated palette.

SetSize

Set the bitmap size (does not alter the existing native bitmap data or image size).

SetWidth

__bool__

__nonzero__


api Class API

class wx.Bitmap(GDIObject)

Possible constructors:

Bitmap()

Bitmap(bitmap)

Bitmap(bits, width, height, depth=1)

Bitmap(width, height, depth=BITMAP_SCREEN_DEPTH)

Bitmap(sz, depth=BITMAP_SCREEN_DEPTH)

Bitmap(name, type=BITMAP_TYPE_ANY)

Bitmap(img, depth=BITMAP_SCREEN_DEPTH)

Bitmap(listOfBytes)

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


Methods

__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.

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



__init__ (self, bitmap)

Copy constructor, uses reference counting.

To make a real copy, you can use:

newBitmap = oldBitmap.GetSubBitmap(
                      wx.Rect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()))
Parameters

bitmap (wx.Bitmap) –



__init__ (self, bits, width, height, depth=1)

Creates a bitmap from the given array 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 wx.Image should be used for creating colour bitmaps from static data.

Parameters
  • bits (string) – Specifies an array of pixel values.

  • width (int) – Specifies the width of the bitmap.

  • height (int) – Specifies the height of the bitmap.

  • depth (int) – Specifies the depth of the bitmap. If this is omitted, then a value of 1 (monochrome bitmap) is used.



__init__ (self, width, height, depth=BITMAP_SCREEN_DEPTH)

Creates a new bitmap.

A depth of BITMAP_SCREEN_DEPTH indicates the depth of the current screen or visual.

Some platforms only support 1 for monochrome and 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 (int) – The width of the bitmap in pixels, must be strictly positive.

  • height (int) – The height of the bitmap in pixels, must be strictly positive.

  • depth (int) – The number of bits used to represent each bitmap pixel.



__init__ (self, sz, depth=BITMAP_SCREEN_DEPTH)

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

Parameters



__init__ (self, name, type=BITMAP_TYPE_ANY)

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 (BitmapType) – 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 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

LoadFile



__init__ (self, img, depth=BITMAP_SCREEN_DEPTH)

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 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 wx.Image object.

  • depth (int) – Specifies the depth of the bitmap. If this is omitted, the display depth of the screen is used.



__init__ (self, listOfBytes)

Construct a Bitmap from a list of strings formatted as XPM data.





ConvertToDisabled(self, brightness=255)

Returns disabled (dimmed) version of the bitmap.

This method is not available when USE_IMAGE == 0 .

Parameters

brightness (int) –

Return type

wx.Bitmap

New in version 2.9.0.



ConvertToImage(self)

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.

Return type

wx.Image



CopyFromBuffer(self, data, format=BitmapBufferFormat_RGB, stride=-1)

Copy data from a buffer object to replace the bitmap pixel data. Default format is plain RGB, but other formats are now supported as well. The following symbols are used to specify the format of the bytes in the buffer:

wx.BitmapBufferFormat_RGB

A simple sequence of RGB bytes

wx.BitmapBufferFormat_RGBA

A simple sequence of RGBA bytes

wx.BitmapBufferFormat_ARGB32

A sequence of 32-bit values in native endian order, with alpha in the upper 8 bits, followed by red, green, and blue.

wx.BitmapBufferFormat_RGB32

Same as above but the alpha byte is ignored.



CopyFromIcon(self, icon)

Creates the bitmap from an icon.

Parameters

icon (wx.Icon) –

Return type

bool



CopyToBuffer(self, data, format=BitmapBufferFormat_RGB, stride=-1)

Copy pixel data to a buffer object. See CopyFromBuffer for buffer format details.



Create(self, *args, **kw)

overload Overloaded Implementations:



Create (self, width, height, depth=BITMAP_SCREEN_DEPTH)

Creates a fresh bitmap.

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

Parameters
  • width (int) – The width of the bitmap in pixels, must be strictly positive.

  • height (int) – The height of the bitmap in pixels, must be strictly positive.

  • depth (int) – The number of bits used to represent each bitmap pixel.

Return type

bool

Returns

True if the creation was successful.



Create (self, sz, depth=BITMAP_SCREEN_DEPTH)

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

Parameters
Return type

bool



Create (self, width, height, dc)

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

Parameters
  • width (int) – The width of the bitmap in pixels, must be strictly positive.

  • height (int) – The height of the bitmap in pixels, must be strictly positive.

  • dc (wx.DC) – DC from wich the scaling factor is inherited

Return type

bool

Returns

True if the creation was successful.

New in version 4.1/wxWidgets-3.1.0.





CreateScaled(self, width, height, depth, logicalScale)

Create a bitmap with a scale factor, width and height are multiplied with that factor.

Parameters
  • width (int) – The width of the bitmap in pixels, must be strictly positive.

  • height (int) – The height of the bitmap in pixels, must be strictly positive.

  • depth (int) – The number of bits used to represent each bitmap pixel.

  • logicalScale (float) – Scale factor used by the bitmap

Return type

bool

Returns

True if the creation was successful.

New in version 4.1/wxWidgets-3.1.0.



static FromBuffer(width, height, data)

Creates a wx.Bitmap from in-memory data. The data parameter must be a Python object that implements the buffer interface, such as a string, bytearray, etc. The data object is expected to contain a series of RGB bytes and be at least (width height 3) bytes long.

Unlike wx.ImageFromBuffer the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the data is made from the buffer object to the bitmap’s native pixel buffer.

Return type

wx.Bitmap



static FromBufferAndAlpha(width, height, data, alpha)

Creates a wx.Bitmap from in-memory data. The data and alpha parameters must be a Python object that implements the buffer interface, such as a string, bytearray, etc. The data object is expected to contain a series of RGB bytes and be at least (width height 3) bytes long, while the alpha object is expected to be widthheight bytes long and represents the image’s alpha channel. On Windows and Mac the RGB values will be ‘premultiplied’ by the alpha values. (The other platforms do the multiplication themselves.)

Unlike wx.ImageFromBuffer the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the data is made from the buffer object to the bitmap’s native pixel buffer.

Return type

wx.Bitmap



static FromBufferRGBA(width, height, data)

Creates a wx.Bitmap from in-memory data. The data parameter must be a Python object that implements the buffer interface, such as a string, bytearray, etc. The data object is expected to contain a series of RGBA bytes and be at least (width height 4) bytes long. On Windows and Mac the RGB values will be ‘premultiplied’ by the alpha values. (The other platforms do the multiplication themselves.)

Unlike wx.ImageFromBuffer the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the data is made from the buffer object to the bitmap’s native pixel buffer.

Return type

wx.Bitmap



static FromRGBA(width, height, red=0, green=0, blue=0, alpha=0)

Creates a new empty 32-bit wx.Bitmap where every pixel has been initialized with the given RGBA values.

Return type

wx.Bitmap



GetDepth(self)

Gets the colour depth of the bitmap.

A value of 1 indicates a monochrome bitmap.

Return type

int



GetHandle(self)

MSW-only method to fetch the windows handle for the bitmap.

Return type

long



GetHeight(self)

Gets the height of the bitmap in pixels.

Return type

int

See also

GetWidth , GetSize



GetMask(self)

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

Return type

wx.Mask

See also

SetMask , wx.Mask



GetPalette(self)

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

Return type

wx.Palette

See also

wx.Palette



GetSize(self)

Returns the size of the bitmap in pixels.

Return type

wx.Size

New in version 2.9.0.

See also

GetHeight , GetWidth



GetSubBitmap(self, 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.

Parameters

rect (wx.Rect) –

Return type

wx.Bitmap



GetWidth(self)

Gets the width of the bitmap in pixels.

Return type

int

See also

GetHeight , GetSize



IsOk(self)

Returns True if bitmap data is present.

Return type

bool



LoadFile(self, name, type=BITMAP_TYPE_ANY)

Loads a bitmap from a file or resource.

Parameters
  • name (string) – Either a filename or a Windows resource name. The meaning of name is determined by the type parameter.

  • type (BitmapType) – One of the wx.BitmapType values; see the note in the class detailed description. Note that the 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.

Return type

bool

Returns

True if the operation succeeded, False otherwise.

Note

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 GetPalette member.

See also

SaveFile



static NewFromPNGData(data, size)

Loads a bitmap from the memory containing image data in PNG format.

This helper function provides the simplest way to create a wx.Bitmap from PNG image data. On most platforms, it’s simply a wrapper around wx.Image loading functions and so requires the PNG image handler to be registered by either calling wx.InitAllImageHandlers which also registers all the other image formats or including the necessary header:

and calling

wx.Image.AddHandler(wx.PNGHandler)

in your application startup code.

However under OS X this function uses native image loading and so doesn’t require wxWidgets PNG support.

Parameters
  • data

  • size (int) –

Return type

wx.Bitmap

New in version 2.9.5.



SaveFile(self, name, type, palette=None)

Saves a bitmap in the named file.

Parameters
  • name (string) – A filename. The meaning of name is determined by the type parameter.

  • type (BitmapType) – One of the wx.BitmapType values; see the note in the class detailed description.

  • palette (wx.Palette) – An optional palette used for saving the bitmap.

Return type

bool

Returns

True if the operation succeeded, False otherwise.

Note

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

See also

LoadFile



SetDepth(self, depth)

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

Parameters

depth (int) – Bitmap depth.

Deprecated

This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.



SetHandle(self, handle)

MSW-only method to set the windows handle for the bitmap.



SetHeight(self, height)

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

Parameters

height (int) – Bitmap height in pixels.

Deprecated

This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.



SetMask(self, mask)

Sets the mask for this bitmap.

Parameters

mask (wx.Mask) –

Note

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.

See also

GetMask , wx.Mask



SetMaskColour(self, colour)


SetPalette(self, palette)

Sets the associated palette.

(Not implemented under GTK+).

Parameters

palette (wx.Palette) – The palette to set.

See also

wx.Palette



SetSize(self, size)

Set the bitmap size (does not alter the existing native bitmap data or image size).



SetWidth(self, width)

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

Parameters

width (int) – Bitmap width in pixels.

Deprecated

This function is deprecated since version 3.1.2, dimensions and depth can only be set at construction time.



__bool__(self)
Return type

int



__nonzero__(self)
Return type

int


Properties

Depth

See GetDepth and SetDepth



Handle

See GetHandle and SetHandle



Height

See GetHeight and SetHeight



Mask

See GetMask and SetMask



Palette

See GetPalette and SetPalette



Size

See GetSize and SetSize



Width

See GetWidth and SetWidth