| 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 | |