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