If the image file contains more than one image and the image handler is capable
of retrieving these individually, this function will return the number of
available images.
-
+
@param stream
Opened input stream for reading image data. Currently, the stream must
support seeking.
-
+
@returns Number of available images. For most image handlers, this is 1
(exceptions are TIFF and ICO formats).
*/
more than one image and the image handler is capable of retrieving these
individually, @e index
indicates which image to read from the stream.
-
+
@param image
The image object which is to be affected by this operation.
@param stream
wxLogMessages.
@param index
The index of the image in the file (starting from zero).
-
+
@returns @true if the operation succeeded, @false otherwise.
-
+
@see wxImage::LoadFile, wxImage::SaveFile, SaveFile()
*/
bool LoadFile(wxImage* image, wxInputStream& stream,
/**
Saves a image in the output stream.
-
+
@param image
The image object which is to be affected by this operation.
@param stream
Opened output stream for writing the data.
-
+
@returns @true if the operation succeeded, @false otherwise.
-
+
@see wxImage::LoadFile, wxImage::SaveFile, LoadFile()
*/
bool SaveFile(wxImage* image, wxOutputStream& stream);
/**
Sets the handler extension.
-
+
@param extension
Handler extension.
*/
/**
Sets the handler MIME type.
-
+
@param mimename
Handler MIME type.
*/
/**
Sets the handler name.
-
+
@param name
Handler name.
*/
/**
@class wxImage
- @ingroup group_class_gdi
@wxheader{image.h}
This class encapsulates a platform-independent image. An image can be created
be drawn in a device context, using wxDC::DrawBitmap.
One colour value of the image may be used as a mask colour which will lead to
- the automatic
- creation of a wxMask object associated to the bitmap object.
+ the automatic creation of a wxMask object associated to the bitmap object.
@library{wxcore}
@category{gdi}
+ @stdobjects
+ ::wxNullImage
+
@see wxBitmap, wxInitAllImageHandlers()
*/
class wxImage : public wxObject
//@{
/**
Creates an image from XPM data.
-
+
@param width
Specifies the width of the image.
@param height
must support seeking.
@param type
May be one of the following:
-
-
-
-
-
-
+
+
+
+
+
+
wxBITMAP_TYPE_BMP
-
-
-
-
+
+
+
+
Load a Windows bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_GIF
-
-
-
-
+
+
+
+
Load a GIF bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_JPEG
-
-
-
-
+
+
+
+
Load a JPEG bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNG
-
-
-
-
+
+
+
+
Load a PNG bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PCX
-
-
-
-
+
+
+
+
Load a PCX bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNM
-
-
-
-
+
+
+
+
Load a PNM bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_TIF
-
-
-
-
+
+
+
+
Load a TIFF bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_TGA
-
-
-
-
+
+
+
+
Load a TGA bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_XPM
-
-
-
-
+
+
+
+
Load a XPM bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ICO
-
-
-
-
+
+
+
+
Load a Windows icon file (ICO).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_CUR
-
-
-
-
+
+
+
+
Load a Windows cursor file (CUR).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ANI
-
-
-
-
+
+
+
+
Load a Windows animated cursor file (ANI).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ANY
-
-
-
-
+
+
+
+
Will try to autodetect the format.
@param mimetype
MIME type string (for example 'image/jpeg')
ICO handler.
@param xpmData
A pointer to XPM image data.
-
+
@remarks Depending on how wxWidgets has been configured, not all formats
may be available.
-
+
@see LoadFile()
*/
wxImage();
pixel
@e blurRadius. This should not be used when using a single mask colour
for transparency.
-
+
@see @ref horzblur() BlurHorizontal, @ref vertblur() BlurVertical
*/
wxImage Blur(int blurRadius);
/**
Blurs the image in the horizontal direction only. This should not be used
when using a single mask colour for transparency.
-
+
@see Blur(), @ref vertblur() BlurVertical
*/
wxImage BlurHorizontal(int blurRadius);
/**
Blurs the image in the vertical direction only. This should not be used
when using a single mask colour for transparency.
-
+
@see Blur(), @ref horzblur() BlurHorizontal
*/
wxImage BlurVertical(int blurRadius);
Computes the histogram of the image. @a histogram is a reference to
wxImageHistogram object. wxImageHistogram is a specialization of
wxHashMap "template" and is defined as follows:
-
+
@returns Returns number of colours in the histogram.
*/
unsigned long ComputeHistogram(wxImageHistogram& histogram) const;
FindFirstUnusedColour().
If the image image doesn't have alpha channel,
ConvertAlphaToMask does nothing.
-
+
@returns @false if FindFirstUnusedColour returns @false, @true otherwise.
*/
bool ConvertAlphaToMask(unsigned char threshold = 128);
Creates a fresh image. If @a clear is @true, the new image will be initialized
to black.
Otherwise, the image data will be uninitialized.
-
+
@param width
The width of the image in pixels.
@param height
The height of the image in pixels.
-
+
@returns @true if the call succeeded, @false otherwise.
*/
bool Create(int width, int height, bool clear = true);
@param startR,startG,startB
Initial values of the colour. Returned colour
will have RGB values equal to or greater than these.
-
+
@returns Returns @false if there is no unused colour left, @true on success.
*/
bool FindFirstUnusedColour(unsigned char* r, unsigned char* g,
//@{
/**
Finds the handler associated with the given MIME type.
-
+
@param name
The handler name.
@param extension
The image type, such as wxBITMAP_TYPE_BMP.
@param mimetype
MIME type.
-
+
@returns A pointer to the handler if found, @NULL otherwise.
-
+
@see wxImageHandler
*/
static wxImageHandler* FindHandler(const wxString& name);
/**
Returns the static list of image format handlers.
-
+
@see wxImageHandler
*/
static wxList GetHandlers();
If the image file contains more than one image and the image handler is capable
of retrieving these individually, this function will return the number of
available images.
-
+
@param name
Name of the file to query.
@param stream
seeking.
@param type
May be one of the following:
-
-
-
-
-
-
+
+
+
+
+
+
wxBITMAP_TYPE_BMP
-
-
-
-
+
+
+
+
Load a Windows bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_GIF
-
-
-
-
+
+
+
+
Load a GIF bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_JPEG
-
-
-
-
+
+
+
+
Load a JPEG bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNG
-
-
-
-
+
+
+
+
Load a PNG bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PCX
-
-
-
-
+
+
+
+
Load a PCX bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNM
-
-
-
-
+
+
+
+
Load a PNM bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_TIF
-
-
-
-
+
+
+
+
Load a TIFF bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_XPM
-
-
-
-
+
+
+
+
Load a XPM bitmap file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ICO
-
-
-
-
+
+
+
+
Load a Windows icon file (ICO).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_CUR
-
-
-
-
+
+
+
+
Load a Windows cursor file (CUR).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ANI
-
-
-
-
+
+
+
+
Load a Windows animated cursor file (ANI).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ANY
-
-
-
-
+
+
+
+
Will try to autodetect the format.
-
+
@returns Number of available images. For most image handlers, this is 1
(exceptions are TIFF and ICO formats).
*/
Iterates all registered wxImageHandler objects, and returns a string containing
file extension masks
suitable for passing to file open/save dialog boxes.
-
+
@returns The format of the returned string is
"(*.ext1;*.ext2)|*.ext1;*.ext2".
-
+
@see wxImageHandler
*/
static wxString GetImageExtWildcard();
Gets a user-defined option. The function is case-insensitive to @e name.
For example, when saving as a JPEG file, the option @b quality is
used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
-
+
@see SetOption(), GetOptionInt(), HasOption()
*/
wxString GetOption(const wxString& name) const;
HasOption() is 0 is a possibly valid value
for the option.
Options for wxPNGHandler
-
+
wxIMAGE_OPTION_PNG_FORMAT
-
+
Format for saving a PNG file.
-
+
wxIMAGE_OPTION_PNG_BITDEPTH
-
+
Bit depth for every channel (R/G/B/A).
-
+
Supported values for wxIMAGE_OPTION_PNG_FORMAT:
-
+
wxPNG_TYPE_COLOUR
-
+
Stores RGB image.
-
+
wxPNG_TYPE_GREY
-
+
Stores grey image, converts from RGB.
-
+
wxPNG_TYPE_GREY_RED
-
+
Stores grey image, uses red value as grey.
-
+
@see SetOption(), GetOption()
*/
int GetOptionInt(const wxString& name) const;
/**
Gets the width of the image in pixels.
-
+
@see GetHeight()
*/
int GetWidth() const;
/**
Returns @true if this image has alpha channel, @false otherwise.
-
+
@see GetAlpha(), SetAlpha()
*/
bool HasAlpha() const;
/**
Returns @true if the given option is present. The function is case-insensitive
to @e name.
-
+
@see SetOption(), GetOption(), GetOptionInt()
*/
bool HasOption(const wxString& name) const;
for the time being, which is used by wxBitmap.
This function is called by wxWidgets on startup, and shouldn't be called by
the user.
-
+
@see wxImageHandler, wxInitAllImageHandlers(), wxQuantize
*/
static void InitStandardHandlers();
/**
Adds a handler at the start of the static list of format handlers.
-
+
@param handler
A new image format handler object. There is usually only one instance
of a given handler class in an application session.
-
+
@see wxImageHandler
*/
static void InsertHandler(wxImageHandler* handler);
//@{
/**
Loads an image from an input stream.
-
+
@param name
Name of the file from which to load the image.
@param stream
must support seeking.
@param type
One of the following values:
-
-
-
-
-
-
+
+
+
+
+
+
wxBITMAP_TYPE_BMP
-
-
-
-
+
+
+
+
Load a Windows image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_GIF
-
-
-
-
+
+
+
+
Load a GIF image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_JPEG
-
-
-
-
+
+
+
+
Load a JPEG image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PCX
-
-
-
-
+
+
+
+
Load a PCX image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNG
-
-
-
-
+
+
+
+
Load a PNG image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNM
-
-
-
-
+
+
+
+
Load a PNM image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_TIF
-
-
-
-
+
+
+
+
Load a TIFF image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_XPM
-
-
-
-
+
+
+
+
Load a XPM image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ICO
-
-
-
-
+
+
+
+
Load a Windows icon file (ICO).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_CUR
-
-
-
-
+
+
+
+
Load a Windows cursor file (CUR).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ANI
-
-
-
-
+
+
+
+
Load a Windows animated cursor file (ANI).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ANY
-
-
-
-
+
+
+
+
Will try to autodetect the format.
@param mimetype
MIME type string (for example 'image/jpeg')
by
the GIF and TIFF handler and as the largest and most colourful one by the
ICO handler.
-
+
@returns @true if the operation succeeded, @false otherwise. If the
optional index parameter is out of range, @false is
returned and a call to wxLogError() takes place.
-
+
@remarks Depending on how wxWidgets has been configured, not all formats
may be available.
-
+
@see SaveFile()
*/
bool LoadFile(const wxString& name,
/**
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.
-
+
@see wxImageHandler
*/
static bool RemoveHandler(const wxString& name);
the image will have the given width and height.
For a description of the @a quality parameter, see the Scale() function.
Returns the (modified) image itself.
-
+
@see Scale()
*/
wxImage Rescale(int width, int height,
then use either the current mask colour if set or find, use, and set a
suitable mask colour for any newly exposed areas.
Returns the (modified) image itself.
-
+
@see Size()
*/
wxImage Resize(const wxSize& size, const wxPoint pos,
//@{
/**
Saves an image in the given stream.
-
+
@param name
Name of the file to save the image to.
@param stream
Opened output stream to save the image to.
@param type
Currently these types can be used:
-
-
-
-
-
-
+
+
+
+
+
+
wxBITMAP_TYPE_BMP
-
-
-
-
+
+
+
+
Save a BMP image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_JPEG
-
-
-
-
+
+
+
+
Save a JPEG image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNG
-
-
-
-
+
+
+
+
Save a PNG image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PCX
-
-
-
-
+
+
+
+
Save a PCX image file (tries to save as 8-bit if possible, falls back to
24-bit otherwise).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_PNM
-
-
-
-
+
+
+
+
Save a PNM image file (as raw RGB always).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_TIFF
-
-
-
-
+
+
+
+
Save a TIFF image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_XPM
-
-
-
-
+
+
+
+
Save a XPM image file.
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_ICO
-
-
-
-
+
+
+
+
Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high.
A single image is saved in 8 colors at the size supplied).
-
-
-
-
-
+
+
+
+
+
wxBITMAP_TYPE_CUR
-
-
-
-
+
+
+
+
Save a Windows cursor file (CUR).
@param mimetype
MIME type.
-
+
@returns @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, int type) const;
image and will therefore remove the mask partially. Using the alpha channel
will work.
Example:
-
+
@param quality
Determines what method to use for resampling the image. Can be one of the
following:
-
-
-
-
-
-
+
+
+
+
+
+
wxIMAGE_QUALITY_NORMAL
-
-
-
-
+
+
+
+
Uses the normal default scaling method of pixel replication
-
-
-
-
-
+
+
+
+
+
wxIMAGE_QUALITY_HIGH
-
-
-
-
+
+
+
+
Uses bicubic and box averaging resampling methods for upsampling and
downsampling respectively
-
+
@see Rescale()
*/
wxImage Scale(int width, int height,
image.
@param mr,mg,mb
RGB value of pixels in mask that will be used to create the mask.
-
+
@returns Returns @false if mask does not have same dimensions as the image
or if there is no unused colour left. Returns @true if
the mask was successfully applied.
Sets a user-defined option. The function is case-insensitive to @e name.
For example, when saving as a JPEG file, the option @b quality is
used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
-
+
@see GetOption(), GetOptionInt(), HasOption()
*/
void SetOption(const wxString& name, const wxString& value);
transparent by filling them with the image mask colour (which will be allocated
automatically if it isn't currently set). Otherwise, the areas will be filled
with the colour with the specified RGB components.
-
+
@see Resize()
*/
wxImage Size(const wxSize& size, const wxPoint pos, int red = -1,
/**
Assignment operator, using @ref overview_trefcount "reference counting".
-
+
@param image
Image to assign.
-
+
@returns Returns 'this' object.
*/
wxImage operator =(const wxImage& image);
};
+/**
+ An empty wxImage.
+*/
+wxImage wxNullImage;
// ============================================================================
// Global functions/macros
// ============================================================================
+/** @ingroup group_funcmacro_appinitterm */
+//@{
+
/**
Initializes all available image handlers. For a list of available handlers,
see wxImage.
@see wxImage, wxImageHandler
+
+ @header{wx/image.h}
*/
void wxInitAllImageHandlers();
+//@}
+
projects / wxWidgets.git / blobdiff