X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12a44087e448071f9f108208a0a88e908d543d44..8a729bb860cec596f4ce5a59fabeb4404a266e97:/docs/latex/wx/image.tex diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex index 281fd8a7e1..1366f12d04 100644 --- a/docs/latex/wx/image.tex +++ b/docs/latex/wx/image.tex @@ -10,15 +10,18 @@ A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-sp wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using wxDC::DrawBitmap. -This class is currently only available under GTK and Windows. - \wxheading{Derived from} \helpref{wxObject}{wxobject} +\wxheading{Include files} + + + \wxheading{See also} \helpref{wxBitmap}{wxbitmap} +\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} \latexignore{\rtfignore{\wxheading{Members}}} @@ -42,10 +45,18 @@ and forth without loss in that respect. Creates an image with the given width and height. -\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxIMAGE\_TYPE\_PNG}} +\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.} @@ -54,23 +65,45 @@ Loads an image from a file. \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{wxIMAGE\_TYPE\_BMP}}}{Load a Windows bitmap file.} -\twocolitem{{\bf \indexit{wxIMAGE\_TYPE\_PNG}}}{Load a PNG bitmap file.} +\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.} +\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.} +\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.} \end{twocollist} The validity of these flags depends on the platform and wxWindows configuration. -If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file -and a PNG (portable network graphics) file is supported on all platforms that +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} @@ -90,6 +123,7 @@ of a given handler class in an application session.} \helpref{wxImageHandler}{wximagehandler} +\pythonnote{In wxPython this static method is named \tt{wxImage_AddHandler}.} \membersection{wxImage::CleanUpHandlers} \func{static void}{CleanUpHandlers}{\void} @@ -105,10 +139,9 @@ This function is called by wxWindows on exit. 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. Especially when converting -to 8-bit (or even less) bitmaps, the routine is slow and will reduce the -quality of the resulting bitmap. A proper set of colour reduction methods has -not yet been written. +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} @@ -146,11 +179,17 @@ Finds the handler associated with the given extension and type. 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 wxIMAGE\_TYPE\_BMP.} +\docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.} + +\docparam{mimetype}{MIME type.} \wxheading{Return value} @@ -220,6 +259,13 @@ Gets the green value of the mask colour. 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} @@ -240,15 +286,16 @@ Returns TRUE if there is a mask active, FALSE otherwise. \func{static void}{InitStandardHandlers}{\void} -Adds the standard image format handlers, which, depending on wxWindows -configuration, can be handlers for Windows BMP (loading) and PNG -(loading and saving) file formats. +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} @@ -265,25 +312,43 @@ of a given handler class in an application session.} \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 wxIMAGE\_TYPE\_BMP}}{Load a Windows image file.} -\twocolitem{{\bf wxIMAGE\_TYPE\_PNG}}{Load a PNG image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF 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. @@ -292,6 +357,17 @@ 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} @@ -319,22 +395,35 @@ TRUE if the handler was found and removed, FALSE otherwise. \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}{Currently only one type can be used: +\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 wxIMAGE\_TYPE\_PNG}}{Save a PNG 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 as well as user-added handlers.} +\docparam{mimetype}{MIME type.} + \wxheading{Return value} TRUE if the operation succeeded, FALSE otherwise. @@ -347,21 +436,66 @@ Depending on how wxWindows has been configured, not all formats may be available \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 do blit a wxMemoryDC into another wxMemoryDC. Windows can such scaling -itself, but on GTK scaling bitmaps is done using this routine -internally. +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} + +\wxheading{See also} + +\helpref{Rescale}{wximagerescale} \membersection{wxImage::SetData}\label{wximagesetdata} \func{void}{SetData}{\param{unsigned char*}{data}} -Sets the image data without performing checks. The data given must have +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. @@ -375,7 +509,7 @@ Specifies whether there is a mask or not. The area of the mask is determined by \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} @@ -441,13 +575,25 @@ If you wish to extend the capabilities of wxImage, derive a class from wxImageHa 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} + + + \wxheading{See also} \helpref{wxImage}{wximage} +\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers} \latexignore{\rtfignore{\wxheading{Members}}} @@ -482,18 +628,24 @@ Gets the file extension associated with this handler. 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}} -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}. \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. +The meaning of {\it stream} is determined by the {\it type} parameter.} \wxheading{Return value} @@ -507,15 +659,15 @@ TRUE if the operation succeeded, FALSE otherwise. \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}{A stream. The meaning of {\it stream} is determined by the {\it type} parameter.} \wxheading{Return value} @@ -558,3 +710,13 @@ Sets the handler type. \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.} +