]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/artprov.h
Default to wxConvUTF8 (not wxConvAuto) in wxDataInputStream and wxDataOutputStream...
[wxWidgets.git] / interface / wx / artprov.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: artprov.h
3 // Purpose: interface of wxArtProvider
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 This type identifies the client of the art objects requested to wxArtProvider.
11 */
12 typedef wxString wxArtClient;
13
14 /**
15 This type identifies a specific art object which can be requested to wxArtProvider.
16 */
17 typedef wxString wxArtID;
18
19
20 /**
21 @class wxArtProvider
22
23 wxArtProvider class is used to customize the look of wxWidgets application.
24
25 When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
26 dialog), it does not use a hard-coded resource but asks wxArtProvider for it
27 instead. This way users can plug in their own wxArtProvider class and easily
28 replace standard art with their own version.
29
30 All that is needed is to derive a class from wxArtProvider, override either its
31 wxArtProvider::CreateBitmap() and/or its wxArtProvider::CreateIconBundle() methods
32 and register the provider with wxArtProvider::Push():
33
34 @code
35 class MyProvider : public wxArtProvider
36 {
37 protected:
38 wxBitmap CreateBitmap(const wxArtID& id,
39 const wxArtClient& client,
40 const wxSize size)
41
42 // optionally override this one as well
43 wxIconBundle CreateIconBundle(const wxArtID& id,
44 const wxArtClient& client)
45 { ... }
46 };
47 ...
48 wxArtProvider::Push(new MyProvider);
49 @endcode
50
51 If you need bitmap images (of the same artwork) that should be displayed at
52 different sizes you should probably consider overriding wxArtProvider::CreateIconBundle
53 and supplying icon bundles that contain different bitmap sizes.
54
55 There's another way of taking advantage of this class: you can use it in your
56 code and use platform native icons as provided by wxArtProvider::GetBitmap or
57 wxArtProvider::GetIcon.
58
59 @section artprovider_identify Identifying art resources
60
61 Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
62 is used when requesting a resource from it. The ID is represented by wxArtID type
63 and can have one of these predefined values (you can see bitmaps represented by these
64 constants in the @ref page_samples_artprov):
65
66 <table>
67 <tr><td>
68 @li wxART_ERROR
69 @li wxART_QUESTION
70 @li wxART_WARNING
71 @li wxART_INFORMATION
72 @li wxART_ADD_BOOKMARK
73 @li wxART_DEL_BOOKMARK
74 @li wxART_HELP_SIDE_PANEL
75 @li wxART_HELP_SETTINGS
76 @li wxART_HELP_BOOK
77 @li wxART_HELP_FOLDER
78 @li wxART_HELP_PAGE
79 @li wxART_GO_BACK
80 @li wxART_GO_FORWARD
81 @li wxART_GO_UP
82 </td><td>
83 @li wxART_GO_DOWN
84 @li wxART_GO_TO_PARENT
85 @li wxART_GO_HOME
86 @li wxART_PRINT
87 @li wxART_HELP
88 @li wxART_TIP
89 @li wxART_REPORT_VIEW
90 @li wxART_LIST_VIEW
91 @li wxART_NEW_DIR
92 @li wxART_FOLDER
93 @li wxART_FOLDER_OPEN
94 @li wxART_GO_DIR_UP
95 @li wxART_EXECUTABLE_FILE
96 @li wxART_NORMAL_FILE
97 @li wxART_TICK_MARK
98 @li wxART_CROSS_MARK
99 </td><td>
100 @li wxART_MISSING_IMAGE
101 @li wxART_NEW
102 @li wxART_FILE_OPEN
103 @li wxART_FILE_SAVE
104 @li wxART_FILE_SAVE_AS
105 @li wxART_DELETE
106 @li wxART_COPY
107 @li wxART_CUT
108 @li wxART_PASTE
109 @li wxART_UNDO
110 @li wxART_REDO
111 @li wxART_QUIT
112 @li wxART_FIND
113 @li wxART_FIND_AND_REPLACE
114 @li wxART_HARDDISK
115 @li wxART_FLOPPY
116 @li wxART_CDROM
117 @li wxART_REMOVABLE
118 </td></tr>
119 </table>
120
121 Additionally, any string recognized by custom art providers registered using
122 wxArtProvider::Push may be used.
123
124 @note
125 When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used
126 as well:
127 @code
128 #ifdef __WXGTK__
129 wxBitmap bmp = wxArtProvider::GetBitmap("gtk-cdrom", wxART_MENU);
130 #endif
131 @endcode
132 For a list of the GTK+ stock items please refer to the GTK+ documentation page
133 http://library.gnome.org/devel/gtk/stable/gtk-Stock-Items.html.
134 Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is also
135 possible to load icons from current icon theme by specifying their name (without
136 extension and directory components).
137 Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification
138 (see http://freedesktop.org/Standards/icon-theme-spec).
139 Note that themes are not guaranteed to contain all icons, so wxArtProvider may
140 return ::wxNullBitmap or ::wxNullIcon.
141 The default theme is typically installed in @c /usr/share/icons/hicolor.
142
143
144 @section artprovider_clients Clients
145
146 The @e client is the entity that calls wxArtProvider's GetBitmap() or GetIcon() function.
147 It is represented by wxClientID type and can have one of these values:
148
149 @li wxART_TOOLBAR
150 @li wxART_MENU
151 @li wxART_BUTTON
152 @li wxART_FRAME_ICON
153 @li wxART_CMN_DIALOG
154 @li wxART_HELP_BROWSER
155 @li wxART_MESSAGE_BOX
156 @li wxART_OTHER (used for all requests that don't fit into any of the
157 categories above)
158
159 Client ID serve as a hint to wxArtProvider that is supposed to help it to
160 choose the best looking bitmap. For example it is often desirable to use
161 slightly different icons in menus and toolbars even though they represent
162 the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a
163 hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns
164 identical bitmap for different client values!
165
166 @library{wxcore}
167 @category{misc,data}
168
169 @see the @ref page_samples_artprov for an example of wxArtProvider usage.
170 */
171 class wxArtProvider : public wxObject
172 {
173 public:
174 /**
175 The destructor automatically removes the provider from the provider stack used
176 by GetBitmap().
177 */
178 virtual ~wxArtProvider();
179
180 /**
181 Delete the given @a provider.
182 */
183 static bool Delete(wxArtProvider* provider);
184
185 /**
186 Query registered providers for bitmap with given ID.
187
188 @param id
189 wxArtID unique identifier of the bitmap.
190 @param client
191 wxArtClient identifier of the client (i.e. who is asking for the bitmap).
192 @param size
193 Size of the returned bitmap or wxDefaultSize if size doesn't matter.
194
195 @return The bitmap if one of registered providers recognizes the ID or
196 wxNullBitmap otherwise.
197 */
198 static wxBitmap GetBitmap(const wxArtID& id,
199 const wxArtClient& client = wxART_OTHER,
200 const wxSize& size = wxDefaultSize);
201
202 /**
203 Same as wxArtProvider::GetBitmap, but return a wxIcon object
204 (or ::wxNullIcon on failure).
205 */
206 static wxIcon GetIcon(const wxArtID& id,
207 const wxArtClient& client = wxART_OTHER,
208 const wxSize& size = wxDefaultSize);
209
210 /**
211 Returns native icon size for use specified by @a client hint.
212
213 If the platform has no commonly used default for this use or if
214 @a client is not recognized, returns wxDefaultSize.
215
216 @note In some cases, a platform may have @em several appropriate
217 native sizes (for example, wxART_FRAME_ICON for frame icons).
218 In that case, this method returns only one of them, picked
219 reasonably.
220
221 @since 2.9.0
222 */
223 static wxSize GetNativeSizeHint(const wxArtClient& client);
224
225 /**
226 Returns a suitable size hint for the given @e wxArtClient.
227
228 If @a platform_default is @true, return a size based on the current
229 platform using GetNativeSizeHint(), otherwise return the size from the
230 topmost wxArtProvider. @e wxDefaultSize may be returned if the client
231 doesn't have a specified size, like wxART_OTHER for example.
232
233 @see GetNativeSizeHint()
234 */
235 static wxSize GetSizeHint(const wxArtClient& client,
236 bool platform_default = false);
237
238 /**
239 Query registered providers for icon bundle with given ID.
240
241 @param id
242 wxArtID unique identifier of the icon bundle.
243 @param client
244 wxArtClient identifier of the client (i.e. who is asking for the icon
245 bundle).
246
247 @return The icon bundle if one of registered providers recognizes the ID
248 or wxNullIconBundle otherwise.
249 */
250 static wxIconBundle GetIconBundle(const wxArtID& id,
251 const wxArtClient& client = wxART_OTHER);
252
253 /**
254 Returns true if the platform uses native icons provider that should
255 take precedence over any customizations.
256
257 This is true for any platform that has user-customizable icon themes,
258 currently only wxGTK.
259
260 A typical use for this method is to decide whether a custom art provider
261 should be plugged in using Push() or PushBack().
262
263 @since 2.9.0
264 */
265 static bool HasNativeProvider();
266
267 /**
268 @deprecated Use PushBack() instead.
269 */
270 static void Insert(wxArtProvider* provider);
271
272 /**
273 Remove latest added provider and delete it.
274 */
275 static bool Pop();
276
277 /**
278 Register new art provider and add it to the top of providers stack
279 (i.e. it will be queried as the first provider).
280
281 @see PushBack()
282 */
283 static void Push(wxArtProvider* provider);
284
285 /**
286 Register new art provider and add it to the bottom of providers stack.
287 In other words, it will be queried as the last one, after all others,
288 including the default provider.
289
290 @see Push()
291
292 @since 2.9.0
293 */
294 static void PushBack(wxArtProvider* provider);
295
296 /**
297 Remove a provider from the stack if it is on it. The provider is not
298 deleted, unlike when using Delete().
299 */
300 static bool Remove(wxArtProvider* provider);
301
302 protected:
303
304 /**
305 Derived art provider classes must override this method to create requested art
306 resource. Note that returned bitmaps are cached by wxArtProvider and it is
307 therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
308 create wxBitmap objects from XPMs here).
309
310 @param id
311 wxArtID unique identifier of the bitmap.
312 @param client
313 wxArtClient identifier of the client (i.e. who is asking for the bitmap).
314 This only servers as a hint.
315 @param size
316 Preferred size of the bitmap. The function may return a bitmap of different
317 dimensions, it will be automatically rescaled to meet client's request.
318
319 @note
320 This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap
321 or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider
322 for a resource.
323
324 @see CreateIconBundle()
325 */
326 virtual wxBitmap CreateBitmap(const wxArtID& id,
327 const wxArtClient& client,
328 const wxSize& size);
329
330 /**
331 This method is similar to CreateBitmap() but can be used when a bitmap
332 (or an icon) exists in several sizes.
333 */
334 virtual wxIconBundle CreateIconBundle(const wxArtID& id,
335 const wxArtClient& client);
336 };
337