#include <wx/bitmap.h>

Inheritance diagram for wxBitmap:

Detailed Description

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 wxMemoryDC you need to use the wxPixelData class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData for bitmaps with an additionally alpha channel).

Note that many wxBitmap functions take a type parameter, which is a value of the wxBitmapType 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;
wxMac supports PICT resources;
wxX11 supports XPM files, XPM data, XBM data;

In addition, wxBitmap can load and save all formats that wxImage can; see wxImage for more info. Of course, you must have loaded the wxImage handlers (see wxInitAllImageHandlers() and wxImage::AddHandler). Note that all available wxBitmapHandlers for a given wxWidgets port are automatically loaded at startup so you won't need to use wxBitmap::AddHandler.

More on the difference between wxImage and wxBitmap: wxImage 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, wxBitmap 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 wxMemoryDC. By splitting the responsibilities between wxImage/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.

Library: wxCore

Category: Graphics Device Interface (GDI)

Predefined objects/pointers: wxNullBitmap

See also: Bitmaps and Icons, Supported Bitmap File Formats, wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData

Public Member Functions
	wxBitmap ()
	Default constructor. More...

	wxBitmap (const wxBitmap &bitmap)
	Copy constructor, uses reference counting. More...

	wxBitmap (const char bits[], int width, int height, int depth=1)
	Creates a bitmap from the given array bits. More...

	wxBitmap (int width, int height, int depth=wxBITMAP_SCREEN_DEPTH)
	Creates a new bitmap. More...

	wxBitmap (const wxSize &sz, int depth=wxBITMAP_SCREEN_DEPTH)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

	wxBitmap (int width, int height, const wxDC &dc)
	Create a bitmap compatible with the given DC, inheriting its magnification factor. More...

	wxBitmap (const char const bits)
	Creates a bitmap from XPM data. More...

	wxBitmap (const wxString &name, wxBitmapType type=wxBITMAP_DEFAULT_TYPE)
	Loads a bitmap from a file or resource. More...

	wxBitmap (const wxImage &img, int depth=wxBITMAP_SCREEN_DEPTH)
	Creates this bitmap object from the given image. More...

	wxBitmap (const wxImage &img, const wxDC &dc)
	Creates a bitmap compatible with the given DC from the given image. More...

	wxBitmap (const wxCursor &cursor)
	Creates bitmap corresponding to the given cursor. More...

wxBitmap	ConvertToDisabled (unsigned char brightness=255) const
	Returns disabled (dimmed) version of the bitmap. More...

virtual wxImage	ConvertToImage () const
	Creates an image from a platform-dependent bitmap. More...

virtual bool	CopyFromIcon (const wxIcon &icon)
	Creates the bitmap from an icon. More...

bool	Create (int width, int height, int depth=wxBITMAP_SCREEN_DEPTH)
	Creates a fresh bitmap. More...

bool	Create (const wxSize &sz, int depth=wxBITMAP_SCREEN_DEPTH)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

bool	Create (int width, int height, const wxDC &dc)
	Create a bitmap compatible with the given DC, inheriting its magnification factor. More...

bool	CreateWithDIPSize (const wxSize &size, double scale, int depth=wxBITMAP_SCREEN_DEPTH)
	Create a bitmap specifying its size in DPI-independent pixels and the scale factor to use. More...

bool	CreateWithDIPSize (int width, int height, double scale, int depth=wxBITMAP_SCREEN_DEPTH)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

bool	CreateWithLogicalSize (const wxSize &size, double scale, int depth=wxBITMAP_SCREEN_DEPTH)
	Create a bitmap specifying its size in logical pixels and the scale factor to use. More...

bool	CreateWithLogicalSize (int width, int height, double scale, int depth=wxBITMAP_SCREEN_DEPTH)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

bool	CreateScaled (int width, int height, int depth, double logicalScale)
	Create a bitmap with a scale factor. More...

virtual int	GetDepth () const
	Gets the colour depth of the bitmap. More...

wxSize	GetDIPSize () const
	Returns the size of bitmap in DPI-independent units. More...

