added optional parameter to SetSizer, to allow replacing a window's

[wxWidgets.git] / docs / latex / wx / image.tex

diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex
index 30c7afb2cbea72ca78d66a6c98baefb9ad9854fd..aa5589fcaca57a9a745356c381036528e8cff95d 100644 (file)
--- a/docs/latex/wx/image.tex
+++ b/docs/latex/wx/image.tex
@@ -33,6 +33,8 @@ handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
 \twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.}
 \twocolitem{\indexit{wxXPMHandler}}{For loading and saving.}
 \twocolitem{\indexit{wxICOHandler}}{For loading and saving.}
 \twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.}
 \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 and saving.}

 \end{twocollist}
 
 When saving in PCX format, {\bf wxPCXHandler} will count the number of
 \end{twocollist}
 
 When saving in PCX format, {\bf wxPCXHandler} will count the number of


@@ -85,15 +87,15 @@ Creates an image from given data with the given width and height. If
 image data in its destructor, otherwise it will free it by calling
 {\it free()}.
 
 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.
 
 
 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.
 
 
 Loads an image from an input stream.
 


@@ -119,12 +121,19 @@ Loads an image from an input stream.
 \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\_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 ICO Icon 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')}
 
 \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 ICO and TIFF handlers. The default value (-1) means 
+"choose the default image" and is interpreted as the first image (index=0) by 
+the 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.
 \wxheading{Remarks}
 
 Depending on how wxWindows has been configured, not all formats may be available.


@@ -133,6 +142,14 @@ Note: any handler other than BMP must be previously
 initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or 
 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
 
 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}
 \wxheading{See also}
 
 \helpref{wxImage::LoadFile}{wximageloadfile}


@@ -188,6 +205,32 @@ Deletes all image handlers.
 
 This function is called by wxWindows on exit.
 
 
 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}
 \membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
 
 \constfunc{wxBitmap}{ConvertToBitmap}{\void}


@@ -309,6 +352,43 @@ chararcters in RGBGBRGB... format.
 
 Returns the green intensity at the given coordinate.
 
 
 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}}
 \membersection{wxImage::GetRed}\label{wximagegetred}
 
 \constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}


@@ -450,16 +530,16 @@ of a given handler class in an application session.}
 
 \membersection{wxImage::LoadFile}\label{wximageloadfile}
 
 
 \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.
 
 
 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.
 
 
 Loads an image from an input stream.
 


@@ -481,17 +561,30 @@ Loads an image from an input stream.
 \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\_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 ICO icon 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')}
 
 \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 ICO and TIFF handlers. The default value (-1) means 
+"choose the default image" and is interpreted as the first image (index=0) by 
+the 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.
 
 \wxheading{Remarks}
 
 Depending on how wxWindows has been configured, not all formats may be available.
 

-wxBITMAP\_TYPE\_ICO will laod the largest image found, with the most colours
+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}
 
 
 \wxheading{Return value}
 


@@ -544,15 +637,15 @@ TRUE if the handler was found and removed, FALSE otherwise.
 
 \membersection{wxImage::SaveFile}\label{wximagesavefile}
 
 
 \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}}

 
 

-\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
+\constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}

 
 Saves a image in the named file.
 
 
 Saves a image in the named file.
 

-\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 a image in the given stream.
 


@@ -572,7 +665,9 @@ Saves a image in the given stream.
 \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\_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 ICO image file. (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\_ICO}}{Save a ICO 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.}
 \end{twocollist}}
 
 \docparam{mimetype}{MIME type.}


@@ -585,6 +680,15 @@ TRUE if the operation succeeded, FALSE otherwise.
 
 Depending on how wxWindows has been configured, not all formats may be available.
 
 
 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}
 \wxheading{See also}
 
 \helpref{wxImage::LoadFile}{wximageloadfile}


@@ -881,7 +985,8 @@ available images.
 
 \wxheading{Return value}
 
 
 \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}
 
 
 \membersection{wxImageHandler::GetType}