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