interface/wx/artprov.h

   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 servers 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