virtual int	GetHeight () const
	Returns the height of the bitmap in physical pixels. More...

double	GetLogicalHeight () const
	Returns the height of the bitmap in logical pixels. More...

wxSize	GetLogicalSize () const
	Returns the size of the bitmap in logical pixels. More...

double	GetLogicalWidth () const
	Returns the width of the bitmap in logical pixels. More...

virtual wxMask *	GetMask () const
	Gets the associated mask (if any) which may have been loaded from a file or set for the bitmap. More...

virtual wxPalette *	GetPalette () const
	Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap. More...

virtual wxBitmap	GetSubBitmap (const wxRect &rect) const
	Returns a sub bitmap of the current one as long as the rect belongs entirely to the bitmap. More...

virtual double	GetScaleFactor () const
	Returns the scale factor of this bitmap. More...

double	GetScaledHeight () const
	Returns the height of the bitmap in logical pixels. More...

wxSize	GetScaledSize () const
	Returns the size of the bitmap in logical pixels. More...

double	GetScaledWidth () const
	Returns the width of the bitmap in logical pixels. More...

wxSize	GetSize () const
	Returns the size of the bitmap in physical pixels. More...

virtual int	GetWidth () const
	Returns the width of the bitmap in physical pixels. More...

bool	HasAlpha () const
	Returns true if the bitmap has an alpha channel. More...

virtual bool	IsOk () const
	Returns true if bitmap data is present. More...

virtual bool	LoadFile (const wxString &name, wxBitmapType type=wxBITMAP_DEFAULT_TYPE)
	Loads a bitmap from a file or resource. More...

void	ResetAlpha ()
	Remove alpha channel from the bitmap. More...

virtual bool	SaveFile (const wxString &name, wxBitmapType type, const wxPalette *palette=nullptr) const
	Saves a bitmap in the named file. More...

virtual void	SetDepth (int depth)

virtual void	SetHeight (int height)

virtual void	SetScaleFactor (double scale)
	Sets the bitmap scale factor. More...

virtual void	SetMask (wxMask *mask)
	Sets the mask for this bitmap. More...

virtual void	SetPalette (const wxPalette &palette)
	Sets the associated palette. More...

virtual void	SetWidth (int width)

bool	UseAlpha (bool use=true)
	Enable or disable use of alpha channel in this bitmap. More...

Public Member Functions inherited from wxGDIObject
	wxGDIObject ()
	Default constructor. More...

Public Member Functions inherited from wxObject
	wxObject ()
	Default ctor; initializes to nullptr the internal reference data. More...

	wxObject (const wxObject &other)
	Copy ctor. More...

virtual	~wxObject ()
	Destructor. More...

virtual wxClassInfo *	GetClassInfo () const
	This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...

wxObjectRefData *	GetRefData () const
	Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...

bool	IsKindOf (const wxClassInfo *info) const
	Determines whether this class is a subclass of (or the same class as) the given class. More...

bool	IsSameAs (const wxObject &obj) const
	Returns true if this object has the same data pointer as obj. More...

void	Ref (const wxObject &clone)
	Makes this object refer to the data in clone. More...

void	SetRefData (wxObjectRefData *data)
	Sets the wxObject::m_refData pointer. More...

void	UnRef ()
	Decrements the reference count in the associated data, and if it is zero, deletes the data. More...

void	UnShare ()
	This is the same of AllocExclusive() but this method is public. More...

void	operator delete (void *buf)
	The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

void *	operator new (size_t size, const wxString &filename=nullptr, int lineNum=0)
	The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

Static Public Member Functions
static void	AddHandler (wxBitmapHandler *handler)
	Adds a handler to the end of the static list of format handlers. More...

static void	CleanUpHandlers ()
	Deletes all bitmap handlers. More...

static wxBitmapHandler *	FindHandler (const wxString &name)
	Finds the handler with the given name. More...

static wxBitmapHandler *	FindHandler (const wxString &extension, wxBitmapType bitmapType)
	Finds the handler associated with the given extension and type. More...

static wxBitmapHandler *	FindHandler (wxBitmapType bitmapType)
	Finds the handler associated with the given bitmap type. More...

