wxWidgets: wxBitmap Class Reference

| Version: 3.0.4

Public Member Functions | Static Public Member Functions | List of all members
wxBitmap Class Reference
Class List by Category » Graphics Device Interface (GDI)

`#include </usr/src/ports/wxWidgets3.0/wxWidgets3.0-3.0.4-1.x86_64/src/wxWidgets-3.0.4/interface/wx/bitmap.h>`

Inheritance diagram for wxBitmap:
[legend]

## 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

<>< =''>:</>&;&;< =''>\ </></>

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 (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...
virtual | ~wxBitmap ()
| Destructor. 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...
virtual bool | Create (int width, int height, int depth=wxBITMAP_SCREEN_DEPTH)
| Creates a fresh bitmap. More...
virtual 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...
virtual int | GetDepth () const
| Gets the colour depth of the bitmap. More...
virtual int | GetHeight () const
| Gets the height of the bitmap in 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...
wxSize | GetSize () const
| Returns the size of the bitmap in pixels. More...
wxBitmap | ConvertToDisabled (unsigned char brightness=255) const
| Returns disabled (dimmed) version of the bitmap. More...
virtual int | GetWidth () const
| Gets the width of the bitmap in pixels. 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...
virtual bool | SaveFile (const wxString &name, wxBitmapType type, const wxPalette *palette=NULL) const
| Saves a bitmap in the named file. More...
virtual void | SetDepth (int depth)
| Sets the depth member (does not affect the bitmap data). More...
virtual void | SetHeight (int height)
| Sets the height member (does not affect the bitmap data). 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)
| Sets the width member (does not affect the bitmap data). More...
Public Member Functions inherited from wxGDIObject
| wxGDIObject ()
| Default constructor. More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to NULL 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=NULL, 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...

## 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/8]

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/8]

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() [3/8]

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/8]

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

## ◆ wxBitmap() [5/8]

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/8]

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

Creates a bitmap from XPM data.

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

## ◆ wxBitmap() [7/8]

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() [8/8]

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

virtual wxBitmap::~wxBitmap | ( |  | ) |
| virtual

Destructor.

See Object Destruction for more info.

If the application omits to delete the bitmap explicitly, the bitmap will be destroyed automatically by wxWidgets when the application exits.

Warning
  Do not delete a bitmap that is selected into a memory device context.

## 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/2]

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

Creates a fresh bitmap.

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

Returns
  true if the creation was successful.

## ◆ Create() [2/2]

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

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 & | name | ) |
| static

Finds the handler with the given name.

Returns
  A pointer to the handler if found, NULL otherwise.

## ◆ FindHandler() [2/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, NULL 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, NULL 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.

## ◆ GetHandlers()

static wxList& wxBitmap::GetHandlers | ( |  | ) |
| static

Returns the static list of bitmap format handlers.

See also
  wxBitmapHandler

## ◆ GetHeight()

virtual int wxBitmap::GetHeight | ( |  | ) | const
| virtual

Gets the height of the bitmap in pixels.

See also
  GetWidth(), GetSize()

## ◆ 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

## ◆ GetSize()

wxSize wxBitmap::GetSize | ( |  | ) | const

Returns the size of the bitmap in pixels.

Since
  2.9.0

See also
  GetHeight(), GetWidth()

## ◆ 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

Gets the width of the bitmap in pixels.

See also
  GetHeight(), GetSize()

## ◆ 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>

and calling

wxImage::AddHandler(new wxPNGHandler);

in your application startup code.

However under OS X 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

## ◆ SaveFile()

virtual bool wxBitmap::SaveFile | ( | const wxString & | name,
|  | wxBitmapType | type,
|  | const wxPalette * | palette = `NULL`
| ) |  | 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

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

Todo:
  since these functions do not affect the bitmap data, why they exist??

Parameters

  depth | Bitmap depth.

## ◆ SetHeight()

virtual void wxBitmap::SetHeight | ( | int | height | ) |
| virtual

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.

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

## ◆ SetWidth()

virtual void wxBitmap::SetWidth | ( | int | width | ) |
| virtual

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

Parameters

  width | Bitmap width in pixels.