Changes for 16-bit BC++ (not there yet), GnuWin32; typetest sample

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

\section{\class{wxImage}}\label{wximage}

This class encapsulates a platform-independent image. An image can be created
from data, or using the constructor taking a wxBitmap object. An image
can be loaded from a file in a variety of formats, and is extensible to new formats
via image format handlers. Functions are available to set and get image bits, so
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.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{See also}

\helpref{wxBitmap}{wxbitmap}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxImage::wxImage}\label{wximageconstr}

\func{}{wxImage}{\void}

Default constructor.

\func{}{wxImage}{\param{const wxImage\& }{image}}

Copy constructor.

\func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}

Constructs an image from a platform-dependent bitmap.

\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}

Creates an image with the given width and height.

\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}

Loads an image from a file.

\wxheading{Parameters}

\docparam{width}{Specifies the width of the image.}

\docparam{height}{Specifies the height of the image.}

\docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}

\docparam{type}{May be one of the following:

\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.}
\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.}

\wxheading{See also}

\helpref{wxImage::LoadFile}{wximageloadfile}

\membersection{wxImage::\destruct{wxImage}}

\func{}{\destruct{wxImage}}{\void}

Destructor.

\membersection{wxImage::AddHandler}\label{wximageaddhandler}

\func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}

Adds a handler to the end of the static list of format handlers.

\docparam{handler}{A new image format handler object. There is usually only one instance
of a given handler class in an application session.}

\wxheading{See also}

\helpref{wxImageHandler}{wximagehandler}

\membersection{wxImage::CleanUpHandlers}

\func{static void}{CleanUpHandlers}{\void}

Deletes all image handlers.

This function is called by wxWindows on exit.

\membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}

\constfunc{wxBitmap}{ConvertToBitmap}{\void}

Converts the image to a platform-specific bitmap object.

\membersection{wxImage::Create}\label{wximagecreate}

\func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}

Creates a fresh image.

\wxheading{Parameters}

\docparam{width}{The width of the image in pixels.}

\docparam{height}{The height of the image in pixels.}

\wxheading{Return value}

TRUE if the call succeeded, FALSE otherwise.

\membersection{wxImage::Destroy}\label{wximagedestroy}

\func{bool}{Destroy}{\void}

Destroys the image data.

\membersection{wxImage::FindHandler}

\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}

Finds the handler with the given name.

\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}

Finds the handler associated with the given extension and type.

\func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}

Finds the handler associated with the given image type.

\docparam{name}{The handler name.}

\docparam{extension}{The file extension, such as ``bmp".}

\docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}

\wxheading{Return value}

A pointer to the handler if found, NULL otherwise.

\wxheading{See also}

\helpref{wxImageHandler}{wximagehandler}

\membersection{wxImage::GetBlue}\label{wximagegetblue}

\constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}

Returns the blue intensity at the given coordinate.

\membersection{wxImage::GetData}\label{wximagegetdata}

\constfunc{unsigned char*}{GetData}{\void}

Returns the image data as an array.

\membersection{wxImage::GetGreen}\label{wximagegetgreen}

\constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}

Returns the green intensity at the given coordinate.

\membersection{wxImage::GetRed}\label{wximagegetred}

\constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}

Returns the red intensity at the given coordinate.

\membersection{wxImage::GetHandlers}

\func{static wxList\&}{GetHandlers}{\void}

Returns the static list of image format handlers.

\wxheading{See also}

\helpref{wxImageHandler}{wximagehandler}

\membersection{wxImage::GetHeight}\label{wximagegetheight}

\constfunc{int}{GetHeight}{\void}

Gets the height of the image in pixels.

\membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}

\constfunc{unsigned char}{GetMaskBlue}{\void}

Gets the blue value of the mask colour.

\membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}

\constfunc{unsigned char}{GetMaskGreen}{\void}

Gets the green value of the mask colour.

\membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}

\constfunc{unsigned char}{GetMaskRed}{\void}

Gets the red value of the mask colour.

\membersection{wxImage::GetWidth}\label{wximagegetwidth}

\constfunc{int}{GetWidth}{\void}

Gets the width of the image in pixels.

\wxheading{See also}

\helpref{wxImage::GetHeight}{wximagegetheight}

\membersection{wxImage::HasMask}\label{wximagehasmask}

\constfunc{bool}{HasMask}{\void}

Returns TRUE if there is a mask active, FALSE otherwise.

\membersection{wxImage::InitStandardHandlers}

\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.

This function is called by wxWindows on startup.

\wxheading{See also}

\helpref{wxImageHandler}{wximagehandler}

\membersection{wxImage::InsertHandler}

\func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}

Adds a handler at the start of the static list of format handlers.

\docparam{handler}{A new image format handler object. There is usually only one instance
of a given handler class in an application session.}

\wxheading{See also}

\helpref{wxImageHandler}{wximagehandler}

\membersection{wxImage::LoadFile}\label{wximageloadfile}

