docs/latex/wx/imaglist.tex

   1 \section{\class{wxImageList}}\label{wximagelist}
   2
   3 A wxImageList contains a list of images, which are stored in
   4 an unspecified form. Images can have masks for transparent
   5 drawing, and can be made from a variety of sources including bitmaps
   6 and icons.
   7
   8 wxImageList is used principally in conjunction with \helpref{wxTreeCtrl}{wxtreectrl} and
   9 \rtfsp\helpref{wxListCtrl}{wxlistctrl} classes.
  10
  11 \wxheading{Derived from}
  12
  13 \helpref{wxObject}{wxobject}
  14
  15 \wxheading{Include files}
  16
  17 <wx/imaglist.h>
  18
  19 \wxheading{See also}
  20
  21 \helpref{wxTreeCtrl}{wxtreectrl}, \helpref{wxListCtrl}{wxlistctrl}
  22
  23 \latexignore{\rtfignore{\wxheading{Members}}}
  24
  25 \membersection{wxImageList::wxImageList}\label{wximagelistconstr}
  26
  27 \func{}{wxImageList}{\void}
  28
  29 Default constructor.
  30
  31 \func{}{wxImageList}{\param{int }{width}, \param{int }{height}, \param{bool }{mask = true},\rtfsp
  32 \param{int }{initialCount = 1}}
  33
  34 Constructor specifying the image size, whether image masks should be created, and the initial size of the list.
  35
  36 \wxheading{Parameters}
  37
  38 \docparam{width}{Width of the images in the list.}
  39
  40 \docparam{height}{Height of the images in the list.}
  41
  42 \docparam{mask}{true if masks should be created for all images.}
  43
  44 \docparam{initialCount}{The initial size of the list.}
  45
  46 \wxheading{See also}
  47
  48 \helpref{wxImageList::Create}{wximagelistcreate}
  49
  50 \membersection{wxImageList::Add}\label{wximagelistadd}
  51
  52 \func{int}{Add}{\param{const wxBitmap\&}{ bitmap}, \param{const wxBitmap\&}{ mask = wxNullBitmap}}
  53
  54 Adds a new image or images using a bitmap and optional mask bitmap.
  55
  56 \func{int}{Add}{\param{const wxBitmap\&}{ bitmap}, \param{const wxColour\&}{ maskColour}}
  57
  58 Adds a new image or images using a bitmap and mask colour.
  59
  60 \func{int}{Add}{\param{const wxIcon\&}{ icon}}
  61
  62 Adds a new image using an icon.
  63
  64 \wxheading{Parameters}
  65
  66 \docparam{bitmap}{Bitmap representing the opaque areas of the image.}
  67
  68 \docparam{mask}{Monochrome mask bitmap, representing the transparent areas of the image.}
  69
  70 \docparam{maskColour}{Colour indicating which parts of the image are transparent.}
  71
  72 \docparam{icon}{Icon to use as the image.}
  73
  74 \wxheading{Return value}
  75
  76 The new zero-based image index.
  77
  78 \wxheading{Remarks}
  79
  80 The original bitmap or icon is not affected by the {\bf Add} operation, and can be deleted afterwards.
  81
  82 If the bitmap is wider than the images in the list, then the bitmap will automatically be split into smaller images, each matching the dimensions of the image list.  This does not apply when adding icons.
  83
  84 \pythonnote{In place of a single overloaded method name, wxPython
  85 implements the following methods:\par
  86 \indented{2cm}{\begin{twocollist}
  87 \twocolitem{{\bf Add(bitmap, mask=wxNullBitmap)}}{}
  88 \twocolitem{{\bf AddWithColourMask(bitmap, colour)}}{}
  89 \twocolitem{{\bf AddIcon(icon)}}{}
  90 \end{twocollist}}
  91 }
  92 \membersection{wxImageList::Create}\label{wximagelistcreate}
  93
  94 \func{bool}{Create}{\param{int }{width}, \param{int }{height}, \param{bool }{mask = true},\rtfsp
  95 \param{int }{initialCount = 1}}
  96
  97 Initializes the list. See \helpref{wxImageList::wxImageList}{wximagelistconstr} for details.
  98
  99 \membersection{wxImageList::Draw}\label{wximagelistdraw}
 100
 101 \func{bool}{Draw}{\param{int}{ index}, \param{wxDC\&}{ dc}, \param{int }{x},\rtfsp
 102 \param{int }{y}, \param{int }{flags = wxIMAGELIST\_DRAW\_NORMAL},\rtfsp
 103 \param{bool }{solidBackground = false}}
 104
 105 Draws a specified image onto a device context.
 106
 107 \wxheading{Parameters}
 108
 109 \docparam{index}{Image index, starting from zero.}
 110
 111 \docparam{dc}{Device context to draw on.}
 112
 113 \docparam{x}{X position on the device context.}
 114
 115 \docparam{y}{Y position on the device context.}
 116
 117 \docparam{flags}{How to draw the image. A bitlist of a selection of the following:
 118
 119 \begin{twocollist}\itemsep=0pt
 120 \twocolitem{{\bf wxIMAGELIST\_DRAW\_NORMAL}}{Draw the image normally.}
 121 \twocolitem{{\bf wxIMAGELIST\_DRAW\_TRANSPARENT}}{Draw the image with transparency.}
 122 \twocolitem{{\bf wxIMAGELIST\_DRAW\_SELECTED}}{Draw the image in selected state.}
 123 \twocolitem{{\bf wxIMAGELIST\_DRAW\_FOCUSED}}{Draw the image in a focused state.}
 124 \end{twocollist}
 125 }
 126
 127 \docparam{solidBackground}{For optimisation - drawing can be faster if the function is told
 128 that the background is solid.}
 129
 130 \membersection{wxImageList::GetBitmap}\label{wximagelistgetbitmap}
 131
 132 \constfunc{wxBitmap}{GetBitmap}{\param{int }{index}}
 133
 134 Returns the bitmap corresponding to the given index.
 135
 136 \membersection{wxImageList::GetIcon}\label{wximagelistgeticon}
 137
 138 \constfunc{wxIcon}{GetIcon}{\param{int }{index}}
 139
 140 Returns the icon corresponding to the given index.
 141
 142 \membersection{wxImageList::GetImageCount}\label{wximagelistgetimagecount}
 143
 144 \constfunc{int}{GetImageCount}{\void}
 145
 146 Returns the number of images in the list.
 147
 148 \membersection{wxImageList::GetSize}\label{wximagelistgetsize}
 149
 150 \constfunc{bool}{GetSize}{\param{int }{index}, \param{int\& }{width}, \param{int \&}{height}}
 151
 152 Retrieves the size of the images in the list. Currently, the {\it index}
 153 parameter is ignored as all images in the list have the same size.
 154
 155 \wxheading{Parameters}
 156
 157 \docparam{index}{currently unused, should be 0}
 158
 159 \docparam{width}{receives the width of the images in the list}
 160
 161 \docparam{height}{receives the height of the images in the list}
 162
 163 \wxheading{Return value}
 164
 165 true if the function succeeded, false if it failed (for example, if the image
 166 list was not yet initialized).
 167
 168 \membersection{wxImageList::Remove}\label{wximagelistremove}
 169
 170 \func{bool}{Remove}{\param{int}{ index}}
 171
 172 Removes the image at the given position.
 173
 174 \membersection{wxImageList::RemoveAll}\label{wximagelistremoveall}
 175
 176 \func{bool}{RemoveAll}{\void}
 177
 178 Removes all the images in the list.
 179
 180 \membersection{wxImageList::Replace}\label{wximagelistreplace}
 181
 182 \func{bool}{Replace}{\param{int}{ index}, \param{const wxBitmap\&}{ bitmap}, \param{const wxBitmap\&}{ mask = wxNullBitmap}}
 183
 184 Replaces the existing image with the new image.
 185
 186 Windows only.
 187
 188 \func{bool}{Replace}{\param{int}{ index}, \param{const wxIcon\&}{ icon}}
 189
 190 Replaces the existing image with the new image.
 191
 192 \wxheading{Parameters}
 193
 194 \docparam{bitmap}{Bitmap representing the opaque areas of the image.}
 195
 196 \docparam{mask}{Monochrome mask bitmap, representing the transparent areas of the image.}
 197
 198 \docparam{icon}{Icon to use as the image.}
 199
 200 \wxheading{Return value}
 201
 202 true if the replacement was successful, false otherwise.
 203
 204 \wxheading{Remarks}
 205
 206 The original bitmap or icon is not affected by the {\bf Replace} operation, and can be deleted afterwards.
 207
 208 \pythonnote{The second form is called {\tt ReplaceIcon} in wxPython.}
 209
 210