// Name: bitmap.h
// Purpose: interface of wxBitmap* classes
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
If you wish to extend the capabilities of wxBitmap, derive a class from
wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your
- application initialisation.
+ application initialization.
+
+ Note that all wxBitmapHandlers provided by wxWidgets are part of the
+ @ref page_libs_wxcore library.
+ For details about the default handlers, please see the note in the
+ wxBitmap class documentation.
@library{wxcore}
- @category{misc}
+ @category{gdi}
@see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor
*/
Loads a bitmap from a file or resource, putting the resulting data into
@a bitmap.
+ @note Under MSW, when loading a bitmap from resources (i.e. using @c
+ wxBITMAP_TYPE_BMP_RESOURCE as @a type), the light grey colour is
+ considered to be transparent, for historical reasons. If you want
+ to handle the light grey pixels normally instead, call
+ SetMask(NULL) after loading the bitmap.
+
@param bitmap
The bitmap object which is to be affected by this operation.
@param name
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 additionaly alpha channel).
+ for bitmaps with an additionally alpha channel).
- @note
- Many wxBitmap functions take a @e type parameter, which is a value of the
- ::wxBitmapType enumeration.
+ Note that many wxBitmap functions take a @e 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, 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 load and save all formats that wxImage; see wxImage for
- more info. Of course, you must have wxImage handlers loaded.
+ If all possible wxWidgets settings are used:
+ - wxMSW supports BMP and ICO files, BMP and ICO resources;
+ - wxGTK supports XPM files;
+ - 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{gdi}
@param depth
Specifies the depth of the bitmap.
If this is omitted, then a value of 1 (monochrome bitmap) is used.
+
+ @beginWxPerlOnly
+ In wxPerl use Wx::Bitmap->newFromBits(bits, width, height, depth).
+ @endWxPerlOnly
*/
wxBitmap(const char bits[], int width, int height, int depth = 1);
A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
*/
wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
+
+ /**
+ @overload
+ */
+ wxBitmap(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
/**
Creates a bitmap from XPM data.
+
+ @beginWxPerlOnly
+ In wxPerl use Wx::Bitmap->newFromXPM(data).
+ @endWxPerlOnly
*/
wxBitmap(const char* const* bits);
@param 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 wxBitmapHandler
*/
/**
Creates a fresh bitmap.
If the final argument is omitted, the display depth of the screen is used.
-
- This overload works on all platforms.
+
+ @return @true if the creation was successful.
*/
virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
+
+ /**
+ @overload
+ */
+ virtual bool Create(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
/*
Creates a bitmap from the given data, which can be of arbitrary type.
@see wxBitmapHandler
*/
- static wxList GetHandlers();
+ static wxList& GetHandlers();
/**
Gets the height of the bitmap in pixels.
+
+ @see GetWidth(), GetSize()
*/
virtual int GetHeight() const;
*/
virtual wxBitmap GetSubBitmap(const wxRect& rect) const;
+ /**
+ Returns the size of the bitmap in pixels.
+
+ @since 2.9.0
+
+ @see GetHeight(), GetWidth()
+ */
+ wxSize GetSize() const;
+
+ /**
+ Returns disabled (dimmed) version of the bitmap.
+
+ This method is not available when <code>wxUSE_IMAGE == 0</code>.
+
+ @since 2.9.0
+ */
+ wxBitmap ConvertToDisabled(unsigned char brightness = 255) const;
+
/**
Gets the width of the bitmap in pixels.
- @see GetHeight()
+ @see GetHeight(), GetSize()
*/
virtual int GetWidth() const;
/**
Returns @true if bitmap data is present.
*/
- bool IsOk() const;
+ virtual bool IsOk() const;
/**
Loads a bitmap from a file or resource.
*/
virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
+ /**
+ 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:
+ @code
+ #include <wx/imagpng.h>
+ @endcode
+ and calling
+ @code
+ wxImage::AddHandler(new wxPNGHandler);
+ @endcode
+ 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
+ */
+ static wxBitmap NewFromPNGData(const void* data, size_t size);
+
/**
Finds the handler with the given name, and removes it.
The handler is not deleted.
/**
Constructs a mask from a monochrome bitmap.
-
- @beginWxPythonOnly
- This is the default constructor for wxMask in wxPython.
- @endWxPythonOnly
*/
wxMask(const wxBitmap& bitmap);
/**
Constructs a mask from a bitmap and a colour that indicates the background.
-
- @beginWxPythonOnly
- wxPython has an alternate wxMask constructor matching this form called wxMaskColour.
- @endWxPythonOnly
*/
wxMask(const wxBitmap& bitmap, const wxColour& colour);
Constructs a mask from a bitmap and a colour that indicates the background.
*/
bool Create(const wxBitmap& bitmap, const wxColour& colour);
+
+ /**
+ Returns the mask as a monochrome bitmap.
+ Currently this method is implemented in wxMSW, wxGTK and wxOSX.
+
+ @since 2.9.5
+ */
+ wxBitmap GetBitmap() const;
};
projects / wxWidgets.git / blobdiff