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