added interface headers with latest discussed changes
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
697
interface/bitmap.h
Normal file
697
interface/bitmap.h
Normal file
@@ -0,0 +1,697 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: bitmap.h
|
||||
// Purpose: documentation for wxBitmapHandler class
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
// Licence: wxWindows license
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/**
|
||||
@class wxBitmapHandler
|
||||
@wxheader{bitmap.h}
|
||||
|
||||
Overview
|
||||
|
||||
This is the base class for implementing bitmap file loading/saving, and bitmap
|
||||
creation from data.
|
||||
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
|
||||
application initialisation.
|
||||
|
||||
@library{wxcore}
|
||||
@category{FIXME}
|
||||
|
||||
@seealso
|
||||
wxBitmap, wxIcon, wxCursor
|
||||
*/
|
||||
class wxBitmapHandler : public wxObject
|
||||
{
|
||||
public:
|
||||
/**
|
||||
Default constructor. In your own default constructor, initialise the members
|
||||
m_name, m_extension and m_type.
|
||||
*/
|
||||
wxBitmapHandler();
|
||||
|
||||
/**
|
||||
Destroys the wxBitmapHandler object.
|
||||
*/
|
||||
~wxBitmapHandler();
|
||||
|
||||
/**
|
||||
Creates a bitmap from the given data, which can be of arbitrary type. The
|
||||
wxBitmap object @e bitmap is
|
||||
manipulated by this function.
|
||||
|
||||
@param bitmap
|
||||
The wxBitmap object.
|
||||
|
||||
@param width
|
||||
The width of the bitmap in pixels.
|
||||
|
||||
@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.
|
||||
|
||||
@param data
|
||||
Data whose type depends on the value of type.
|
||||
|
||||
@param type
|
||||
A bitmap type identifier - see wxBitmapHandler() for a list
|
||||
of possible values.
|
||||
|
||||
@returns @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);
|
||||
|
||||
/**
|
||||
Gets the file extension associated with this handler.
|
||||
*/
|
||||
const wxString GetExtension();
|
||||
|
||||
/**
|
||||
Gets the name of this handler.
|
||||
*/
|
||||
const wxString GetName();
|
||||
|
||||
/**
|
||||
Gets the bitmap type associated with this handler.
|
||||
*/
|
||||
long GetType();
|
||||
|
||||
/**
|
||||
Loads a bitmap from a file or resource, putting the resulting data into @e
|
||||
bitmap.
|
||||
|
||||
@param bitmap
|
||||
The bitmap object which is to be affected by this operation.
|
||||
|
||||
@param name
|
||||
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.
|
||||
|
||||
@sa wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
|
||||
*/
|
||||
bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);
|
||||
|
||||
/**
|
||||
Saves a bitmap in the named file.
|
||||
|
||||
@param bitmap
|
||||
The bitmap object which is to be affected by this operation.
|
||||
|
||||
@param name
|
||||
A filename. The meaning of name is determined by the type parameter.
|
||||
|
||||
@param type
|
||||
See wxBitmap::wxBitmap for values this can take.
|
||||
|
||||
@param palette
|
||||
An optional palette used for saving the bitmap.
|
||||
|
||||
@returns @true if the operation succeeded, @false otherwise.
|
||||
|
||||
@sa wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
|
||||
*/
|
||||
bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
|
||||
wxPalette* palette = @NULL);
|
||||
|
||||
/**
|
||||
Sets the handler extension.
|
||||
|
||||
@param extension
|
||||
Handler extension.
|
||||
*/
|
||||
void SetExtension(const wxString& extension);
|
||||
|
||||
/**
|
||||
Sets the handler name.
|
||||
|
||||
@param name
|
||||
Handler name.
|
||||
*/
|
||||
void SetName(const wxString& name);
|
||||
|
||||
/**
|
||||
Sets the handler type.
|
||||
|
||||
@param name
|
||||
Handler type.
|
||||
*/
|
||||
void SetType(long type);
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
@class wxBitmap
|
||||
@wxheader{bitmap.h}
|
||||
|
||||
This class encapsulates the concept of a platform-dependent bitmap,
|
||||
either monochrome or colour or colour with alpha channel support.
|
||||
|
||||
@library{wxcore}
|
||||
@category{gdi}
|
||||
|
||||
@stdobjects
|
||||
Objects:
|
||||
wxNullBitmap
|
||||
|
||||
@seealso
|
||||
@ref overview_wxbitmapoverview "wxBitmap overview", @ref
|
||||
overview_supportedbitmapformats "supported bitmap file formats", wxDC::Blit, wxIcon, wxCursor, wxBitmap, wxMemoryDC
|
||||
*/
|
||||
class wxBitmap : public wxGDIObject
|
||||
{
|
||||
public:
|
||||
//@{
|
||||
/**
|
||||
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.
|
||||
|
||||
@param bits
|
||||
Specifies an array of pixel values.
|
||||
|
||||
@param width
|
||||
Specifies the width of the bitmap.
|
||||
|
||||
@param height
|
||||
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.
|
||||
|
||||
@param 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.
|
||||
|
||||
@param 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.
|
||||
|
||||
@param 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.
|
||||
|
||||
@sa LoadFile()
|
||||
*/
|
||||
wxBitmap();
|
||||
wxBitmap(const wxBitmap& bitmap);
|
||||
wxBitmap(const void* data, int type, int width, int height,
|
||||
int depth = -1);
|
||||
wxBitmap(const char bits[], int width, int height,
|
||||
int depth = 1);
|
||||
wxBitmap(int width, int height, int depth = -1);
|
||||
wxBitmap(const char* const* bits);
|
||||
wxBitmap(const wxString& name, long type);
|
||||
wxBitmap(const wxImage& img, int depth = -1);
|
||||
//@}
|
||||
|
||||
/**
|
||||
Destructor.
|
||||
See @ref overview_refcountdestruct "reference-counted 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.
|
||||
|
||||
Do not delete a bitmap that is selected into a memory device context.
|
||||
*/
|
||||
~wxBitmap();
|
||||
|
||||
/**
|
||||
Adds a handler to the end of the static list of format handlers.
|
||||
|
||||
@param handler
|
||||
A new bitmap format handler object. There is usually only one instance
|
||||
of a given handler class in an application session.
|
||||
|
||||
@sa wxBitmapHandler
|
||||
*/
|
||||
static void AddHandler(wxBitmapHandler* handler);
|
||||
|
||||
/**
|
||||
Deletes all bitmap handlers.
|
||||
|
||||
This function is called by wxWidgets on exit.
|
||||
*/
|
||||
static void CleanUpHandlers();
|
||||
|
||||
/**
|
||||
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.
|
||||
*/
|
||||
wxImage ConvertToImage();
|
||||
|
||||
/**
|
||||
Creates the bitmap from an icon.
|
||||
*/
|
||||
bool CopyFromIcon(const wxIcon& icon);
|
||||
|
||||
//@{
|
||||
/**
|
||||
Creates a bitmap from the given data, which can be of arbitrary type.
|
||||
|
||||
@param width
|
||||
The width of the bitmap in pixels.
|
||||
|
||||
@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.
|
||||
|
||||
@param data
|
||||
Data whose type depends on the value of type.
|
||||
|
||||
@param type
|
||||
A bitmap type identifier - see wxBitmap() for a list
|
||||
of possible values.
|
||||
|
||||
@returns @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.
|
||||
|
||||
@sa wxBitmap()
|
||||
*/
|
||||
virtual bool Create(int width, int height, int depth = -1);
|
||||
virtual bool Create(const void* data, int type, int width,
|
||||
int height,
|
||||
int depth = -1);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
Finds the handler associated with the given bitmap type.
|
||||
|
||||
@param name
|
||||
The handler name.
|
||||
|
||||
@param extension
|
||||
The file extension, such as "bmp".
|
||||
|
||||
@param bitmapType
|
||||
The bitmap type, such as wxBITMAP_TYPE_BMP.
|
||||
|
||||
@returns A pointer to the handler if found, @NULL otherwise.
|
||||
|
||||
@sa wxBitmapHandler
|
||||
*/
|
||||
static wxBitmapHandler* FindHandler(const wxString& name);
|
||||
static wxBitmapHandler* FindHandler(const wxString& extension,
|
||||
wxBitmapType bitmapType);
|
||||
static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
|
||||
//@}
|
||||
|
||||
/**
|
||||
Gets the colour depth of the bitmap. A value of 1 indicates a
|
||||
monochrome bitmap.
|
||||
*/
|
||||
int GetDepth();
|
||||
|
||||
/**
|
||||
Returns the static list of bitmap format handlers.
|
||||
|
||||
@sa wxBitmapHandler
|
||||
*/
|
||||
static wxList GetHandlers();
|
||||
|
||||
/**
|
||||
Gets the height of the bitmap in pixels.
|
||||
*/
|
||||
int GetHeight();
|
||||
|
||||
/**
|
||||
Gets the associated mask (if any) which may have been loaded from a file
|
||||
or set for the bitmap.
|
||||
|
||||
@sa SetMask(), wxMask
|
||||
*/
|
||||
wxMask* GetMask();
|
||||
|
||||
/**
|
||||
Gets the associated palette (if any) which may have been loaded from a file
|
||||
or set for the bitmap.
|
||||
|
||||
@sa wxPalette
|
||||
*/
|
||||
wxPalette* GetPalette();
|
||||
|
||||
/**
|
||||
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);
|
||||
|
||||
/**
|
||||
Gets the width of the bitmap in pixels.
|
||||
|
||||
@sa GetHeight()
|
||||
*/
|
||||
int GetWidth();
|
||||
|
||||
/**
|
||||
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.
|
||||
|
||||
@sa wxBitmapHandler
|
||||
*/
|
||||
static void InitStandardHandlers();
|
||||
|
||||
/**
|
||||
Adds a handler at the start of the static list of format handlers.
|
||||
|
||||
@param handler
|
||||
A new bitmap format handler object. There is usually only one instance
|
||||
of a given handler class in an application session.
|
||||
|
||||
@sa wxBitmapHandler
|
||||
*/
|
||||
static void InsertHandler(wxBitmapHandler* handler);
|
||||
|
||||
/**
|
||||
Returns @true if bitmap data is present.
|
||||
*/
|
||||
#define bool IsOk() /* implementation is private */
|
||||
|
||||
/**
|
||||
Loads a bitmap from a file or resource.
|
||||
|
||||
@param name
|
||||
Either a filename or a Windows resource name.
|
||||
The meaning of name is determined by the type parameter.
|
||||
|
||||
@param 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.)
|
||||
|
||||
@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.
|
||||
|
||||
@sa SaveFile()
|
||||
*/
|
||||
bool LoadFile(const wxString& name, wxBitmapType type);
|
||||
|
||||
/**
|
||||
Finds the handler with the given name, and removes it. The handler
|
||||
is not deleted.
|
||||
|
||||
@param name
|
||||
The handler name.
|
||||
|
||||
@returns @true if the handler was found and removed, @false otherwise.
|
||||
|
||||
@sa wxBitmapHandler
|
||||
*/
|
||||
static bool RemoveHandler(const wxString& name);
|
||||
|
||||
/**
|
||||
Saves a bitmap in the named file.
|
||||
|
||||
@param name
|
||||
A filename. The meaning of name is determined by the type parameter.
|
||||
|
||||
@param 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.)
|
||||
|
||||
@param 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.
|
||||
|
||||
@sa LoadFile()
|
||||
*/
|
||||
bool SaveFile(const wxString& name, wxBitmapType type,
|
||||
wxPalette* palette = @NULL);
|
||||
|
||||
/**
|
||||
Sets the depth member (does not affect the bitmap data).
|
||||
|
||||
@param depth
|
||||
Bitmap depth.
|
||||
*/
|
||||
void SetDepth(int depth);
|
||||
|
||||
/**
|
||||
Sets the height member (does not affect the bitmap data).
|
||||
|
||||
@param height
|
||||
Bitmap height in pixels.
|
||||
*/
|
||||
void SetHeight(int height);
|
||||
|
||||
/**
|
||||
Sets the mask for this bitmap.
|
||||
|
||||
@remarks The bitmap object owns the mask once this has been called.
|
||||
|
||||
@sa GetMask(), wxMask
|
||||
*/
|
||||
void SetMask(wxMask* mask);
|
||||
|
||||
/**
|
||||
Sets the associated palette. (Not implemented under GTK+).
|
||||
|
||||
@param palette
|
||||
The palette to set.
|
||||
|
||||
@sa wxPalette
|
||||
*/
|
||||
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_trefcount "reference counting".
|
||||
|
||||
@param bitmap
|
||||
Bitmap to assign.
|
||||
*/
|
||||
wxBitmap operator =(const wxBitmap& bitmap);
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
@class wxMask
|
||||
@wxheader{bitmap.h}
|
||||
|
||||
This class encapsulates a monochrome mask bitmap, where the masked area is
|
||||
black and
|
||||
the unmasked area is white. When associated with a bitmap and drawn in a device
|
||||
context,
|
||||
the unmasked area of the bitmap will be drawn, and the masked area will not be
|
||||
drawn.
|
||||
|
||||
@library{wxcore}
|
||||
@category{gdi}
|
||||
|
||||
@seealso
|
||||
wxBitmap, wxDC::Blit, wxMemoryDC
|
||||
*/
|
||||
class wxMask : public wxObject
|
||||
{
|
||||
public:
|
||||
//@{
|
||||
/**
|
||||
Constructs a mask from a bitmap and a palette index that indicates the
|
||||
background. Not
|
||||
yet implemented for GTK.
|
||||
|
||||
@param bitmap
|
||||
A valid bitmap.
|
||||
|
||||
@param colour
|
||||
A colour specifying the transparency RGB values.
|
||||
|
||||
@param index
|
||||
Index into a palette, specifying the transparency colour.
|
||||
*/
|
||||
wxMask();
|
||||
wxMask(const wxBitmap& bitmap);
|
||||
wxMask(const wxBitmap& bitmap,
|
||||
const wxColour& colour);
|
||||
wxMask(const wxBitmap& bitmap, int index);
|
||||
//@}
|
||||
|
||||
/**
|
||||
Destroys the wxMask object and the underlying bitmap data.
|
||||
*/
|
||||
~wxMask();
|
||||
|
||||
//@{
|
||||
/**
|
||||
Constructs a mask from a bitmap and a palette index that indicates the
|
||||
background. Not
|
||||
yet implemented for GTK.
|
||||
|
||||
@param bitmap
|
||||
A valid bitmap.
|
||||
|
||||
@param colour
|
||||
A colour specifying the transparency RGB values.
|
||||
|
||||
@param index
|
||||
Index into a palette, specifying the transparency colour.
|
||||
*/
|
||||
bool Create(const wxBitmap& bitmap);
|
||||
bool Create(const wxBitmap& bitmap, const wxColour& colour);
|
||||
bool Create(const wxBitmap& bitmap, int index);
|
||||
//@}
|
||||
};
|
||||
Reference in New Issue
Block a user