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