// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+/**
+ In wxBitmap and wxBitmapHandler context this value means: "use the screen depth".
+*/
+#define wxBITMAP_SCREEN_DEPTH (-1)
+
/**
@class wxBitmapHandler
@wxheader{bitmap.h}
It is used within wxBitmap and is not normally seen by the application.
If you wish to extend the capabilities of wxBitmap, derive a class from
- wxBitmapHandler and add the handler using wxBitmap::AddHandler in your
+ wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your
application initialisation.
@library{wxcore}
/**
Destroys the wxBitmapHandler object.
*/
- ~wxBitmapHandler();
+ virtual ~wxBitmapHandler();
/**
Creates a bitmap from the given data, which can be of arbitrary type.
@param height
The height of the bitmap in pixels.
@param depth
- The depth of the bitmap in pixels. If this is -1, the screen depth is used.
+ The depth of the bitmap in pixels.
+ If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used.
@param data
Data whose type depends on the value of type.
@param type
A bitmap type identifier - see ::wxBitmapType for a list
of possible values.
-@todo why type is an int and not a wxBitmapType?
-
- @returns @true if the call succeeded, @false otherwise (the default).
+ @return @true if the call succeeded, @false otherwise (the default).
*/
- virtual bool Create(wxBitmap* bitmap, const void* data, int type,
- int width, int height, int depth = -1);
+ virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type,
+ int width, int height, int depth = 1);
/**
Gets the file extension associated with this handler.
*/
- const wxString GetExtension() const;
+ const wxString& GetExtension() const;
/**
Gets the name of this handler.
*/
- const wxString GetName() const;
+ const wxString& GetName() const;
/**
Gets the bitmap type associated with this handler.
-@todo why type is an int and not a wxBitmapType?
*/
- long GetType() const;
+ wxBitmapType GetType() const;
/**
Loads a bitmap from a file or resource, putting the resulting data into
Either a filename or a Windows resource name.
The meaning of name is determined by the type parameter.
@param type
- See wxBitmap::wxBitmap for values this can take.
-
- @returns @true if the operation succeeded, @false otherwise.
+ See ::wxBitmapType for values this can take.
+ @param desiredWidth
+ The desired width for the loaded bitmap.
+ @param desiredHeight
+ The desired height for the loaded bitmap.
-@todo why type is an int and not a wxBitmapType?
+ @return @true if the operation succeeded, @false otherwise.
@see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
*/
- bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);
+ virtual bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,
+ int desiredWidth, int desiredHeight);
/**
Saves a bitmap in the named file.
@param name
A filename. The meaning of name is determined by the type parameter.
@param type
- See wxBitmap::wxBitmap for values this can take.
+ See ::wxBitmapType for values this can take.
@param palette
An optional palette used for saving the bitmap.
- @returns @true if the operation succeeded, @false otherwise.
-
-@todo why type is an int and not a wxBitmapType?
+ @return @true if the operation succeeded, @false otherwise.
@see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
*/
- bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
- wxPalette* palette = NULL);
+ virtual bool SaveFile(const wxBitmap* bitmap, const wxString& name, wxBitmapType type,
+ const wxPalette* palette = NULL) const;
/**
Sets the handler extension.
/**
Sets the handler type.
-@todo why type is an int and not a wxBitmapType?
-
@param type
Handler type.
*/
- void SetType(long type);
+ void SetType(wxBitmapType type);
};
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).
@note
- Many wxBitmap functions take a @e type parameter, which is a value of
- the ::wxBitmapType enumeration.
+ 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,
::wxNullBitmap
@see @ref overview_bitmap, @ref overview_bitmap_supportedformats,
- wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC
+ wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData
*/
class wxBitmap : public wxGDIObject
{
*/
wxBitmap(const wxBitmap& bitmap);
- /**
+
+ /*
Creates a bitmap from the given @a data which is interpreted in
platform-dependent manner.
@param depth
Specifies the depth of the bitmap.
If this is omitted, the display depth of the screen is used.
+ wxBitmap(const void* data, int type, int width, int height, int depth = -1);
-@todo why type is an int and not a wxBitmapType?
+ NOTE: this ctor is not implemented by all ports, is somewhat useless
+ without further description of the "data" supported formats and
+ uses 'int type' instead of wxBitmapType, so don't document it.
*/
- wxBitmap(const void* data, int type, int width, int height, int depth = -1);
/**
Creates a bitmap from the given array @a bits.
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.
+ Under other platforms, only monochrome bitmaps may be created using this
+ constructor and wxImage should be used for creating colour bitmaps from
+ static data.
@param bits
Specifies an array of pixel values.
Specifies the height of the bitmap.
@param depth
Specifies the depth of the bitmap.
- If this is omitted, the display depth of the screen is used.
+ If this is omitted, then a value of 1 (monochrome bitmap) is used.
*/
wxBitmap(const char bits[], 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
+ 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(int width, int height, int depth = -1);
+ wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
/**
Creates a bitmap from XPM data.
@see LoadFile()
*/
- wxBitmap(const wxString& name, long type);
+ wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM);
/**
- 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.
+ 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 -1) which entails that a colour reduction has
- to take place.
+ current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
+ colour reduction may 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,
Specifies the depth of the bitmap.
If this is omitted, the display depth of the screen is used.
*/
- wxBitmap(const wxImage& img, int depth = -1);
-
+ wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);
/**
Destructor.
@warning
Do not delete a bitmap that is selected into a memory device context.
*/
- ~wxBitmap();
+ virtual ~wxBitmap();
/**
Adds a handler to the end of the static list of format handlers.
mask information so that bitmaps and images can be converted back
and forth without loss in that respect.
*/
- wxImage ConvertToImage();
+ virtual wxImage ConvertToImage() const;
/**
Creates the bitmap from an icon.
*/
- bool CopyFromIcon(const wxIcon& icon);
-
+ virtual bool CopyFromIcon(const wxIcon& icon);
/**
Creates a fresh bitmap.
This overload works on all platforms.
*/
- virtual bool Create(int width, int height, int depth = -1);
+ virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
- /**
+ /*
Creates a bitmap from the given data, which can be of arbitrary type.
@param data
@param depth
The depth of the bitmap in pixels. If this is -1, the screen depth is used.
- @returns @true if the call succeeded, @false otherwise.
+ @return @true if the call succeeded, @false otherwise.
This overload depends on the @a type of data.
- */
virtual bool Create(const void* data, int type, int width,
int height, int depth = -1);
+ NOTE: leave this undoc for the same reason of the relative ctor.
+ */
+
/**
Finds the handler with the given @a name.
- @returns A pointer to the handler if found, @NULL otherwise.
+ @return A pointer to the handler if found, @NULL otherwise.
*/
static wxBitmapHandler* FindHandler(const wxString& name);
@param bitmapType
The bitmap type managed by the handler, see ::wxBitmapType.
- @returns A pointer to the handler if found, @NULL otherwise.
+ @return A pointer to the handler if found, @NULL otherwise.
*/
static wxBitmapHandler* FindHandler(const wxString& extension,
wxBitmapType bitmapType);
@param bitmapType
The bitmap type managed by the handler, see ::wxBitmapType.
- @returns A pointer to the handler if found, @NULL otherwise.
+ @return A pointer to the handler if found, @NULL otherwise.
@see wxBitmapHandler
*/
static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
/**
- Gets the colour depth of the bitmap. A value of 1 indicates a
- monochrome bitmap.
+ Gets the colour depth of the bitmap.
+ A value of 1 indicates a monochrome bitmap.
*/
- int GetDepth() const;
+ virtual int GetDepth() const;
/**
Returns the static list of bitmap format handlers.
/**
Gets the height of the bitmap in pixels.
*/
- int GetHeight() const;
+ virtual int GetHeight() const;
/**
Gets the associated mask (if any) which may have been loaded from a file
@see SetMask(), wxMask
*/
- wxMask* GetMask() const;
+ virtual wxMask* GetMask() const;
/**
Gets the associated palette (if any) which may have been loaded from a file
@see wxPalette
*/
- wxPalette* GetPalette() const;
+ virtual wxPalette* GetPalette() 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 GetSubBitmap(const wxRect& rect) const;
+ virtual wxBitmap GetSubBitmap(const wxRect& rect) const;
/**
Gets the width of the bitmap in pixels.
@see GetHeight()
*/
- int GetWidth() const;
+ virtual int GetWidth() const;
/**
Adds the standard bitmap format handlers, which, depending on wxWidgets
One of the ::wxBitmapType values; see the note in the class
detailed description.
- @returns @true if the operation succeeded, @false otherwise.
+ @return @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
@see SaveFile()
*/
- bool LoadFile(const wxString& name, wxBitmapType type);
+ virtual bool LoadFile(const wxString& name, wxBitmapType type);
/**
Finds the handler with the given name, and removes it.
@param name
The handler name.
- @returns @true if the handler was found and removed, @false otherwise.
+ @return @true if the handler was found and removed, @false otherwise.
@see wxBitmapHandler
*/
@param palette
An optional palette used for saving the bitmap.
- @returns @true if the operation succeeded, @false otherwise.
+ @return @true if the operation succeeded, @false otherwise.
@remarks Depending on how wxWidgets has been configured, not all formats
may be available.
@see LoadFile()
*/
- bool SaveFile(const wxString& name, wxBitmapType type,
- wxPalette* palette = NULL);
+ virtual bool SaveFile(const wxString& name, wxBitmapType type,
+ const wxPalette* palette = NULL) const;
/**
Sets the depth member (does not affect the bitmap data).
@param depth
Bitmap depth.
*/
- void SetDepth(int depth);
+ virtual void SetDepth(int depth);
/**
Sets the height member (does not affect the bitmap data).
@param height
Bitmap height in pixels.
*/
- void SetHeight(int height);
+ virtual void SetHeight(int height);
/**
Sets the mask for this bitmap.
@see GetMask(), wxMask
*/
- void SetMask(wxMask* mask);
+ virtual void SetMask(wxMask* mask);
/**
Sets the associated palette. (Not implemented under GTK+).
@see wxPalette
*/
- void SetPalette(const wxPalette& palette);
+ virtual void SetPalette(const wxPalette& palette);
/**
Sets the width member (does not affect the bitmap data).
@param width
Bitmap width in pixels.
*/
- void SetWidth(int width);
-
- /**
- Assignment operator, using @ref overview_refcount "reference counting".
-
- @param bitmap
- Bitmap to assign.
- */
- wxBitmap operator =(const wxBitmap& bitmap);
+ virtual void SetWidth(int width);
};
/**
/**
Destroys the wxMask object and the underlying bitmap data.
*/
- ~wxMask();
+ virtual ~wxMask();
/**
Constructs a mask from a bitmap and a palette index that indicates the
projects / wxWidgets.git / blobdiff