interface/wx/imaglist.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        imaglist.h
   3 // Purpose:     interface of wxImageList
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxImageList
  11
  12     A wxImageList contains a list of images, which are stored in an unspecified
  13     form. Images can have masks for transparent drawing, and can be made from a
  14     variety of sources including bitmaps and icons.
  15
  16     wxImageList is used principally in conjunction with wxTreeCtrl and
  17     wxListCtrl classes.
  18
  19     @library{wxcore}
  20     @category{gdi}
  21
  22     @see wxTreeCtrl, wxListCtrl
  23 */
  24 class wxImageList : public wxObject
  25 {
  26 public:
  27     /**
  28         Default ctor.
  29     */
  30     wxImageList();
  31
  32     /**
  33         Constructor specifying the image size, whether image masks should be created,
  34         and the initial size of the list.
  35
  36         @param width
  37             Width of the images in the list.
  38         @param height
  39             Height of the images in the list.
  40         @param mask
  41             @true if masks should be created for all images.
  42         @param initialCount
  43             The initial size of the list.
  44
  45         @see Create()
  46     */
  47     wxImageList(int width, int height, bool mask = true,
  48                 int initialCount = 1);
  49
  50     /**
  51         Adds a new image or images using a bitmap and optional mask bitmap.
  52
  53         @param bitmap
  54             Bitmap representing the opaque areas of the image.
  55         @param mask
  56             Monochrome mask bitmap, representing the transparent areas of the image.
  57
  58         @return The new zero-based image index.
  59
  60         @remarks The original bitmap or icon is not affected by the Add()
  61                  operation, and can be deleted afterwards.
  62                  If the bitmap is wider than the images in the list, then the
  63                  bitmap will automatically be split into smaller images, each
  64                  matching the dimensions of the image list.
  65                  This does not apply when adding icons.
  66     */
  67     int Add(const wxBitmap& bitmap,
  68             const wxBitmap& mask = wxNullBitmap);
  69
  70     /**
  71         Adds a new image or images using a bitmap and mask colour.
  72
  73         @param bitmap
  74             Bitmap representing the opaque areas of the image.
  75         @param maskColour
  76             Colour indicating which parts of the image are transparent.
  77
  78         @return The new zero-based image index.
  79
  80         @remarks The original bitmap or icon is not affected by the Add()
  81                  operation, and can be deleted afterwards.
  82                  If the bitmap is wider than the images in the list, then the
  83                  bitmap will automatically be split into smaller images, each
  84                  matching the dimensions of the image list.
  85                  This does not apply when adding icons.
  86     */
  87     int Add(const wxBitmap& bitmap, const wxColour& maskColour);
  88
  89     /**
  90         Adds a new image using an icon.
  91
  92         @param icon
  93             Icon to use as the image.
  94
  95         @return The new zero-based image index.
  96
  97         @remarks The original bitmap or icon is not affected by the Add()
  98                  operation, and can be deleted afterwards.
  99                  If the bitmap is wider than the images in the list, then the
 100                  bitmap will automatically be split into smaller images, each
 101                  matching the dimensions of the image list.
 102                  This does not apply when adding icons.
 103     */
 104     int Add(const wxIcon& icon);
 105
 106     /**
 107         Initializes the list. See wxImageList() for details.
 108     */
 109     bool Create(int width, int height, bool mask = true,
 110                 int initialCount = 1);
 111
 112     /**
 113         Draws a specified image onto a device context.
 114
 115         @param index
 116             Image index, starting from zero.
 117         @param dc
 118             Device context to draw on.
 119         @param x
 120             X position on the device context.
 121         @param y
 122             Y position on the device context.
 123         @param flags
 124             How to draw the image. A bitlist of a selection of the following:
 125             - wxIMAGELIST_DRAW_NORMAL: Draw the image normally.
 126             - wxIMAGELIST_DRAW_TRANSPARENT: Draw the image with transparency.
 127             - wxIMAGELIST_DRAW_SELECTED: Draw the image in selected state.
 128             - wxIMAGELIST_DRAW_FOCUSED: Draw the image in a focused state.
 129         @param solidBackground
 130             For optimisation - drawing can be faster if the function is told
 131             that the background is solid.
 132     */
 133     virtual bool Draw(int index, wxDC& dc, int x, int y,
 134                       int flags = wxIMAGELIST_DRAW_NORMAL,
 135                       bool solidBackground = false);
 136
 137     /**
 138         Returns the bitmap corresponding to the given index.
 139     */
 140     wxBitmap GetBitmap(int index) const;
 141
 142     /**
 143         Returns the icon corresponding to the given index.
 144     */
 145     wxIcon GetIcon(int index) const;
 146
 147     /**
 148         Returns the number of images in the list.
 149     */
 150     virtual int GetImageCount() const;
 151
 152     /**
 153         Retrieves the size of the images in the list. Currently, the @a index
 154         parameter is ignored as all images in the list have the same size.
 155
 156         @param index
 157             currently unused, should be 0
 158         @param width
 159             receives the width of the images in the list
 160         @param height
 161             receives the height of the images in the list
 162
 163         @return @true if the function succeeded, @false if it failed
 164                 (for example, if the image list was not yet initialized).
 165     */
 166     virtual bool GetSize(int index, int& width, int& height) const;
 167
 168     /**
 169         Removes the image at the given position.
 170     */
 171     bool Remove(int index);
 172
 173     /**
 174         Removes all the images in the list.
 175     */
 176     bool RemoveAll();
 177
 178     /**
 179         Replaces the existing image with the new image.
 180         Windows only.
 181
 182         @param index
 183             The index of the bitmap to be replaced.
 184         @param bitmap
 185             Bitmap representing the opaque areas of the image.
 186         @param mask
 187             Monochrome mask bitmap, representing the transparent areas of the image.
 188
 189         @return @true if the replacement was successful, @false otherwise.
 190
 191         @remarks The original bitmap or icon is not affected by the Replace()
 192                  operation, and can be deleted afterwards.
 193     */
 194     bool Replace(int index, const wxBitmap& bitmap,
 195                  const wxBitmap& mask = wxNullBitmap);
 196
 197     /**
 198         Replaces the existing image with the new image.
 199
 200         @param index
 201             The index of the bitmap to be replaced.
 202         @param icon
 203             Icon to use as the image.
 204
 205         @return @true if the replacement was successful, @false otherwise.
 206
 207         @remarks The original bitmap or icon is not affected by the Replace()
 208                  operation, and can be deleted afterwards.
 209     */
 210     bool Replace(int index, const wxIcon& icon);
 211 };
 212