wxBitmap

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

Derived from

wxGDIObject
wxObject

Include file

Predefined objects

Objects:

wxNullBitmap

wxBitmap::wxBitmap

wxBitmap(void)

Default constructor.

wxBitmap(const wxBitmap& bitmap)

Copy constructor. Note that this does not take a fresh copy of the data, but instead makes the internal data point to bitmap's data. So changing one bitmap will change the other. To make a real copy, you can use:

    wxBitmap newBitmap = oldBitmap.GetSubBitmap(
                             wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));

wxBitmap(void* data, int type, int width, int height, int depth = -1)

Creates a bitmap from the given data which is interpreted in platform-dependent manner.

wxBitmap(const char bits[], int width, int height
int depth = 1)

Creates a bitmap from an array of 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.

wxBitmap(int width, int height, int depth = -1)

Creates a new bitmap. A depth of -1 indicates the depth of the current screen or visual. Some platforms only support 1 for monochrome and -1 for the current colour setting. Beginning with version 2.5.4 of wxWidgets a depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.

wxBitmap(const char** bits)

Creates a bitmap from XPM data.

wxBitmap(const wxString& name, long type)

Loads a bitmap from a file or resource.

wxBitmap(const wxImage& img, int depth = -1)

Creates bitmap object from the 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 -1) which entails that a colour reduction has to take place.

When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube created on program start-up to look up colors. This ensures a very fast conversion, but the image quality won't be perfect (and could be better for photo images using more sophisticated dithering algorithms).

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

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, the display depth of the screen is used.

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

type

May be one of the following:

wxBITMAP_TYPE_BMP Load a Windows bitmap file.

wxBITMAP_TYPE_BMP_RESOURCE Load a Windows bitmap resource from the executable. Windows only.

wxBITMAP_TYPE_PICT_RESOURCE Load a PICT image resource from the executable. Mac OS only.

wxBITMAP_TYPE_GIF Load a GIF bitmap file.

wxBITMAP_TYPE_XBM Load an X bitmap file.

wxBITMAP_TYPE_XPM Load an XPM bitmap file.

The validity of these flags depends on the platform and wxWidgets configuration. If all possible wxWidgets settings are used, the Windows platform supports BMP file, BMP resource, XPM data, and XPM. Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file. Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.

In addition, wxBitmap can read all formats that wxImage can, which currently include wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_TIF, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_PCX, and wxBITMAP_TYPE_PNM. Of course, you must have wxImage handlers loaded.

img: Platform-independent wxImage object.

Remarks

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

The second and third forms provide copy constructors. Note that these do not copy the bitmap data, but instead a pointer to the data, keeping a reference count. They are therefore very efficient operations.

The fourth form constructs a bitmap from data whose type and value depends on the value of the type argument.

The fifth form constructs a (usually monochrome) bitmap from an array of pixel values, under both X and Windows.

The sixth form constructs a new bitmap.

The seventh form constructs a bitmap from pixmap (XPM) data, if wxWidgets has been configured to incorporate this feature.

To use this constructor, you must first include an XPM file. For example, assuming that the file mybitmap.xpm contains an XPM array of character pointers called mybitmap:

#include "mybitmap.xpm"

...

wxBitmap *bitmap = new wxBitmap(mybitmap);

The eighth form constructs a bitmap from a file or resource. name can refer to a resource name under MS Windows, or a filename under MS Windows and X.

Under Windows, type defaults to wxBITMAP_TYPE_BMP_RESOURCE. Under X, type defaults to wxBITMAP_TYPE_XPM.

See also

wxBitmap::LoadFile

wxPython での注意点: Constructors supported by wxPython are:

2cm

wxBitmap(name, flag) Loads a bitmap from a file

wxEmptyBitmap(width, height, depth = -1) Creates an empty bitmap with the given specifications

wxBitmapFromXPMData(listOfStrings) Create a bitmap from a Python list of strings whose contents are XPM data.

wxBitmapFromBits(bits, width, height, depth=-1) Create a bitmap from an array of bits contained in a string.

wxBitmapFromImage(image, depth=-1) Convert a wxImage to a wxBitmap.

wxPerl での注意点: Constructors supported by wxPerl are:

Wx::Bitmap->new( width, height, depth = -1 )
Wx::Bitmap->new( name, type )
Wx::Bitmap->new( icon )
Wx::Bitmap->newFromBits( bits, width, height, depth = 1 )
Wx::Bitmap->newFromXPM( data )