static wxList &	GetHandlers ()
	Returns the static list of bitmap format handlers. More...

static void	InitStandardHandlers ()
	Adds the standard bitmap format handlers, which, depending on wxWidgets configuration, can be handlers for Windows bitmap, Windows bitmap resource, and XPM. More...

static void	InsertHandler (wxBitmapHandler *handler)
	Adds a handler at the start of the static list of format handlers. More...

static wxBitmap	NewFromPNGData (const void *data, size_t size)
	Loads a bitmap from the memory containing image data in PNG format. More...

static bool	RemoveHandler (const wxString &name)
	Finds the handler with the given name, and removes it. More...

static void	Rescale (wxBitmap &bmp, const wxSize &sizeNeeded)
	Rescale the given bitmap to the requested size. More...

Additional Inherited Members
Protected Member Functions inherited from wxObject
void	AllocExclusive ()
	Ensure that this object's data is not shared with any other object. More...

virtual wxObjectRefData *	CreateRefData () const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...

virtual wxObjectRefData *	CloneRefData (const wxObjectRefData *data) const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...

Protected Attributes inherited from wxObject
wxObjectRefData *	m_refData
	Pointer to an object which is the object's reference-counted data. More...

Constructor & Destructor Documentation

◆ wxBitmap() [1/11]

wxBitmap::wxBitmap ( )

Default constructor.

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

◆ wxBitmap() [2/11]

wxBitmap::wxBitmap ( const wxBitmap & bitmap )

Copy constructor, uses reference counting.

To make a real copy, you can use:

wxBitmap newBitmap = oldBitmap.GetSubBitmap(

wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));

wxBitmap

This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or co...

Definition: bitmap.h:212

wxBitmap::GetSubBitmap

virtual wxBitmap GetSubBitmap(const wxRect &rect) const

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

wxRect

Represents a rectangle with integer coordinates.

Definition: gdicmn.h:281

◆ wxBitmap() [3/11]

