X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b06a6b20d51183027f4d76695c836c79fa924979..2245b2b2c3339ecf023e5880caa803610a5d1907:/docs/latex/wx/image.tex diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex index 7f9b666f14..574391e7c1 100644 --- a/docs/latex/wx/image.tex +++ b/docs/latex/wx/image.tex @@ -24,13 +24,18 @@ handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or \twocolwidtha{5cm}% \begin{twocollist} -\twocolitem{\indexit{wxBMPHandler}}{Only for loading, always installed.} +\twocolitem{\indexit{wxBMPHandler}}{For loading and saving, always installed.} \twocolitem{\indexit{wxPNGHandler}}{For loading and saving.} \twocolitem{\indexit{wxJPEGHandler}}{For loading and saving.} \twocolitem{\indexit{wxGIFHandler}}{Only for loading, due to legal issues.} \twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).} \twocolitem{\indexit{wxPNMHandler}}{For loading and saving (see below).} -\twocolitem{\indexit{wxTIFFHandler}}{For loading.} +\twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.} +\twocolitem{\indexit{wxIFFHandler}}{For loading only.} +\twocolitem{\indexit{wxXPMHandler}}{For loading and saving.} +\twocolitem{\indexit{wxICOHandler}}{For loading and saving.} +\twocolitem{\indexit{wxCURHandler}}{For loading and saving.} +\twocolitem{\indexit{wxANIHandler}}{For loading only.} \end{twocollist} When saving in PCX format, {\bf wxPCXHandler} will count the number of @@ -76,22 +81,22 @@ and forth without loss in that respect. Creates an image with the given width and height. -\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static_data=FALSE}} +\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static\_data=FALSE}} Creates an image from given data with the given width and height. If -{\it static_data} is TRUE, then wxImage will not delete the actual +{\it static\_data} is TRUE, then wxImage will not delete the actual image data in its destructor, otherwise it will free it by calling {\it free()}. -\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}} +\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}} -\func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}} +\func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}} Loads an image from a file. -\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}} +\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}} -\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}} +\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}} Loads an image from an input stream. @@ -116,11 +121,20 @@ Loads an image from an input stream. \twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.} \twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.} \twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).} +\twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).} +\twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).} \twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.} \end{twocollist}} \docparam{mimetype}{MIME type string (for example 'image/jpeg')} +\docparam{index}{Index of the image to load in the case that the image file contains multiple images. +This is only used by GIF, ICO and TIFF handlers. The default value (-1) means +"choose the default image" and is interpreted as the first image (index=0) by +the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.} + \wxheading{Remarks} Depending on how wxWindows has been configured, not all formats may be available. @@ -129,6 +143,14 @@ Note: any handler other than BMP must be previously initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}. +Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the +hotspot for loaded cursor file: +\begin{verbatim} + int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X); + int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y); + +\end{verbatim} + \wxheading{See also} \helpref{wxImage::LoadFile}{wximageloadfile} @@ -175,7 +197,11 @@ of a given handler class in an application session.} \helpref{wxImageHandler}{wximagehandler} -\pythonnote{In wxPython this static method is named {\tt wxImage_AddHandler}.} +\func{bool}{CanRead}{\param{const wxString\&}{ filename}} + +returns TRUE if the current image handlers can read this file + +\pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.} \membersection{wxImage::CleanUpHandlers} \func{static void}{CleanUpHandlers}{\void} @@ -184,6 +210,32 @@ Deletes all image handlers. This function is called by wxWindows on exit. +\membersection{wxImage::ComputeHistogram}\label{wximagecomputehistogram} + +\constfunc{unsigned long}{ComputeHistogram}{\param{wxImageHistogram\& }{histogram}} + +Computes the histogram of the image. {\it histogram} is a reference to +wxImageHistogram object. wxImageHistogram is a specialization of +\helpref{wxHashMap}{wxhashmap} "template" and is defined as follows: + +\begin{verbatim} +class WXDLLEXPORT wxImageHistogramEntry +{ +public: + wxImageHistogramEntry() : index(0), value(0) {} + unsigned long index; + unsigned long value; +}; + +WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry, + wxIntegerHash, wxIntegerEqual, + wxImageHistogram); +\end{verbatim} + +\wxheading{Return value} + +Returns number of colours in the histogram. + \membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap} \constfunc{wxBitmap}{ConvertToBitmap}{\void} @@ -227,6 +279,30 @@ TRUE if the call succeeded, FALSE otherwise. Destroys the image data. +\membersection{wxImage::FindFirstUnusedColour}\label{wximagefindfirstunusedcolour} + +\func{bool}{FindFirstUnusedColour}{\param{unsigned char *}{ r}, \param{unsigned char *}{ g}, \param{unsigned char *}{ b}, \param{unsigned char}{ startR = 1}, \param{unsigned char}{ startG = 0}, \param{unsigned char}{ startB = 0}} + +\wxheading{Parameters} + +\docparam{r,g,b}{Pointers to variables to save the colour.} + +\docparam{startR,startG,startB}{Initial values of the colour. Returned colour +will have RGB values equal to or greater than these.} + +Finds the first colour that is never used in the image. The search begins at +given initial colour and continues by increasing R, G and B components (in this +order) by 1 until an unused colour is found or the colour space exhausted. + +\wxheading{Return value} + +Returns FALSE if there is no unused colour left, TRUE on success. + +\wxheading{Notes} + +Note that this method involves computing the histogram, which is +computationally intensive operation. + \membersection{wxImage::FindHandler} \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}} @@ -281,6 +357,43 @@ chararcters in RGBGBRGB... format. Returns the green intensity at the given coordinate. +\membersection{wxImage::GetImageCount}\label{wximagegetimagecount} + +\func{static int}{GetImageCount}{\param{const wxString\&}{ filename}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}} + +\func{static int}{GetImageCount}{\param{wxInputStream\&}{ stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}} + +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{name}{Name of the file to query.} + +\docparam{stream}{Opened input stream with image data. Currently, the stream must support seeking.} + +\docparam{type}{May be one of the following: + +\twocolwidtha{5cm}% +\begin{twocollist} +\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.} +\twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).} +\twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).} +\twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).} +\twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.} +\end{twocollist}} + +\wxheading{Return value} + +Number of available images. For most image handlers, this is 1 (exceptions +are TIFF and ICO formats). + \membersection{wxImage::GetRed}\label{wximagegetred} \constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}} @@ -422,16 +535,16 @@ of a given handler class in an application session.} \membersection{wxImage::LoadFile}\label{wximageloadfile} -\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}} +\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}} -\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}} +\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}} Loads an image from a file. If no handler type is provided, the library will try to autodetect the format. -\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}} +\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}, \param{int}{ index = -1}} -\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}} +\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}} Loads an image from an input stream. @@ -452,18 +565,36 @@ Loads an image from an input stream. \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load a XPM image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).} +\twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).} +\twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).} \twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.} \end{twocollist}} \docparam{mimetype}{MIME type string (for example 'image/jpeg')} +\docparam{index}{Index of the image to load in the case that the image file contains multiple images. +This is only used by GIF, ICO and TIFF handlers. The default value (-1) means +"choose the default image" and is interpreted as the first image (index=0) by +the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.} + \wxheading{Remarks} Depending on how wxWindows has been configured, not all formats may be available. +Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the +hotspot for loaded cursor file: +\begin{verbatim} + int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X); + int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y); + +\end{verbatim} + \wxheading{Return value} -TRUE if the operation succeeded, FALSE otherwise. +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. \wxheading{See also} @@ -512,17 +643,23 @@ TRUE if the handler was found and removed, FALSE otherwise. \membersection{wxImage::SaveFile}\label{wximagesavefile} -\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}} +\constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}} + +\constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}} + +Saves an image in the named file. -\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}} +\constfunc{bool}{SaveFile}{\param{const wxString\& }{name}} -Saves a image in the named file. +Saves an image in the named file. File type is determined from the extension of the +file name. Note that this function may fail if the extension is not recognized! You +can use one of the forms above to save images to files with non-standard extensions. -\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}} +\constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}} -\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}} +\constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}} -Saves a image in the given stream. +Saves an image in the given stream. \wxheading{Parameters} @@ -530,14 +667,19 @@ Saves a image in the given stream. \docparam{stream}{Opened output stream to save the image to.} -\docparam{type}{Currently three types can be used: +\docparam{type}{Currently these types can be used: \twocolwidtha{5cm}% \begin{twocollist} +\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a BMP image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.} \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).} \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).} +\twocolitem{{\bf wxBITMAP\_TYPE\_TIFF}}{Save a TIFF image file.} +\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save a XPM image file.} +\twocolitem{{\bf 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).} +\twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Save a Windows cursor file (CUR).} \end{twocollist}} \docparam{mimetype}{MIME type.} @@ -550,6 +692,15 @@ TRUE if the operation succeeded, FALSE otherwise. Depending on how wxWindows has been configured, not all formats may be available. +Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the +hotspot before saving an image into a cursor file (default hotspot is in +the centre of the image): +\begin{verbatim} + image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX); + image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY); + +\end{verbatim} + \wxheading{See also} \helpref{wxImage::LoadFile}{wximageloadfile} @@ -671,6 +822,33 @@ Specifies whether there is a mask or not. The area of the mask is determined by Sets the mask colour for this image (and tells the image to use the mask). +\membersection{wxImage::SetMaskFromImage}\label{wximagesetmaskfromimage} + +\func{bool}{SetMaskFromImage}{\param{const wxImage\&}{ mask}, \param{unsigned char}{ mr}, \param{unsigned char}{ mg}, \param{unsigned char}{ mb}} + +\wxheading{Parameters} + +\docparam{mask}{The mask image to extract mask shape from. Must have same dimensions as the image.} + +\docparam{mr,mg,mb}{RGB value of pixels in {\it mask} that will be used to create the mask.} + +Sets image's mask so that the pixels that have RGB value of {\it mr,mg,mb} +in {\it mask} will be masked in the image. This is done by first finding an +unused colour in the image, setting this colour as the mask colour and then +using this colour to draw all pixels in the image who corresponding pixel +in {\it mask} has given RGB value. + +\wxheading{Return value} + +Returns FALSE if {\it 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. + +\wxheading{Notes} + +Note that this method involves computing the histogram, which is +computationally intensive operation. + \membersection{wxImage::SetOption}\label{wximagesetoption} \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}} @@ -819,7 +997,8 @@ available images. \wxheading{Return value} -Number of available images. For most image handles, this defaults to 1. +Number of available images. For most image handlers, this is 1 (exceptions +are TIFF and ICO formats). \membersection{wxImageHandler::GetType}