wxBitmap::~wxBitmap

~wxBitmap(void)

Destroys the wxBitmap object and possibly the underlying bitmap data. Because reference counting is used, the bitmap may not actually be destroyed at this point - only when the reference count is zero will the data be deleted.

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

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

wxBitmap::AddHandler

static void AddHandler(wxBitmapHandler* handler)

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

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

wxBitmap::CleanUpHandlers

static void CleanUpHandlers(void)

Deletes all bitmap handlers.

This function is called by wxWidgets on exit.

wxBitmap::ConvertToImage

wxImage ConvertToImage(void)

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.

wxBitmap::CopyFromIcon

bool CopyFromIcon(const wxIcon& icon)

Creates the bitmap from an icon.

wxBitmap::Create

virtual bool Create(int width, int height, int depth = -1)

Creates a fresh bitmap. If the final argument is omitted, the display depth of the screen is used.

virtual bool Create(void* data, int type, int width, int height, int depth = -1)

Creates a bitmap from the given data, which can be of arbitrary type.

Parameters

width: The width of the bitmap in pixels.

height: The height of the bitmap in pixels.

depth: The depth of the bitmap in pixels. If this is -1, the screen depth is used.

data: Data whose type depends on the value of type.

type: A bitmap type identifier - see wxBitmap::wxBitmap for a list of possible values.

Return value

true if the call succeeded, false otherwise.

Remarks

The first form works on all platforms. The portability of the second form depends on the type of data.

See also

wxBitmap::wxBitmap

wxBitmap::FindHandler

static wxBitmapHandler* FindHandler(const wxString& name)

Finds the handler with the given name.

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

Finds the handler associated with the given extension and type.

static wxBitmapHandler* FindHandler(wxBitmapType bitmapType)

Finds the handler associated with the given bitmap type.

name: The handler name.

extension: The file extension, such as ``bmp".

bitmapType: The bitmap type, such as wxBITMAP_TYPE_BMP.

Return value

A pointer to the handler if found, NULL otherwise.

See also

wxBitmapHandler

wxBitmap::GetDepth

int GetDepth(void) const

Gets the colour depth of the bitmap. A value of 1 indicates a monochrome bitmap.

wxBitmap::GetHandlers

static wxList& GetHandlers(void)

Returns the static list of bitmap format handlers.

See also

wxBitmapHandler

wxBitmap::GetHeight

int GetHeight(void) const

Gets the height of the bitmap in pixels.

wxBitmap::GetPalette

wxPalette* GetPalette(void) const

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

See also

wxPalette

wxBitmap::GetMask

wxMask* GetMask(void) const

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

See also

wxBitmap::SetMask, wxMask

wxBitmap::GetWidth

int GetWidth(void) const

Gets the width of the bitmap in pixels.

See also

wxBitmap::GetHeight

wxBitmap::GetSubBitmap

wxBitmap GetSubBitmap(const wxRect& rect) const

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.

wxBitmap::InitStandardHandlers

static void InitStandardHandlers(void)

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

wxBitmap::InsertHandler

static void InsertHandler(wxBitmapHandler* handler)

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

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

wxBitmap::LoadFile

bool LoadFile(const wxString& name, wxBitmapType type)

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 following values:

wxBITMAP_TYPE_BMP Load a Windows bitmap file.

wxBITMAP_TYPE_BMP_RESOURCE Load a Windows bitmap resource from the executable.

wxBITMAP_TYPE_PICT_RESOURCE Load a PICT image resource from the executable. Mac OS only.

wxBITMAP_TYPE_GIF Load a GIF bitmap file.

wxBITMAP_TYPE_XBM Load an X bitmap file.

wxBITMAP_TYPE_XPM Load an XPM bitmap file.

The validity of these flags depends on the platform and wxWidgets configuration.

In addition, wxBitmap can read all formats that wxImage can (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG, wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_PCX, wxBITMAP_TYPE_PNM). (Of course you must have wxImage handlers loaded.)

Return value

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

wxBitmap::SaveFile

wxBitmap::Ok

bool Ok(void) const

Returns true if bitmap data is present.

wxBitmap::RemoveHandler

static bool RemoveHandler(const wxString& name)

Finds the handler with the given name, and removes it. The handler is not deleted.

name: The handler name.

