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