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