update for 2.6.0 from Martin Srebotnjak

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

\section{\class{wxImageList}}\label{wximagelist}

A wxImageList contains a list of images, which are stored in
an unspecified form. Images can have masks for transparent
drawing, and can be made from a variety of sources including bitmaps
and icons.

wxImageList is used principally in conjunction with \helpref{wxTreeCtrl}{wxtreectrl} and
\rtfsp\helpref{wxListCtrl}{wxlistctrl} classes.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/imaglist.h>

\wxheading{See also}

\helpref{wxTreeCtrl}{wxtreectrl}, \helpref{wxListCtrl}{wxlistctrl}

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

\membersection{wxImageList::wxImageList}\label{wximagelistconstr}

\func{}{wxImageList}{\void}

Default constructor.

\func{}{wxImageList}{\param{int }{width}, \param{int }{height}, \param{const bool }{mask = true},\rtfsp
\param{int }{initialCount = 1}}

Constructor specifying the image size, whether image masks should be created, and the initial size of the list.

\wxheading{Parameters}

\docparam{width}{Width of the images in the list.}

\docparam{height}{Height of the images in the list.}

\docparam{mask}{true if masks should be created for all images.}

\docparam{initialCount}{The initial size of the list.}

\wxheading{See also}

\helpref{wxImageList::Create}{wximagelistcreate}

\membersection{wxImageList::Add}\label{wximagelistadd}

\func{int}{Add}{\param{const wxBitmap\&}{ bitmap}, \param{const wxBitmap\&}{ mask = wxNullBitmap}}

Adds a new image using a bitmap and optional mask bitmap.

\func{int}{Add}{\param{const wxBitmap\&}{ bitmap}, \param{const wxColour\&}{ maskColour}}

Adds a new image using a bitmap and mask colour.

\func{int}{Add}{\param{const wxIcon\&}{ icon}}

Adds a new image using an icon.

\wxheading{Parameters}

\docparam{bitmap}{Bitmap representing the opaque areas of the image.}

\docparam{mask}{Monochrome mask bitmap, representing the transparent areas of the image.}

\docparam{maskColour}{Colour indicating which parts of the image are transparent.}

\docparam{icon}{Icon to use as the image.}

\wxheading{Return value}

The new zero-based image index.

\wxheading{Remarks}

The original bitmap or icon is not affected by the {\bf Add} operation, and can be deleted afterwards.

\pythonnote{In place of a single overloaded method name, wxPython
implements the following methods:\par
\indented{2cm}{\begin{twocollist}
\twocolitem{{\bf Add(bitmap, mask=wxNullBitmap)}}{}
\twocolitem{{\bf AddWithColourMask(bitmap, colour)}}{}
\twocolitem{{\bf AddIcon(icon)}}{}
\end{twocollist}}
}
\membersection{wxImageList::Create}\label{wximagelistcreate}

\func{bool}{Create}{\param{int }{width}, \param{int }{height}, \param{const bool }{mask = true},\rtfsp
\param{int }{initialCount = 1}}

Initializes the list. See \helpref{wxImageList::wxImageList}{wximagelistconstr} for details.

\membersection{wxImageList::Draw}\label{wximagelistdraw}

\func{bool}{Draw}{\param{int}{ index}, \param{wxDC\&}{ dc}, \param{int }{x},\rtfsp
\param{int }{y}, \param{int }{flags = wxIMAGELIST\_DRAW\_NORMAL},\rtfsp
\param{const bool }{solidBackground = false}}

Draws a specified image onto a device context.

\wxheading{Parameters}

\docparam{index}{Image index, starting from zero.}

\docparam{dc}{Device context to draw on.}

\docparam{x}{X position on the device context.}

\docparam{y}{Y position on the device context.}

\docparam{flags}{How to draw the image. A bitlist of a selection of the following:

\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxIMAGELIST\_DRAW\_NORMAL}}{Draw the image normally.}
\twocolitem{{\bf wxIMAGELIST\_DRAW\_TRANSPARENT}}{Draw the image with transparency.}
\twocolitem{{\bf wxIMAGELIST\_DRAW\_SELECTED}}{Draw the image in selected state.}
\twocolitem{{\bf wxIMAGELIST\_DRAW\_FOCUSED}}{Draw the image in a focused state.}
\end{twocollist}
}

\docparam{solidBackground}{For optimisation - drawing can be faster if the function is told
that the background is solid.}

\membersection{wxImageList::GetBitmap}\label{wximagelistgetbitmap}

\constfunc{wxBitmap}{GetBitmap}{\param{int }{index}}

Returns the bitmap corresponding to the given index.

\membersection{wxImageList::GetIcon}\label{wximagelistgeticon}

\constfunc{wxIcon}{GetIcon}{\param{int }{index}}

Returns the icon corresponding to the given index.

\membersection{wxImageList::GetImageCount}\label{wximagelistgetimagecount}

\constfunc{int}{GetImageCount}{\void}

Returns the number of images in the list.

\membersection{wxImageList::GetSize}\label{wximagelistgetsize}

\constfunc{bool}{GetSize}{\param{int }{index}, \param{int\& }{width}, \param{int \&}{height}}

Retrieves the size of the images in the list. Currently, the {\it index} 
parameter is ignored as all images in the list have the same size.

\wxheading{Parameters}

\docparam{index}{currently unused, should be 0}

\docparam{width}{receives the width of the images in the list}

\docparam{height}{receives the height of the images in the list}

\wxheading{Return value}

true if the function succeeded, false if it failed (for example, if the image
list was not yet initialized).

\membersection{wxImageList::Remove}\label{wximagelistremove}

\func{bool}{Remove}{\param{int}{ index}}

Removes the image at the given position.

\membersection{wxImageList::RemoveAll}\label{wximagelistremoveall}

\func{bool}{RemoveAll}{\void}

Removes all the images in the list.

\membersection{wxImageList::Replace}\label{wximagelistreplace}

\func{bool}{Replace}{\param{int}{ index}, \param{const wxBitmap\&}{ bitmap}, \param{const wxBitmap\&}{ mask = wxNullBitmap}}

Replaces the existing image with the new image.

Windows only.

\func{bool}{Replace}{\param{int}{ index}, \param{const wxIcon\&}{ icon}}

Replaces the existing image with the new image.

\wxheading{Parameters}

\docparam{bitmap}{Bitmap representing the opaque areas of the image.}

\docparam{mask}{Monochrome mask bitmap, representing the transparent areas of the image.}

\docparam{icon}{Icon to use as the image.}

\wxheading{Return value}

true if the replacement was successful, false otherwise.

\wxheading{Remarks}

The original bitmap or icon is not affected by the {\bf Replace} operation, and can be deleted afterwards.

\pythonnote{The second form is called {\tt ReplaceIcon} in wxPython.}