interface/imaglist.h

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