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