interface/wx/imaglist.h

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