it can be used for basic image manipulation.
A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-specific
-wxBitmap object must be created from it, and that bitmap drawn on the wxDC.
+wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using
+wxDC::DrawBitmap.
\wxheading{Derived from}
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/image.h>
+
\wxheading{See also}
\helpref{wxBitmap}{wxbitmap}
+\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
\latexignore{\rtfignore{\wxheading{Members}}}
\func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
-Constructs an image from a platform-dependent bitmap.
+Constructs 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.
\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
+\func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
+
Loads an image from a file.
+\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
+
+\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
+
+Loads an image from an input stream.
+
\wxheading{Parameters}
\docparam{width}{Specifies the width of the image.}
\docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}
+\docparam{stream}{This refers to an input stream. Its meaning is determined by the {\it type} parameter. It is equal to loading from file except that you provide opened stream (file, HTTP or any other custom class).}
+
\docparam{type}{May be one of the following:
-\twocolwidtha{5cm}
+\twocolwidtha{5cm}%
\begin{twocollist}
\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XBM}}}{Load an X bitmap file.}
-\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_XPM}}}{Load an XPM bitmap file.}
\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_GIF}}}{Load a GIF bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PCX}}}{Load a PCX bitmap file.}
+\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNM}}}{Load a PNM bitmap file.}
\end{twocollist}
The validity of these flags depends on the platform and wxWindows configuration.
-If all possible wxWindows settings are used, the Windows platform supports BMP, BMP\_RESOURCE,
-XPM\_DATA, and XPM. Under X, the available formats are BMP, GIF, XBM, and XPM.}
+If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file,
+a PNG (portable network graphics) file and a JPEG file is supported on all platforms that
+implement wxImage.}
+
+\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
+
+Note : you must call wxImage::AddHandler(new wxJPEGHandler) during application
+initialization in order to work with JPEGs.
\wxheading{See also}
\helpref{wxImage::LoadFile}{wximageloadfile}
+\pythonnote{Constructors supported by wxPython are:\par
+\indented{2cm}{\begin{twocollist}
+\twocolitem{\bf{wxImage(name, flag)}}{Loads an image from a file}
+\twocolitem{\bf{wxNullImage()}}{Create a null image (has no size or
+image data)}
+\twocolitem{\bf{wxEmptyImage(width, height)}}{Creates an empty image
+of the given size}
+\twocolitem{\bf{wxImageFromMime(name, mimetype}}{Creates an image from
+the given file of the given mimetype}
+\twocolitem{\bf{wxImageFromBitmap(bitmap)}}{Creates an image from a
+platform-dependent bitmap}
+\end{twocollist}}
+}
+
\membersection{wxImage::\destruct{wxImage}}
\func{}{\destruct{wxImage}}{\void}
\helpref{wxImageHandler}{wximagehandler}
+\pythonnote{In wxPython this static method is named \tt{wxImage_AddHandler}.}
\membersection{wxImage::CleanUpHandlers}
\func{static void}{CleanUpHandlers}{\void}
\constfunc{wxBitmap}{ConvertToBitmap}{\void}
-Converts the image to a platform-specific bitmap object.
+Converts the image to a platform-specific bitmap object. 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 colour depth of the current system which entails
+that a (crude) colour reduction has to take place. When in 8-bit mode, this
+routine will use a color cube created on program start-up to look up colors.
+Still, the image quality won't be perfect for photo images.
\membersection{wxImage::Create}\label{wximagecreate}
Finds the handler associated with the given image type.
+\func{static wxImageHandler*}{FindHandlerMime}{\param{const wxString\& }{mimetype}}
+
+Finds the handler associated with the given MIME type.
+
\docparam{name}{The handler name.}
\docparam{extension}{The file extension, such as ``bmp".}
\docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
+\docparam{mimetype}{MIME type.}
+
\wxheading{Return value}
A pointer to the handler if found, NULL otherwise.
\constfunc{unsigned char*}{GetData}{\void}
-Returns the image data as an array.
+Returns the image data as an array. This is most often used when doing
+direct image manipulation. The return value points to an array of
+chararcters in RGBGBRGB... format.
\membersection{wxImage::GetGreen}\label{wximagegetgreen}
Gets the red value of the mask colour.
+\membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
+
+\constfunc{wxImage}{GetSubImage}{\param{const wxRect&}{rect}}
+
+Returns a sub image of the current one as long as the rect belongs entirely to
+the image.
+
\membersection{wxImage::GetWidth}\label{wximagegetwidth}
\constfunc{int}{GetWidth}{\void}
\func{static void}{InitStandardHandlers}{\void}
-Adds the standard image format handlers, which, depending on wxWindows
-configuration, can be handlers for Windows image, Windows image resource, and XPM.
+Internal use only. Adds standard image format handlers. It only install BMP
+for the time being, which is use by wxBitmap.
-This function is called by wxWindows on startup.
+This function is called by wxWindows on startup, and shouldn't be called by
+the user.
\wxheading{See also}
\helpref{wxImageHandler}{wximagehandler}
+\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
\membersection{wxImage::InsertHandler}
\membersection{wxImage::LoadFile}\label{wximageloadfile}
-\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}
+\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
-Loads an image from a file.
+\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}}
+
+Loads an image from a file. If no handler type is provided, the library will
+try to use wxBITMAP\_TYPE\_BMP.
+
+\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
+
+\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}}
+
+Loads an image from an input stream.
\wxheading{Parameters}
\docparam{name}{A filename.
The meaning of {\it name} is determined by the {\it type} parameter.}
+\docparam{stream}{An input stream.
+The meaning of {\it stream} data is determined by the {\it type} parameter.}
+
\docparam{type}{One of the following values:
-\twocolwidtha{5cm}
+\twocolwidtha{5cm}%
\begin{twocollist}
\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Load an X image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load an XPM image file.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
\end{twocollist}
The validity of these flags depends on the platform and wxWindows configuration.}
+\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
+
\wxheading{Return value}
TRUE if the operation succeeded, FALSE otherwise.
\helpref{wxImage::SaveFile}{wximagesavefile}
+\pythonnote{In place of a single overloaded method name, wxPython
+implements the following methods:\par
+\indented{2cm}{\begin{twocollist}
+\twocolitem{\bf{LoadFile(filename, type)}}{Loads an image of the given
+type from a file}
+\twocolitem{\bf{LoadMimeFile(filename, mimetype)}}{Loads an image of the given
+mimetype from a file}
+\end{twocollist}}
+}
+
+
\membersection{wxImage::Ok}\label{wximageok}
\constfunc{bool}{Ok}{\void}
\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
+\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
+
Saves a image in the named file.
+\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
+
+\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
+
+Saves a image in the given stream.
+
\wxheading{Parameters}
\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
-\docparam{type}{One of the following values:
+\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
+
+\docparam{type}{Currently two types can be used:
-\twocolwidtha{5cm}
+\twocolwidtha{5cm}%
\begin{twocollist}
-\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a Windows image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Save a GIF image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_XBM}}{Save an X image file.}
-\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save an XPM image file.}
\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
+\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
\end{twocollist}
-The validity of these flags depends on the platform and wxWindows configuration.}
+The validity of these flags depends on the platform and wxWindows configuration
+as well as user-added handlers.}
+
+\docparam{mimetype}{MIME type.}
\wxheading{Return value}
\helpref{wxImage::LoadFile}{wximageloadfile}
+\pythonnote{In place of a single overloaded method name, wxPython
+implements the following methods:\par
+\indented{2cm}{\begin{twocollist}
+\twocolitem{\bf{SaveFile(filename, type)}}{Saves the image using the given
+type to the named file}
+\twocolitem{\bf{SaveMimeFile(filename, mimetype)}}{Saves the image using the given
+mimetype to the named file}
+\end{twocollist}}
+}
+
+\membersection{wxImage::Rescale}\label{wximagerescale}
+
+\func{wxImage}{Rescale}{\param{int}{ width}, \param{int}{ height}}
+
+Changes the size of the image in-place: after a call to this function, the
+image will have the given width and height.
+
+\wxheading{See also}
+
+\helpref{Scale}{wximagescale}
+
\membersection{wxImage::Scale}\label{wximagescale}
-\func{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
+\constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
+
+Returns a scaled version of the image. This is also useful for
+scaling bitmaps in general as the only other way to scale bitmaps
+is to blit a wxMemoryDC into another wxMemoryDC.
+
+It may be mentioned that the GTK post uses this function internally
+to scale bitmaps when using mapping mode in wxDC.
+
+Example:
+
+\begin{verbatim}
+ // get the bitmap from somewhere
+ wxBitmap bmp = ...;
+
+ // rescale it to have size of 32*32
+ if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
+ {
+ wxImage image(bmp);
+ bmp = image.Scale(32, 32).ConvertToBitmap();
+
+ // another possibility:
+ image.Rescale(32, 32);
+ bmp = image;
+ }
+
+\end{verbatim}
-Returns a scaled version of the image.
+\wxheading{See also}
+
+\helpref{Rescale}{wximagerescale}
\membersection{wxImage::SetData}\label{wximagesetdata}
\func{void}{SetData}{\param{unsigned char*}{data}}
-Sets the image data.
+Sets the image data without performing checks. The data given must have
+the size (width*height*3) or results will be unexpected. Don't use this
+method if you aren't sure you know what you are doing.
\membersection{wxImage::SetMask}\label{wximagesetmask}
\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
-Sets the mask colour for this image.
+Sets the mask colour for this image (and tells the image to use the mask).
\membersection{wxImage::SetRGB}\label{wximagesetrgb}
\func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
-Sets the pixel at the given coordinate.
+Sets the pixel at the given coordinate. This routine performs bounds-checks
+for the coordinate so it can be considered a safe way to manipulate the
+data, but in some cases this might be too slow so that the data will have to
+be set directly. In that case you have to get that data by calling GetData().
\membersection{wxImage::operator $=$}
\section{\class{wxImageHandler}}\label{wximagehandler}
-\overview{Overview}{wximageoverview}
-
This is the base class for implementing image file loading/saving, and image creation from data.
It is used within wxImage and is not normally seen by the application.
and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
application initialisation.
+\wxheading{Note (Legal Issue)}
+
+This software is based in part on the work of the Independent JPEG Group.
+
+(Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
+created by IJG.)
+
\wxheading{Derived from}
\helpref{wxObject}{wxobject}
+\wxheading{Include files}
+
+<wx/image.h>
+
\wxheading{See also}
\helpref{wxImage}{wximage}
+\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
\latexignore{\rtfignore{\wxheading{Members}}}
Gets the file extension associated with this handler.
+\membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
+
+\func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
+
+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.
+
+\docparam{stream}{Opened input stream for reading image file.}
+
+\wxheading{Return value}
+
+Number of available images. For most image handles, this defaults to 1.
+
\membersection{wxImageHandler::GetType}
\constfunc{long}{GetType}{\void}
Gets the image type associated with this handler.
+\membersection{wxImageHandler::GetMimeType}
+
+\constfunc{wxString}{GetMimeType}{\void}
+
+Gets the MIME type associated with this handler.
+
\membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
-\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{const wxString\&}{ name}}
+\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=TRUE}, \param{int}{ index=0}}
-Loads a image from a file or resource, putting the resulting data into {\it image}.
+Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
+more than one image and the image handler is capable of retrieving these individually, {\it index}
+indicates which image to read from the stream.
\wxheading{Parameters}
\docparam{image}{The image object which is to be affected by this operation.}
-\docparam{name}{Either a filename or a Windows resource name.
-The meaning of {\it name} is determined by the {\it type} parameter.}
+\docparam{stream}{Opened input stream for reading images.}
+
+\docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.}
+
+\docparam{index}{The index of the image in the file (starting from zero).}
\wxheading{Return value}
\membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
-\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{const wxString\& }{name}}
+\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
-Saves a image in the named file.
+Saves a image in the output stream.
\wxheading{Parameters}
\docparam{image}{The image object which is to be affected by this operation.}
-\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
+\docparam{stream}{An opened stream for writing images.}
\wxheading{Return value}
\docparam{name}{Handler type.}
+\membersection{wxImageHandler::SetMimeType}
+
+\func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
+
+Sets the handler MIME type.
+
+\wxheading{Parameters}
+
+\docparam{mimename}{Handler MIME type.}
+
projects / wxWidgets.git / blobdiff