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     (NB: 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_utils_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_utils_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     ~wxArtProvider();
 165
 166     /**
 167         Derived art provider classes must override this method to create requested art
 168         resource. Note that returned bitmaps are cached by wxArtProvider and it is
 169         therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
 170         create wxBitmap objects from XPMs here).
 171
 172         @param id
 173             wxArtID unique identifier of the bitmap.
 174         @param client
 175             wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 176             This only servers as a hint.
 177         @param size
 178             Preferred size of the bitmap. The function may return a bitmap of different
 179             dimensions, it will be automatically rescaled to meet client's request.
 180
 181         @note
 182         This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap
 183         or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider
 184         for a resource.
 185
 186         @see CreateIconBundle()
 187     */
 188     wxBitmap CreateBitmap(const wxArtID& id,
 189                           const wxArtClient& client,
 190                           const wxSize& size);
 191
 192     /**
 193         This method is similar to CreateBitmap() but can be used when a bitmap
 194         (or an icon) exists in several sizes.
 195     */
 196     wxIconBundle CreateIconBundle(const wxArtID& id,
 197                                   const wxArtClient& client);
 198
 199     /**
 200         Delete the given @e provider.
 201     */
 202     static bool Delete(wxArtProvider* provider);
 203
 204     /**
 205         Query registered providers for bitmap with given ID.
 206
 207         @param id
 208             wxArtID unique identifier of the bitmap.
 209         @param client
 210             wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 211         @param size
 212             Size of the returned bitmap or wxDefaultSize if size doesn't matter.
 213
 214         @returns The bitmap if one of registered providers recognizes the ID or
 215                  wxNullBitmap otherwise.
 216     */
 217     static wxBitmap GetBitmap(const wxArtID& id,
 218                               const wxArtClient& client = wxART_OTHER,
 219                               const wxSize& size = wxDefaultSize);
 220
 221     /**
 222         Same as wxArtProvider::GetBitmap, but return a wxIcon object
 223         (or ::wxNullIcon on failure).
 224     */
 225     static wxIcon GetIcon(const wxArtID& id,
 226                           const wxArtClient& client = wxART_OTHER,
 227                           const wxSize& size = wxDefaultSize);
 228
 229     /**
 230         Returns a suitable size hint for the given @e wxArtClient. If
 231         @a platform_default is @true, return a size based on the current platform,
 232         otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
 233         be returned if the client doesn't have a specified size, like wxART_OTHER for
 234         example.
 235     */
 236     static wxSize GetSizeHint(const wxArtClient& client,
 237                               bool platform_default = false);
 238
 239     /**
 240         Query registered providers for icon bundle with given ID.
 241
 242         @param id
 243             wxArtID unique identifier of the icon bundle.
 244         @param client
 245             wxArtClient identifier of the client (i.e. who is asking for the icon
 246             bundle).
 247
 248         @returns The icon bundle if one of registered providers recognizes the ID
 249                  or wxNullIconBundle otherwise.
 250     */
 251     static wxIconBundle GetIconBundle(const wxArtID& id,
 252                                       const wxArtClient& client = wxART_OTHER);
 253
 254     /**
 255         Register new art provider and add it to the bottom of providers stack
 256         (i.e. it will be queried as the last one).
 257
 258         @see Push()
 259     */
 260     static void Insert(wxArtProvider* provider);
 261
 262     /**
 263         Remove latest added provider and delete it.
 264     */
 265     static bool Pop();
 266
 267     /**
 268         Register new art provider and add it to the top of providers stack
 269         (i.e. it will be queried as the first provider).
 270
 271         @see Insert()
 272     */
 273     static void Push(wxArtProvider* provider);
 274
 275     /**
 276         Remove a provider from the stack if it is on it. The provider is not
 277         deleted, unlike when using Delete().
 278     */
 279     static bool Remove(wxArtProvider* provider);
 280 };
 281