\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}

Loads an image from a file.

\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:

\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\_PNG}}{Load a PNG image file.}
\end{twocollist}

The validity of these flags depends on the platform and wxWindows configuration.}

\wxheading{Return value}

TRUE if the operation succeeded, FALSE otherwise.

\wxheading{See also}

\helpref{wxImage::SaveFile}{wximagesavefile}

\membersection{wxImage::Ok}\label{wximageok}

\constfunc{bool}{Ok}{\void}

Returns TRUE if image data is present.

\membersection{wxImage::RemoveHandler}

\func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}

Finds the handler with the given name, and removes it. The handler
is not deleted.

\docparam{name}{The handler name.}

\wxheading{Return value}

TRUE if the handler was found and removed, FALSE otherwise.

\wxheading{See also}

\helpref{wxImageHandler}{wximagehandler}

\membersection{wxImage::SaveFile}\label{wximagesavefile}

\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}

Saves a image in the named file.

\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:

\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.}
\end{twocollist}

The validity of these flags depends on the platform and wxWindows configuration.}

\wxheading{Return value}

TRUE if the operation succeeded, FALSE otherwise.

\wxheading{Remarks}

Depending on how wxWindows has been configured, not all formats may be available.

\wxheading{See also}

\helpref{wxImage::LoadFile}{wximageloadfile}

\membersection{wxImage::Scale}\label{wximagescale}

\func{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}

Returns a scaled version of the image.

\membersection{wxImage::SetData}\label{wximagesetdata}

\func{void}{SetData}{\param{unsigned char*}{data}}

Sets the image data.

\membersection{wxImage::SetMask}\label{wximagesetmask}

\func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}

Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.

\membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}

\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}

Sets the mask colour for this image.

\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.

\membersection{wxImage::operator $=$}

\func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}

Assignment operator. This operator does not copy any data, but instead
passes a pointer to the data in {\it image} and increments a reference
counter. It is a fast operation.

\wxheading{Parameters}

\docparam{image}{Image to assign.}

\wxheading{Return value}

Returns 'this' object.

\membersection{wxImage::operator $==$}

\func{bool}{operator $==$}{\param{const wxImage\& }{image}}

Equality operator. This operator tests whether the internal data pointers are
equal (a fast test).

\wxheading{Parameters}

\docparam{image}{Image to compare with 'this'}

\wxheading{Return value}

Returns TRUE if the images were effectively equal, FALSE otherwise.

\membersection{wxImage::operator $!=$}

\func{bool}{operator $!=$}{\param{const wxImage\& }{image}}

Inequality operator. This operator tests whether the internal data pointers are
unequal (a fast test).

\wxheading{Parameters}

\docparam{image}{Image to compare with 'this'}

\wxheading{Return value}

Returns TRUE if the images were unequal, FALSE otherwise.

\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.

If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
application initialisation.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{See also}

\helpref{wxImage}{wximage}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}

\func{}{wxImageHandler}{\void}

Default constructor. In your own default constructor, initialise the members
m\_name, m\_extension and m\_type.

\membersection{wxImageHandler::\destruct{wxImageHandler}}

\func{}{\destruct{wxImageHandler}}{\void}

Destroys the wxImageHandler object.

\membersection{wxImageHandler::GetName}

\constfunc{wxString}{GetName}{\void}

Gets the name of this handler.

\membersection{wxImageHandler::GetExtension}

\constfunc{wxString}{GetExtension}{\void}

Gets the file extension associated with this handler.

\membersection{wxImageHandler::GetType}

\constfunc{long}{GetType}{\void}

Gets the image type associated with this handler.

\membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}

\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{const wxString\&}{ name}}

Loads a image from a file or resource, 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.}

\wxheading{Return value}

TRUE if the operation succeeded, FALSE otherwise.

\wxheading{See also}

\helpref{wxImage::LoadFile}{wximageloadfile}\\
\helpref{wxImage::SaveFile}{wximagesavefile}\\
\helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}

\membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}

\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{const wxString\& }{name}}

Saves a image in the named file.

\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.}

\wxheading{Return value}

TRUE if the operation succeeded, FALSE otherwise.

\wxheading{See also}

\helpref{wxImage::LoadFile}{wximageloadfile}\\
\helpref{wxImage::SaveFile}{wximagesavefile}\\
\helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}

\membersection{wxImageHandler::SetName}

\func{void}{SetName}{\param{const wxString\& }{name}}

Sets the handler name.

\wxheading{Parameters}

\docparam{name}{Handler name.}

\membersection{wxImageHandler::SetExtension}

\func{void}{SetExtension}{\param{const wxString\& }{extension}}

Sets the handler extension.

\wxheading{Parameters}

\docparam{extension}{Handler extension.}

\membersection{wxImageHandler::SetType}

\func{void}{SetType}{\param{long }{type}}

Sets the handler type.

\wxheading{Parameters}

\docparam{name}{Handler type.}