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