Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: icon.h | |
e54c96f1 | 3 | // Purpose: interface of wxIcon |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
cbea3ec6 FM |
9 | |
10 | ||
11 | /** | |
12 | In wxIcon context this value means: "use the screen depth". | |
13 | */ | |
14 | #define wxICON_SCREEN_DEPTH (-1) | |
15 | ||
16 | ||
23324ae1 FM |
17 | /** |
18 | @class wxIcon | |
7c913512 | 19 | |
cbea3ec6 FM |
20 | An icon is a small rectangular bitmap usually used for denoting a minimized |
21 | application. | |
22 | ||
23 | It differs from a wxBitmap in always having a mask associated with it for | |
24 | transparent drawing. On some platforms, icons and bitmaps are implemented | |
25 | identically, since there is no real distinction between a wxBitmap with a | |
26 | mask and an icon; and there is no specific icon format on some platforms | |
27 | (X-based applications usually standardize on XPMs for small bitmaps and icons). | |
28 | However, some platforms (such as Windows) make the distinction, so a | |
29 | separate class is provided. | |
30 | ||
31 | @remarks | |
32 | It is usually desirable to associate a pertinent icon with a frame. | |
33 | Icons can also be used for other purposes, for example with wxTreeCtrl and wxListCtrl. | |
34 | Icons have different formats on different platforms therefore separate icons | |
35 | will usually be created for the different environments. | |
36 | Platform-specific methods for creating a wxIcon structure are catered for, | |
37 | and this is an occasion where conditional compilation will probably be required. | |
38 | Note that a new icon must be created for every time the icon is to be used | |
39 | for a new window. In Windows, the icon will not be reloaded if it has already | |
40 | been used. | |
41 | An icon allocated to a frame will be deleted when the frame is deleted. | |
42 | For more information please see @ref overview_bitmap. | |
7c913512 | 43 | |
23324ae1 FM |
44 | @library{wxcore} |
45 | @category{gdi} | |
7c913512 | 46 | |
23324ae1 | 47 | @stdobjects |
65874118 | 48 | ::wxNullIcon |
7c913512 | 49 | |
cbea3ec6 FM |
50 | @see @ref overview_bitmap, @ref overview_bitmap_supportedformats, |
51 | wxDC::DrawIcon, wxCursor | |
23324ae1 FM |
52 | */ |
53 | class wxIcon : public wxBitmap | |
54 | { | |
55 | public: | |
23324ae1 | 56 | /** |
cbea3ec6 | 57 | Default ctor. |
3c4f71cc | 58 | |
cbea3ec6 FM |
59 | Constructs an icon object with no data; an assignment or another member |
60 | function such as LoadFile() must be called subsequently. | |
61 | */ | |
62 | wxIcon(); | |
3c4f71cc | 63 | |
cbea3ec6 FM |
64 | /** |
65 | Copy ctor. | |
66 | */ | |
67 | wxIcon(const wxIcon& icon); | |
3c4f71cc | 68 | |
cbea3ec6 FM |
69 | /* |
70 | Creates an icon from the given data, which can be of arbitrary type. | |
3c4f71cc | 71 | |
cbea3ec6 | 72 | wxIcon(void* data, int type, int width, int height, int depth = -1); |
3c4f71cc | 73 | |
cbea3ec6 FM |
74 | NOTE: this ctor is not implemented by all ports, is somewhat useless |
75 | without further description of the "data" supported formats and | |
76 | uses 'int type' instead of wxBitmapType, so don't document it. | |
77 | */ | |
3c4f71cc | 78 | |
cbea3ec6 FM |
79 | /** |
80 | Creates an icon from an array of bits. | |
81 | You should only use this function for monochrome bitmaps (depth 1) in | |
82 | portable programs: in this case the bits parameter should contain an XBM image. | |
3c4f71cc | 83 | |
cbea3ec6 FM |
84 | For other bit depths, the behaviour is platform dependent: under Windows, |
85 | the data is passed without any changes to the underlying CreateBitmap() API. | |
86 | Under other platforms, only monochrome bitmaps may be created using this | |
87 | constructor and wxImage should be used for creating colour bitmaps from | |
88 | static data. | |
3c4f71cc | 89 | |
cbea3ec6 FM |
90 | @param bits |
91 | Specifies an array of pixel values. | |
92 | @param width | |
a44f3b5a | 93 | The width of the image. |
cbea3ec6 | 94 | @param height |
a44f3b5a | 95 | The height of the image. |
3c4f71cc | 96 | |
0f6c9085 | 97 | @onlyfor{wxmsw,wxosx} |
cbea3ec6 | 98 | */ |
a44f3b5a | 99 | wxIcon(const char bits[], int width, int height); |
3c4f71cc | 100 | |
cbea3ec6 FM |
101 | /** |
102 | Creates a bitmap from XPM data. | |
103 | To use this constructor, you must first include an XPM file. | |
104 | For example, assuming that the file mybitmap.xpm contains an XPM array | |
105 | of character pointers called @e mybitmap: | |
106 | ||
107 | @code | |
108 | #include "mybitmap.xpm" | |
109 | ... | |
110 | wxIcon *icon = new wxIcon(mybitmap); | |
111 | @endcode | |
112 | ||
113 | A macro, wxICON, is available which creates an icon using an XPM on | |
114 | the appropriate platform, or an icon resource on Windows. | |
115 | ||
116 | @code | |
117 | wxIcon icon(wxICON(mondrian)); | |
118 | ||
119 | // Equivalent to: | |
120 | #if defined(__WXGTK__) || defined(__WXMOTIF__) | |
121 | wxIcon icon(mondrian_xpm); | |
122 | #endif | |
123 | ||
124 | #if defined(__WXMSW__) | |
125 | wxIcon icon("mondrian"); | |
126 | #endif | |
127 | @endcode | |
128 | */ | |
129 | wxIcon(const char* const* bits); | |
3c4f71cc | 130 | |
cbea3ec6 FM |
131 | /** |
132 | Loads an icon from a file or resource. | |
3c4f71cc | 133 | |
cbea3ec6 FM |
134 | @param name |
135 | This can refer to a resource name or a filename under MS Windows and X. | |
136 | Its meaning is determined by the @a type parameter. | |
137 | @param type | |
138 | May be one of the ::wxBitmapType values and indicates which type of | |
139 | bitmap should be loaded. See the note in the class detailed description. | |
140 | Note that the wxICON_DEFAULT_TYPE constant has different value under | |
141 | different wxWidgets ports. See the icon.h header for the value it takes | |
142 | for a specific port. | |
143 | @param desiredWidth | |
144 | Specifies the desired width of the icon. This parameter only has | |
145 | an effect in Windows where icon resources can contain several icons | |
146 | of different sizes. | |
147 | @param desiredHeight | |
148 | Specifies the desired height of the icon. This parameter only has | |
149 | an effect in Windows where icon resources can contain several icons | |
150 | of different sizes. | |
151 | ||
152 | @see LoadFile() | |
153 | */ | |
154 | wxIcon(const wxString& name, wxBitmapType type = wxICON_DEFAULT_TYPE, | |
155 | int desiredWidth = -1, int desiredHeight = -1); | |
3c4f71cc | 156 | |
cbea3ec6 FM |
157 | /** |
158 | Loads an icon from the specified location. | |
23324ae1 | 159 | */ |
7c913512 | 160 | wxIcon(const wxIconLocation& loc); |
23324ae1 FM |
161 | |
162 | /** | |
163 | Destructor. | |
cbea3ec6 FM |
164 | See @ref overview_refcount_destruct for more info. |
165 | ||
23324ae1 FM |
166 | If the application omits to delete the icon explicitly, the icon will be |
167 | destroyed automatically by wxWidgets when the application exits. | |
cbea3ec6 FM |
168 | |
169 | @warning | |
23324ae1 FM |
170 | Do not delete an icon that is selected into a memory device context. |
171 | */ | |
adaaa686 | 172 | virtual ~wxIcon(); |
23324ae1 FM |
173 | |
174 | /** | |
cbea3ec6 FM |
175 | Copies @a bmp bitmap to this icon. |
176 | Under MS Windows the bitmap must have mask colour set. | |
3c4f71cc | 177 | |
cbea3ec6 | 178 | @see LoadFile() |
23324ae1 FM |
179 | */ |
180 | void CopyFromBitmap(const wxBitmap& bmp); | |
181 | ||
182 | /** | |
cbea3ec6 FM |
183 | Gets the colour depth of the icon. |
184 | A value of 1 indicates a monochrome icon. | |
23324ae1 | 185 | */ |
328f5751 | 186 | int GetDepth() const; |
23324ae1 FM |
187 | |
188 | /** | |
189 | Gets the height of the icon in pixels. | |
cbea3ec6 FM |
190 | |
191 | @see GetWidth() | |
23324ae1 | 192 | */ |
328f5751 | 193 | int GetHeight() const; |
23324ae1 FM |
194 | |
195 | /** | |
196 | Gets the width of the icon in pixels. | |
3c4f71cc | 197 | |
4cc4bfaf | 198 | @see GetHeight() |
23324ae1 | 199 | */ |
328f5751 | 200 | int GetWidth() const; |
23324ae1 FM |
201 | |
202 | /** | |
203 | Returns @true if icon data is present. | |
204 | */ | |
0004982c | 205 | virtual bool IsOk() const; |
23324ae1 FM |
206 | |
207 | /** | |
208 | Loads an icon from a file or resource. | |
3c4f71cc | 209 | |
7c913512 | 210 | @param name |
4cc4bfaf | 211 | Either a filename or a Windows resource name. |
cbea3ec6 | 212 | The meaning of name is determined by the @a type parameter. |
7c913512 | 213 | @param type |
cbea3ec6 FM |
214 | One of the ::wxBitmapType values; see the note in the class |
215 | detailed description. | |
216 | Note that the wxICON_DEFAULT_TYPE constant has different value under | |
217 | different wxWidgets ports. See the icon.h header for the value it takes | |
218 | for a specific port. | |
219 | @param desiredWidth | |
220 | Specifies the desired width of the icon. This parameter only has | |
221 | an effect in Windows where icon resources can contain several icons | |
222 | of different sizes. | |
223 | @param desiredHeight | |
224 | Specifies the desired height of the icon. This parameter only has | |
225 | an effect in Windows where icon resources can contain several icons | |
226 | of different sizes. | |
3c4f71cc | 227 | |
d29a9a8a | 228 | @return @true if the operation succeeded, @false otherwise. |
23324ae1 | 229 | */ |
cbea3ec6 FM |
230 | bool LoadFile(const wxString& name, wxBitmapType type = wxICON_DEFAULT_TYPE, |
231 | int desiredWidth = -1, int desiredHeight = -1); | |
23324ae1 FM |
232 | |
233 | /** | |
234 | Sets the depth member (does not affect the icon data). | |
3c4f71cc | 235 | |
7c913512 | 236 | @param depth |
4cc4bfaf | 237 | Icon depth. |
23324ae1 FM |
238 | */ |
239 | void SetDepth(int depth); | |
240 | ||
241 | /** | |
242 | Sets the height member (does not affect the icon data). | |
3c4f71cc | 243 | |
7c913512 | 244 | @param height |
4cc4bfaf | 245 | Icon height in pixels. |
23324ae1 FM |
246 | */ |
247 | void SetHeight(int height); | |
248 | ||
249 | /** | |
250 | Sets the width member (does not affect the icon data). | |
3c4f71cc | 251 | |
7c913512 | 252 | @param width |
4cc4bfaf | 253 | Icon width in pixels. |
23324ae1 FM |
254 | */ |
255 | void SetWidth(int width); | |
256 | ||
257 | /** | |
cbea3ec6 | 258 | Assignment operator, using @ref overview_refcount. |
3c4f71cc | 259 | |
7c913512 | 260 | @param icon |
4cc4bfaf | 261 | Icon to assign. |
23324ae1 | 262 | */ |
43c48e1e | 263 | wxIcon& operator=(const wxIcon& icon); |
23324ae1 | 264 | }; |
e54c96f1 | 265 | |
e54c96f1 | 266 | /** |
65874118 | 267 | An empty wxIcon. |
e54c96f1 FM |
268 | */ |
269 | wxIcon wxNullIcon; | |
270 | ||
271 |