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