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