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.
See also
Bitmaps and Icons, Supported Bitmap File Formats, wx.DC.Blit , wx.Icon, wx.Cursor, wx.MemoryDC, wx.Image, PixelData
Class Hierarchy¶
Inheritance diagram for class Bitmap:
Methods Summary¶Default constructor. |
|
Returns disabled (dimmed) version of the bitmap. |
|
Creates an image from a platform-dependent bitmap. |
|
Copy data from a buffer object to replace the bitmap pixel data. |
|
Creates the bitmap from an icon. |
|
Copy pixel data to a buffer object. See |
|
Creates a fresh bitmap. |
|
Create a bitmap with a scale factor. |
|
Create a bitmap specifying its size in DPI-independent pixels and the scale factor to use. |
|
Creates a |
|
Creates a |
|
Creates a |
|
Like |
|
Creates a new empty 32-bit |
|
Returns the size of bitmap in DPI-independent units. |
|
Gets the colour depth of the bitmap. |
|
MSW-only method to fetch the windows handle for the bitmap. |
|
Returns the height of the bitmap in physical pixels. |
|
Returns the height of the bitmap in logical pixels. |
|
Returns the size of the bitmap in logical pixels. |
|
Returns the width of the bitmap in logical pixels. |
|
Gets the associated mask (if any) which may have been loaded from a file or set for the bitmap. |
|
Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap. |
|
Returns the scale factor of this bitmap. |
|
Returns the height of the bitmap in logical pixels. |
|
Returns the size of the bitmap in logical pixels. |
|
Returns the width of the bitmap in logical pixels. |
|
Returns the size of the bitmap in physical pixels. |
|
Returns a sub bitmap of the current one as long as the rect belongs entirely to the bitmap. |
|
Returns the width of the bitmap in physical pixels. |
|
Returns |
|
Returns |
|
Loads a bitmap from a file or resource. |
|
Loads a bitmap from the memory containing image data in |
|
Rescale the given bitmap to the requested size. |
|
Remove alpha channel from the bitmap. |
|
Saves a bitmap in the named file. |
|
MSW-only method to set the windows handle for the bitmap. |
|
Sets the mask for this bitmap. |
|
Create a mask for this bitmap based on the pixels with the given colour. |
|
Sets the associated palette. |
|
Sets the bitmap scale factor. |
|
Set the bitmap size (does not alter the existing native bitmap data or image size). |
|
Enable or disable use of alpha channel in this bitmap. |
|
Properties Summary¶See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
See |
|
Class API¶
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(width, height, dc)
Bitmap(name, type=BITMAP_TYPE_ANY)
Bitmap(img, depth=BITMAP_SCREEN_DEPTH)
Bitmap(img, dc)
Bitmap(listOfBytes)
This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or colour with alpha channel support.
__init__(self, *args, **kw)¶
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()))
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.
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+.
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.
sz (wx.Size) –
depth (int) –
__init__ (self, width, height, dc)
Create a bitmap compatible with the given DC, inheriting its magnification factor.
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 which the scaling factor is inherited
New in version 4.1/wxWidgets-3.1.7: (previously available only in wxMSW and wxOSX ports).
__init__ (self, name, type=BITMAP_TYPE_ANY)
Loads a bitmap from a file or resource.
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
__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.
__init__ (self, img, dc)
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.
New in version 4.1/wxWidgets-3.1.7: (previously this constructor overload was only available in wxMSW port)
__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 .
brightness (int) –
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.
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
RGBbyteswx.BitmapBufferFormat_RGBA
A simple sequence of
RGBAbyteswx.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.
icon (wx.Icon) –
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)¶ 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.
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.
bool
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.
sz (wx.Size) –
depth (int) –
bool
Create (self, width, height, dc)
Create a bitmap compatible with the given DC, inheriting its magnification factor.
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 which the scaling factor is inherited
bool
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.
This is an older synonym for CreateWithDIPSize , use the new function in the new code.
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, see SetScaleFactor .
bool
True if the creation was successful.
New in version 4.1/wxWidgets-3.1.0.
CreateWithDIPSize(self, *args, **kw)¶ Overloaded Implementations:
CreateWithDIPSize (self, size, scale, depth=BITMAP_SCREEN_DEPTH)
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:
GetSize returns size multiplied by scale
GetDIPSize returns size
GetScaleFactor returns scale
size (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 SetScaleFactor .
depth (int) – The number of bits used to represent each bitmap pixel.
bool
True if the creation was successful.
New in version 4.1/wxWidgets-3.1.6.
CreateWithDIPSize (self, width, height, scale, 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.
width (int) –
height (int) –
scale (float) –
depth (int) –
bool
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.
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 (width height) 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.
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.
FromPNGData(data)¶Like NewFromPNGData, but with a simpler API accepting a Python
buffer-compatible object.
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.
GetDIPSize(self)¶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 CreateWithDIPSize and SetScaleFactor ) and returns its physical size divided by this scale factor.
Unlike GetLogicalSize , this function returns the same value under all platforms and so its result should not be used as window or device context coordinates.
New in version 4.1/wxWidgets-3.1.6.
GetDepth(self)¶Gets the colour depth of the bitmap.
A value of 1 indicates a monochrome bitmap.
int
GetHandle(self)¶MSW-only method to fetch the windows handle for the bitmap.
long
GetHeight(self)¶Returns the height of the bitmap in physical pixels.
int
See also
GetLogicalHeight(self)¶Returns the height of the bitmap in logical pixels.
See GetLogicalSize for more information.
float
New in version 4.1/wxWidgets-3.1.6.
See also
GetLogicalSize(self)¶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 GetSize , divided by its scale factor, as returned by GetScaleFactor , while for the other platforms, it simply returns the same thing as GetSize .
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 wx.DC coordinates, whether these pixels are the same as physical pixels, which are returned by GetSize , or not.
New in version 2.9.5.
See also
GetLogicalWidth(self)¶Returns the width of the bitmap in logical pixels.
See GetLogicalSize for more information.
float
New in version 4.1/wxWidgets-3.1.6.
See also
GetMask(self)¶Gets the associated mask (if any) which may have been loaded from a file or set for the bitmap.
GetPalette(self)¶Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap.
See also
GetScaleFactor(self)¶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 GTK3, and this function always returns 1 under the other platforms.
float
New in version 2.9.5.
See also
SetScaleFactor , GetLogicalWidth , GetLogicalHeight , GetLogicalSize
GetScaledHeight(self)¶Returns the height of the bitmap in logical pixels.
This is an older synonym for GetLogicalHeight , use the new function in the new code.
float
New in version 2.9.5.
GetScaledSize(self)¶Returns the size of the bitmap in logical pixels.
This is an older synonym for GetLogicalSize , use the new function in the new code.
New in version 2.9.5.
GetScaledWidth(self)¶Returns the width of the bitmap in logical pixels.
This is an older synonym for GetLogicalWidth , use the new function in the new code.
float
New in version 2.9.5.
GetSize(self)¶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.
New in version 2.9.0.
See also
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.
GetWidth(self)¶Returns the width of the bitmap in physical pixels.
int
See also
HasAlpha(self)¶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 wx.ALPHA_OPAQUE value. To actually examine the alpha values, the bitmap can be converted to wx.Image.
bool
IsOk(self)¶Returns True if bitmap data is present.
bool
LoadFile(self, name, type=BITMAP_TYPE_ANY)¶Loads a bitmap from a file or resource.
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.
bool
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
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
in-memory PNG image data.
data –
size (int) –
Rescale(bmp, sizeNeeded)¶Rescale the given bitmap to the requested size.
This function is just a convenient wrapper for wx.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 IMAGE_QUALITY_NEAREST used by this function, please use the wx.Image function directly instead.
Both the bitmap itself and size must be valid.
New in version 4.1/wxWidgets-3.1.6.
ResetAlpha(self)¶Remove alpha channel from the bitmap.
This is the same as calling UseAlpha with False argument.
SaveFile(self, name, type, palette=None)¶Saves a bitmap in the named file.
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.
bool
True if the operation succeeded, False otherwise.
Note
Depending on how wxWidgets has been configured, not all formats may be available.
See also
SetDepth(self, depth)¶Sets the depth member (does not affect the bitmap data).
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).
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.
SetMaskColour(self, colour)¶Create a mask for this bitmap based on the pixels with the given colour.
SetPalette(self, palette)¶Sets the associated palette.
(Not implemented under GTK+).
palette (wx.Palette) – The palette to set.
See also
SetScaleFactor(self, scale)¶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 GTK3, but not wxMSW).
When creating a new bitmap, CreateWithDIPSize can be used to specify the correct scale factor from the beginning.
scale (float) –
New in version 4.1/wxWidgets-3.1.6.
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).
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.
UseAlpha(self, use=True)¶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.
use (bool) –
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.
See also
__bool__(self)¶int
__nonzero__(self)¶int
DIPSize¶See GetDIPSize
LogicalHeight¶See GetLogicalHeight
LogicalSize¶See GetLogicalSize
LogicalWidth¶See GetLogicalWidth
Palette¶See GetPalette and SetPalette
ScaleFactor¶See GetScaleFactor and SetScaleFactor
ScaledHeight¶See GetScaledHeight
ScaledSize¶See GetScaledSize
ScaledWidth¶See GetScaledWidth