Return value

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

See also

wxBitmapHandler

wxBitmap::SaveFile

bool SaveFile(const wxString& name, wxBitmapType type, wxPalette* palette = NULL)

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 following values:

wxBITMAP_TYPE_BMP Save a Windows bitmap file.

wxBITMAP_TYPE_GIF Save a GIF bitmap file.

wxBITMAP_TYPE_XBM Save an X bitmap file.

wxBITMAP_TYPE_XPM Save an XPM bitmap file.

The validity of these flags depends on the platform and wxWidgets configuration.

In addition, wxBitmap can save all formats that wxImage can (wxBITMAP_TYPE_JPEG, wxBITMAP_TYPE_PNG). (Of course you must have wxImage handlers loaded.)

palette: An optional palette used for saving the bitmap.

Return value

true if the operation succeeded, false otherwise.

Remarks

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

See also

wxBitmap::LoadFile

wxBitmap::SetDepth

void SetDepth(int depth)

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

Parameters

depth: Bitmap depth.

wxBitmap::SetHeight

void SetHeight(int height)

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

Parameters

height: Bitmap height in pixels.

wxBitmap::SetMask

void SetMask(wxMask* mask)

Sets the mask for this bitmap.

Remarks

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

See also

wxBitmap::GetMask, wxMask

wxBitmap::SetPalette

void SetPalette(const wxPalette& palette)

Sets the associated palette. (Not implemented under GTK+).

Parameters

palette: The palette to set.

See also

wxPalette

wxBitmap::SetWidth

void SetWidth(int width)

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

Parameters

width: Bitmap width in pixels.

wxBitmap::operator

wxBitmap& operator (const wxBitmap& bitmap)

Assignment operator. This operator does not copy any data, but instead passes a pointer to the data in bitmap and increments a reference counter. It is a fast operation.

Parameters

bitmap: Bitmap to assign.

Return value

Returns 'this' object.

wxBitmap::operator

bool operator (const wxBitmap& bitmap)

Equality operator. This operator tests whether the internal data pointers are equal (a fast test).

Parameters

bitmap: Bitmap to compare with 'this'

Return value

Returns true if the bitmaps were effectively equal, false otherwise.

wxBitmap::operator $\!=$

bool operator $\!=$ (const wxBitmap& bitmap)

Inequality operator. This operator tests whether the internal data pointers are unequal (a fast test).

Parameters

bitmap: Bitmap to compare with 'this'

Return value

Returns true if the bitmaps were unequal, false otherwise.

ymasuda 平成17年11月19日

wxBITMAP_TYPE_BMP	Load a Windows bitmap file.
wxBITMAP_TYPE_BMP_RESOURCE	Load a Windows bitmap resource from the executable. Windows only.
wxBITMAP_TYPE_PICT_RESOURCE	Load a PICT image resource from the executable. Mac OS only.
wxBITMAP_TYPE_GIF	Load a GIF bitmap file.
wxBITMAP_TYPE_XBM	Load an X bitmap file.
wxBITMAP_TYPE_XPM	Load an XPM bitmap file.

wxBitmap(name, flag)	Loads a bitmap from a file
wxEmptyBitmap(width, height, depth = -1)	Creates an empty bitmap with the given specifications
wxBitmapFromXPMData(listOfStrings)	Create a bitmap from a Python list of strings whose contents are XPM data.
wxBitmapFromBits(bits, width, height, depth=-1)	Create a bitmap from an array of bits contained in a string.
wxBitmapFromImage(image, depth=-1)	Convert a wxImage to a wxBitmap.

wxBITMAP_TYPE_BMP	Load a Windows bitmap file.
wxBITMAP_TYPE_BMP_RESOURCE	Load a Windows bitmap resource from the executable.
wxBITMAP_TYPE_PICT_RESOURCE	Load a PICT image resource from the executable. Mac OS only.
wxBITMAP_TYPE_GIF	Load a GIF bitmap file.
wxBITMAP_TYPE_XBM	Load an X bitmap file.
wxBITMAP_TYPE_XPM	Load an XPM bitmap file.

wxBITMAP_TYPE_BMP	Save a Windows bitmap file.
wxBITMAP_TYPE_GIF	Save a GIF bitmap file.
wxBITMAP_TYPE_XBM	Save an X bitmap file.
wxBITMAP_TYPE_XPM	Save an XPM bitmap file.