// 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
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 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 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 LoadFile()
*/
- wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM);
+ wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
/**
Creates this bitmap object from the given image.
@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.
@param 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.
@return @true if the operation succeeded, @false otherwise.
@see SaveFile()
*/
- virtual bool LoadFile(const wxString& name, wxBitmapType type);
+ 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.
/**
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