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