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