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