wxBitmap::wxBitmap	(	const char	bits[],
		int	width,
		int	height,
		int	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 wxImage should be used for creating colour bitmaps from static 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, then a value of 1 (monochrome bitmap) is used.

wxPerl Note: In wxPerl use Wx::Bitmap->newFromBits(bits, width, height, depth).

◆ wxBitmap() [4/11]

wxBitmap::wxBitmap	(	int	width,
		int	height,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

Creates a new bitmap.

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

Some platforms only support 1 for monochrome and wxBITMAP_SCREEN_DEPTH for the current colour setting.

A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.

Parameters

width	The width of the bitmap in pixels, must be strictly positive.
height	The height of the bitmap in pixels, must be strictly positive.
depth	The number of bits used to represent each bitmap pixel.

◆ wxBitmap() [5/11]

wxBitmap::wxBitmap	(	const wxSize &	sz,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

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

◆ wxBitmap() [6/11]

wxBitmap::wxBitmap	(	int	width,
		int	height,
		const wxDC &	dc
	)

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

Parameters

width	The width of the bitmap in pixels, must be strictly positive.
height	The height of the bitmap in pixels, must be strictly positive.
dc	DC from which the scaling factor is inherited

Since: 3.1.7 (previously available only in wxMSW and wxOSX ports).

◆ wxBitmap() [7/11]

wxBitmap::wxBitmap ( const char *const * bits )

Creates a bitmap from XPM data.

wxPerl Note: In wxPerl use Wx::Bitmap->newFromXPM(data).

◆ wxBitmap() [8/11]

wxBitmap::wxBitmap	(	const wxString &	name,
		wxBitmapType	type = `wxBITMAP_DEFAULT_TYPE`
	)

Loads a bitmap from a file or resource.

Parameters

name	This can refer to a resource name or a filename under MS Windows and X. Its meaning is determined by the type parameter.
type	May be one of the wxBitmapType values and indicates which type of bitmap should be loaded. See the note in the class detailed description. Note that the wxBITMAP_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()

◆ wxBitmap() [9/11]

wxBitmap::wxBitmap	(	const wxImage &	img,
		int	depth = `wxBITMAP_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 wxBITMAP_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 wxBitmap (most useful in 8-bit display mode). On other platforms, the palette is currently ignored.

Parameters

img	Platform-independent wxImage object.
depth	Specifies the depth of the bitmap. If this is omitted, the display depth of the screen is used.

◆ wxBitmap() [10/11]

wxBitmap::wxBitmap	(	const wxImage &	img,
		const wxDC &	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.

Parameters

img	Platform-independent wxImage object.
dc	DC from which the scaling factor is inherited

Since: 3.1.7 (previously this constructor overload was only available in wxMSW port)

◆ wxBitmap() [11/11]

wxBitmap::wxBitmap ( const wxCursor & cursor )

explicit

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

cursor A valid wxCursor.

Since: 3.1.0

Member Function Documentation

◆ AddHandler()

static void wxBitmap::AddHandler ( wxBitmapHandler * handler )

static

Adds a handler to the end of the static list of format handlers.

Parameters

handler A new bitmap format handler object. There is usually only one instance of a given handler class in an application session.

Note that unlike wxImage::AddHandler, there's no documented list of the wxBitmapHandlers available in wxWidgets. This is because they are platform-specific and most important, they are all automatically loaded at startup.

If you want to be sure that wxBitmap can load a certain type of image, you'd better use wxImage::AddHandler.

See also: wxBitmapHandler

◆ CleanUpHandlers()

static void wxBitmap::CleanUpHandlers ( )

static

Deletes all bitmap handlers.

This function is called by wxWidgets on exit.

◆ ConvertToDisabled()

wxBitmap wxBitmap::ConvertToDisabled ( unsigned char brightness = 255 ) const

Returns disabled (dimmed) version of the bitmap.

This method is not available when wxUSE_IMAGE == 0.

Since: 2.9.0

◆ ConvertToImage()

virtual wxImage wxBitmap::ConvertToImage ( ) const

virtual

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.

◆ CopyFromIcon()

virtual bool wxBitmap::CopyFromIcon ( const wxIcon & icon )

virtual

Creates the bitmap from an icon.

◆ Create() [1/3]

bool wxBitmap::Create	(	const wxSize &	sz,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

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

◆ Create() [2/3]

bool wxBitmap::Create	(	int	width,
		int	height,
		const wxDC &	dc
	)

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

Parameters

width	The width of the bitmap in pixels, must be strictly positive.
height	The height of the bitmap in pixels, must be strictly positive.
dc	DC from which the scaling factor is inherited

Returns: true if the creation was successful.

Since: 3.1.0

◆ Create() [3/3]

bool wxBitmap::Create	(	int	width,
		int	height,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

Creates a fresh bitmap.

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

Parameters

width	The width of the bitmap in pixels, must be strictly positive.
height	The height of the bitmap in pixels, must be strictly positive.
depth	The number of bits used to represent each bitmap pixel.

Returns: true if the creation was successful.

◆ CreateScaled()

bool wxBitmap::CreateScaled	(	int	width,
		int	height,
		int	depth,
		double	logicalScale
	)

Create a bitmap with a scale factor.

This is an older synonym for CreateWithDIPSize(), use the new function in the new code.

Parameters

width	The width of the bitmap in pixels, must be strictly positive.
height	The height of the bitmap in pixels, must be strictly positive.
depth	The number of bits used to represent each bitmap pixel.
logicalScale	Scale factor used by the bitmap, see SetScaleFactor().

Returns: true if the creation was successful.

Since: 3.1.0

◆ CreateWithDIPSize() [1/2]

bool wxBitmap::CreateWithDIPSize	(	const wxSize &	size,
		double	scale,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

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

This should be used when the bitmap size is fixed (e.g. at compile-time) and not if it comes from wxWindow::GetSize() or other similar functions – use CreateWithLogicalSize() in the latter case.

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

Parameters

size	The size of the bitmap in DPI-independent pixels. Both width and height must be strictly positive.
scale	Scale factor used by the bitmap, see SetScaleFactor().
depth	The number of bits used to represent each bitmap pixel.

Returns: true if the creation was successful.

Since: 3.1.6

◆ CreateWithDIPSize() [2/2]

bool wxBitmap::CreateWithDIPSize	(	int	width,
		int	height,
		double	scale,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

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

◆ CreateWithLogicalSize() [1/2]

bool wxBitmap::CreateWithLogicalSize	(	const wxSize &	size,
		double	scale,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

Create a bitmap specifying its size in logical pixels and the scale factor to use.

This should be typically used when creating bitmaps associated to a window area, e.g. to create a bitmap covering the entire window the size parameter should be wxWindow::GetClientSize() and scale should be the wxWindow::GetDPIScaleFactor().

The physical size of the bitmap created by this function depends on the platform and will be the same as size on the platforms for which wxHAS_DPI_INDEPENDENT_PIXELS is not defined (e.g. wxMSW) or size multiplied by scale for those where it is (e.g. wxGTK3, wxOSX and wxQt). In other words, this function is the same as CreateWithDIPSize() if wxHAS_DPI_INDEPENDENT_PIXELS is defined, but not otherwise.

Parameters

size	The size of the bitmap in logical pixels. Both width and height must be strictly positive.
scale	Scale factor used by the bitmap, see SetScaleFactor().
depth	The number of bits used to represent each bitmap pixel.

Returns: true if the creation was successful.

Since: 3.3.0

◆ CreateWithLogicalSize() [2/2]

bool wxBitmap::CreateWithLogicalSize	(	int	width,
		int	height,
		double	scale,
		int	depth = `wxBITMAP_SCREEN_DEPTH`
	)

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

◆ FindHandler() [1/3]

static wxBitmapHandler* wxBitmap::FindHandler	(	const wxString &	extension,
		wxBitmapType	bitmapType
	)

static

Finds the handler associated with the given extension and type.

Parameters

extension	The file extension, such as "bmp" (without the dot).
bitmapType	The bitmap type managed by the handler, see wxBitmapType.

Returns: A pointer to the handler if found, nullptr otherwise.

◆ FindHandler() [2/3]

static wxBitmapHandler* wxBitmap::FindHandler ( const wxString & name )

static

Finds the handler with the given name.

Returns: A pointer to the handler if found, nullptr otherwise.

◆ FindHandler() [3/3]

static wxBitmapHandler* wxBitmap::FindHandler ( wxBitmapType bitmapType )

static

Finds the handler associated with the given bitmap type.

Parameters

bitmapType The bitmap type managed by the handler, see wxBitmapType.

Returns: A pointer to the handler if found, nullptr otherwise.

See also: wxBitmapHandler

◆ GetDepth()

virtual int wxBitmap::GetDepth ( ) const

virtual

Gets the colour depth of the bitmap.

A value of 1 indicates a monochrome bitmap.

◆ GetDIPSize()

wxSize wxBitmap::GetDIPSize ( ) const

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.

Since: 3.1.6

◆ GetHandlers()

static wxList& wxBitmap::GetHandlers ( )

static

Returns the static list of bitmap format handlers.

See also: wxBitmapHandler

◆ GetHeight()

virtual int wxBitmap::GetHeight ( ) const

virtual

Returns the height of the bitmap in physical pixels.

See also: GetWidth(), GetSize(), GetLogicalHeight()

◆ GetLogicalHeight()

double wxBitmap::GetLogicalHeight ( ) const

Returns the height of the bitmap in logical pixels.

See GetLogicalSize() for more information.

See also: GetLogicalWidth(), GetWidth()

Since: 3.1.6

◆ GetLogicalSize()

wxSize wxBitmap::GetLogicalSize ( ) const

Returns the size of the bitmap in logical pixels.

For the platforms using DPI-independent pixels, i.e. those where wxHAS_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 wxDC coordinates, whether these pixels are the same as physical pixels, which are returned by GetSize(), or not.

See also: GetLogicalWidth(), GetLogicalHeight(), GetSize()

Since: 2.9.5

◆ GetLogicalWidth()

double wxBitmap::GetLogicalWidth ( ) const

Returns the width of the bitmap in logical pixels.

See GetLogicalSize() for more information.

See also: GetLogicalHeight(), GetWidth()

Since: 3.1.6

◆ GetMask()

virtual wxMask* wxBitmap::GetMask ( ) const

virtual

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

See also: SetMask(), wxMask

◆ GetPalette()

virtual wxPalette* wxBitmap::GetPalette ( ) const

virtual

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

See also: wxPalette

◆ GetScaledHeight()

double wxBitmap::GetScaledHeight ( ) const

Returns the height of the bitmap in logical pixels.

This is an older synonym for GetLogicalHeight(), use the new function in the new code.

Since: 2.9.5

◆ GetScaledSize()

wxSize wxBitmap::GetScaledSize ( ) const

Returns the size of the bitmap in logical pixels.

This is an older synonym for GetLogicalSize(), use the new function in the new code.

Since: 2.9.5

◆ GetScaledWidth()

double wxBitmap::GetScaledWidth ( ) const

Returns the width of the bitmap in logical pixels.

This is an older synonym for GetLogicalWidth(), use the new function in the new code.

Since: 2.9.5

◆ GetScaleFactor()

virtual double wxBitmap::GetScaleFactor ( ) const

virtual

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.

See also: SetScaleFactor(), GetLogicalWidth(), GetLogicalHeight(), GetLogicalSize()

Since: 2.9.5

◆ GetSize()

wxSize wxBitmap::GetSize ( ) const

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.

Since: 2.9.0

See also: GetHeight(), GetWidth(), GetLogicalSize()

◆ GetSubBitmap()

virtual wxBitmap wxBitmap::GetSubBitmap ( const wxRect & rect ) const

virtual

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

virtual int wxBitmap::GetWidth ( ) const

virtual

Returns the width of the bitmap in physical pixels.

See also: GetHeight(), GetSize(), GetLogicalWidth()

◆ HasAlpha()

bool wxBitmap::HasAlpha ( ) const

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 wxALPHA_OPAQUE value. To actually examine the alpha values, the bitmap can be converted to wxImage.

◆ InitStandardHandlers()

static void wxBitmap::InitStandardHandlers ( )

static

Adds the standard bitmap format handlers, which, depending on wxWidgets configuration, can be handlers for Windows bitmap, Windows bitmap resource, and XPM.

This function is called by wxWidgets on startup.

See also: wxBitmapHandler

◆ InsertHandler()

static void wxBitmap::InsertHandler ( wxBitmapHandler * handler )

static

Adds a handler at the start of the static list of format handlers.

Parameters

handler A new bitmap format handler object. There is usually only one instance of a given handler class in an application session.

See also: wxBitmapHandler

◆ IsOk()

virtual bool wxBitmap::IsOk ( ) const

virtual

Returns true if bitmap data is present.

◆ LoadFile()

virtual bool wxBitmap::LoadFile	(	const wxString &	name,
		wxBitmapType	type = `wxBITMAP_DEFAULT_TYPE`
	)

virtual

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 wxBitmapType values; see the note in the class detailed description. Note that the wxBITMAP_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: 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 GetPalette() member.

See also: SaveFile()

◆ NewFromPNGData()

static wxBitmap wxBitmap::NewFromPNGData	(	const void *	data,
		size_t	size
	)

static

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

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

#include <wx/imagpng.h>

imagpng.h

and calling

wxImage::AddHandler(new wxPNGHandler);

wxImage::AddHandler

static void AddHandler(wxImageHandler *handler)

Register an image handler.

wxPNGHandler

This is the image handler for the PNG format.

Definition: imagpng.h:39

in your application startup code.

However under macOS this function uses native image loading and so doesn't require wxWidgets PNG support.

Since: 2.9.5

◆ RemoveHandler()

static bool wxBitmap::RemoveHandler ( const wxString & name )

static

Finds the handler with the given name, and removes it.

The handler is not deleted.

Parameters

name	The handler name.

Returns: true if the handler was found and removed, false otherwise.

See also: wxBitmapHandler

◆ Rescale()

static void wxBitmap::Rescale	(	wxBitmap &	bmp,
		const wxSize &	sizeNeeded
	)

static

Rescale the given bitmap to the requested size.

This function is just a convenient wrapper for wxImage::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 wxIMAGE_QUALITY_NEAREST used by this function, please use the wxImage function directly instead.

Both the bitmap itself and size must be valid.

Since: 3.1.6

◆ ResetAlpha()

void wxBitmap::ResetAlpha ( )

Remove alpha channel from the bitmap.

This is the same as calling UseAlpha() with false argument.

◆ SaveFile()

virtual bool wxBitmap::SaveFile	(	const wxString &	name,
		wxBitmapType	type,
		const wxPalette *	palette = `nullptr`
	)		const

virtual

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 wxBitmapType values; see the note in the class detailed description.
palette	An optional palette used for saving the bitmap.

Returns: true if the operation succeeded, false otherwise.

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

See also: LoadFile()

◆ SetDepth()

virtual void wxBitmap::SetDepth ( int depth )

virtual

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

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

Parameters

depth Bitmap depth.

◆ SetHeight()

virtual void wxBitmap::SetHeight ( int height )

virtual

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

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

Parameters

height Bitmap height in pixels.

◆ SetMask()

virtual void wxBitmap::SetMask ( wxMask * mask )

virtual

Sets the mask for this bitmap.

Remarks: 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(), wxMask

◆ SetPalette()

virtual void wxBitmap::SetPalette ( const wxPalette & palette )

virtual

Sets the associated palette.

(Not implemented under GTK+).

Parameters

palette The palette to set.

See also: wxPalette

◆ SetScaleFactor()

virtual void wxBitmap::SetScaleFactor ( double scale )

virtual

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, CreateWithDIPSize() can be used to specify the correct scale factor from the beginning.

Since: 3.1.6

◆ SetWidth()

virtual void wxBitmap::SetWidth ( int width )

virtual

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

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

Parameters

width Bitmap width in pixels.

◆ UseAlpha()

bool wxBitmap::UseAlpha ( bool 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.

Returns: 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: HasAlpha(), ResetAlpha()

Detailed Description

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ wxBitmap() [1/11]

◆ wxBitmap() [2/11]

◆ wxBitmap() [3/11]

◆ wxBitmap() [4/11]

◆ wxBitmap() [5/11]

◆ wxBitmap() [6/11]

◆ wxBitmap() [7/11]

◆ wxBitmap() [8/11]

◆ wxBitmap() [9/11]

◆ wxBitmap() [10/11]

◆ wxBitmap() [11/11]

Member Function Documentation

◆ AddHandler()

◆ CleanUpHandlers()

◆ ConvertToDisabled()

◆ ConvertToImage()

◆ CopyFromIcon()

◆ Create() [1/3]

◆ Create() [2/3]

◆ Create() [3/3]

◆ CreateScaled()

◆ CreateWithDIPSize() [1/2]

◆ CreateWithDIPSize() [2/2]

◆ CreateWithLogicalSize() [1/2]

◆ CreateWithLogicalSize() [2/2]

◆ FindHandler() [1/3]

◆ FindHandler() [2/3]

◆ FindHandler() [3/3]

◆ GetDepth()

◆ GetDIPSize()

◆ GetHandlers()

◆ GetHeight()

◆ GetLogicalHeight()

◆ GetLogicalSize()

◆ GetLogicalWidth()

◆ GetMask()

◆ GetPalette()

◆ GetScaledHeight()

◆ GetScaledSize()

◆ GetScaledWidth()

◆ GetScaleFactor()

◆ GetSize()

◆ GetSubBitmap()

◆ GetWidth()

◆ HasAlpha()

◆ InitStandardHandlers()

◆ InsertHandler()

◆ IsOk()

◆ LoadFile()

◆ NewFromPNGData()

◆ RemoveHandler()

◆ Rescale()

◆ ResetAlpha()

◆ SaveFile()

◆ SetDepth()

◆ SetHeight()

◆ SetMask()

◆ SetPalette()

◆ SetScaleFactor()

◆ SetWidth()

◆ UseAlpha()