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 wxartprovider_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 wxartprovider_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 a suitable size hint for the given @e wxArtClient. If
 197         @a platform_default is @true, return a size based on the current platform,
 198         otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
 199         be returned if the client doesn't have a specified size, like wxART_OTHER for
 200         example.
 201     */
 202     static wxSize GetSizeHint(const wxArtClient& client,
 203                               bool platform_default = false);
 204
 205     /**
 206         Query registered providers for icon bundle with given ID.
 207
 208         @param id
 209             wxArtID unique identifier of the icon bundle.
 210         @param client
 211             wxArtClient identifier of the client (i.e. who is asking for the icon
 212             bundle).
 213
 214         @return The icon bundle if one of registered providers recognizes the ID
 215                 or wxNullIconBundle otherwise.
 216     */
 217     static wxIconBundle GetIconBundle(const wxArtID& id,
 218                                       const wxArtClient& client = wxART_OTHER);
 219
 220     /**
 221         Returns true if the platform uses native icons provider that should
 222         take precedence over any customizations.
 223
 224         This is true for any platform that has user-customizable icon themes,
 225         currently only wxGTK.
 226
 227         A typical use for this method is to decide whether a custom art provider
 228         should be plugged in using Push() or PushBack().
 229
 230         @since 2.9.0
 231      */
 232     static bool HasNativeProvider();
 233
 234     /**
 235         @deprecated Use PushBack() instead.
 236     */
 237     static void Insert(wxArtProvider* provider);
 238
 239     /**
 240         Remove latest added provider and delete it.
 241     */
 242     static bool Pop();
 243
 244     /**
 245         Register new art provider and add it to the top of providers stack
 246         (i.e. it will be queried as the first provider).
 247
 248         @see PushBack()
 249     */
 250     static void Push(wxArtProvider* provider);
 251
 252     /**
 253         Register new art provider and add it to the bottom of providers stack.
 254         In other words, it will be queried as the last one, after all others,
 255         including the default provider.
 256
 257         @see Push()
 258
 259         @since 2.9.0
 260     */
 261     static void PushBack(wxArtProvider* provider);
 262
 263     /**
 264         Remove a provider from the stack if it is on it. The provider is not
 265         deleted, unlike when using Delete().
 266     */
 267     static bool Remove(wxArtProvider* provider);
 268
 269 protected:
 270
 271     /**
 272         Derived art provider classes must override this method to create requested art
 273         resource. Note that returned bitmaps are cached by wxArtProvider and it is
 274         therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
 275         create wxBitmap objects from XPMs here).
 276
 277         @param id
 278             wxArtID unique identifier of the bitmap.
 279         @param client
 280             wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 281             This only servers as a hint.
 282         @param size
 283             Preferred size of the bitmap. The function may return a bitmap of different
 284             dimensions, it will be automatically rescaled to meet client's request.
 285
 286         @note
 287         This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap
 288         or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider
 289         for a resource.
 290
 291         @see CreateIconBundle()
 292     */
 293     virtual wxBitmap CreateBitmap(const wxArtID& id,
 294                                   const wxArtClient& client,
 295                                   const wxSize& size);
 296
 297     /**
 298         This method is similar to CreateBitmap() but can be used when a bitmap
 299         (or an icon) exists in several sizes.
 300     */
 301     virtual wxIconBundle CreateIconBundle(const wxArtID& id,
 302                                           const wxArtClient& client);
 303 };
 304