]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/artprov.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxArtProvider
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 This type identifies the client of the art objects requested to wxArtProvider.
12 typedef wxString wxArtClient
;
15 This type identifies a specific art object which can be requested to wxArtProvider.
17 typedef wxString wxArtID
;
23 wxArtProvider class is used to customize the look of wxWidgets application.
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.
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():
35 class MyProvider : public wxArtProvider
38 wxBitmap CreateBitmap(const wxArtID& id,
39 const wxArtClient& client,
42 // optionally override this one as well
43 wxIconBundle CreateIconBundle(const wxArtID& id,
44 const wxArtClient& client)
48 wxArtProvider::Push(new MyProvider);
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.
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.
59 @section artprovider_identify Identifying art resources
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):
72 @li wxART_ADD_BOOKMARK
73 @li wxART_DEL_BOOKMARK
74 @li wxART_HELP_SIDE_PANEL
75 @li wxART_HELP_SETTINGS
84 @li wxART_GO_TO_PARENT
95 @li wxART_EXECUTABLE_FILE
100 @li wxART_MISSING_IMAGE
104 @li wxART_FILE_SAVE_AS
113 @li wxART_FIND_AND_REPLACE
121 Additionally, any string recognized by custom art providers registered using
122 wxArtProvider::Push may be used.
125 When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used
129 wxBitmap bmp = wxArtProvider::GetBitmap("gtk-cdrom", wxART_MENU);
132 Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is also
133 possible to load icons from current icon theme by specifying their name (without
134 extension and directory components).
135 Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification
136 (see http://freedesktop.org/Standards/icon-theme-spec).
137 Note that themes are not guaranteed to contain all icons, so wxArtProvider may
138 return ::wxNullBitmap or ::wxNullIcon.
139 The default theme is typically installed in @c /usr/share/icons/hicolor.
142 @section artprovider_clients Clients
144 The @e client is the entity that calls wxArtProvider's GetBitmap() or GetIcon() function.
145 It is represented by wxClientID type and can have one of these values:
152 @li wxART_HELP_BROWSER
153 @li wxART_MESSAGE_BOX
154 @li wxART_OTHER (used for all requests that don't fit into any of the
157 Client ID serve as a hint to wxArtProvider that is supposed to help it to
158 choose the best looking bitmap. For example it is often desirable to use
159 slightly different icons in menus and toolbars even though they represent
160 the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a
161 hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns
162 identical bitmap for different client values!
167 @see the @ref page_samples_artprov for an example of wxArtProvider usage.
169 class wxArtProvider
: public wxObject
173 The destructor automatically removes the provider from the provider stack used
176 virtual ~wxArtProvider();
179 Delete the given @a provider.
181 static bool Delete(wxArtProvider
* provider
);
184 Query registered providers for bitmap with given ID.
187 wxArtID unique identifier of the bitmap.
189 wxArtClient identifier of the client (i.e. who is asking for the bitmap).
191 Size of the returned bitmap or wxDefaultSize if size doesn't matter.
193 @return The bitmap if one of registered providers recognizes the ID or
194 wxNullBitmap otherwise.
196 static wxBitmap
GetBitmap(const wxArtID
& id
,
197 const wxArtClient
& client
= wxART_OTHER
,
198 const wxSize
& size
= wxDefaultSize
);
201 Same as wxArtProvider::GetBitmap, but return a wxIcon object
202 (or ::wxNullIcon on failure).
204 static wxIcon
GetIcon(const wxArtID
& id
,
205 const wxArtClient
& client
= wxART_OTHER
,
206 const wxSize
& size
= wxDefaultSize
);
209 Returns native icon size for use specified by @a client hint.
211 If the platform has no commonly used default for this use or if
212 @a client is not recognized, returns wxDefaultSize.
214 @note In some cases, a platform may have @em several appropriate
215 native sizes (for example, wxART_FRAME_ICON for frame icons).
216 In that case, this method returns only one of them, picked
221 static wxSize
GetNativeSizeHint(const wxArtClient
& client
);
224 Returns a suitable size hint for the given @e wxArtClient.
226 If @a platform_default is @true, return a size based on the current
227 platform using GetNativeSizeHint(), otherwise return the size from the
228 topmost wxArtProvider. @e wxDefaultSize may be returned if the client
229 doesn't have a specified size, like wxART_OTHER for example.
231 @see GetNativeSizeHint()
233 static wxSize
GetSizeHint(const wxArtClient
& client
,
234 bool platform_default
= false);
237 Query registered providers for icon bundle with given ID.
240 wxArtID unique identifier of the icon bundle.
242 wxArtClient identifier of the client (i.e. who is asking for the icon
245 @return The icon bundle if one of registered providers recognizes the ID
246 or wxNullIconBundle otherwise.
248 static wxIconBundle
GetIconBundle(const wxArtID
& id
,
249 const wxArtClient
& client
= wxART_OTHER
);
252 Returns true if the platform uses native icons provider that should
253 take precedence over any customizations.
255 This is true for any platform that has user-customizable icon themes,
256 currently only wxGTK.
258 A typical use for this method is to decide whether a custom art provider
259 should be plugged in using Push() or PushBack().
263 static bool HasNativeProvider();
266 @deprecated Use PushBack() instead.
268 static void Insert(wxArtProvider
* provider
);
271 Remove latest added provider and delete it.
276 Register new art provider and add it to the top of providers stack
277 (i.e. it will be queried as the first provider).
281 static void Push(wxArtProvider
* provider
);
284 Register new art provider and add it to the bottom of providers stack.
285 In other words, it will be queried as the last one, after all others,
286 including the default provider.
292 static void PushBack(wxArtProvider
* provider
);
295 Remove a provider from the stack if it is on it. The provider is not
296 deleted, unlike when using Delete().
298 static bool Remove(wxArtProvider
* provider
);
303 Derived art provider classes must override this method to create requested art
304 resource. Note that returned bitmaps are cached by wxArtProvider and it is
305 therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
306 create wxBitmap objects from XPMs here).
309 wxArtID unique identifier of the bitmap.
311 wxArtClient identifier of the client (i.e. who is asking for the bitmap).
312 This only servers as a hint.
314 Preferred size of the bitmap. The function may return a bitmap of different
315 dimensions, it will be automatically rescaled to meet client's request.
318 This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap
319 or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider
322 @see CreateIconBundle()
324 virtual wxBitmap
CreateBitmap(const wxArtID
& id
,
325 const wxArtClient
& client
,
329 This method is similar to CreateBitmap() but can be used when a bitmap
330 (or an icon) exists in several sizes.
332 virtual wxIconBundle
CreateIconBundle(const wxArtID
& id
,
333 const wxArtClient
& client
);