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