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     When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
  15     dialog), it does not use a hard-coded resource but asks wxArtProvider for it
  16     instead. This way users can plug in their own wxArtProvider class and easily
  17     replace standard art with their own version. All
  18     that is needed is to derive a class from wxArtProvider, override either its
  19     wxArtProvider::CreateBitmap and/or its
  20     wxArtProvider::CreateIconBundle methods
  21     and register the provider with
  22     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
  43     you should probably consider overriding wxArtProvider::CreateIconBundle
  44     and supplying icon bundles that contain different bitmap sizes.
  45
  46     There's another way of taking advantage of this class: you can use it in your
  47     code and use
  48     platform native icons as provided by wxArtProvider::GetBitmap or
  49     wxArtProvider::GetIcon (NB: this is not yet really
  50     possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
  51     small).
  52
  53
  54     wxArtProvider::~wxArtProvider
  55     wxArtProvider::CreateBitmap
  56     wxArtProvider::CreateIconBundle
  57     wxArtProvider::Delete
  58     wxArtProvider::GetBitmap
  59     wxArtProvider::GetIconBundle
  60     wxArtProvider::GetIcon
  61     wxArtProvider::Insert
  62     wxArtProvider::Pop
  63     wxArtProvider::Push
  64     wxArtProvider::Remove
  65
  66
  67     Identifying art resources
  68
  69     Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
  70     is used when
  71     requesting a resource from it. The ID is represented by wxArtID type and can
  72     have one of these predefined values (you can see bitmaps represented by these
  73     constants in the artprov() sample):
  74
  75      wxART_ERROR
  76      wxART_QUESTION
  77      wxART_WARNING
  78      wxART_INFORMATION
  79      wxART_ADD_BOOKMARK
  80      wxART_DEL_BOOKMARK
  81      wxART_HELP_SIDE_PANEL
  82      wxART_HELP_SETTINGS
  83      wxART_HELP_BOOK
  84      wxART_HELP_FOLDER
  85      wxART_HELP_PAGE
  86      wxART_GO_BACK
  87      wxART_GO_FORWARD
  88      wxART_GO_UP
  89      wxART_GO_DOWN
  90      wxART_GO_TO_PARENT
  91      wxART_GO_HOME
  92      wxART_PRINT
  93      wxART_HELP
  94      wxART_TIP
  95      wxART_REPORT_VIEW
  96      wxART_LIST_VIEW
  97      wxART_NEW_DIR
  98      wxART_FOLDER
  99      wxART_FOLDER_OPEN
 100      wxART_GO_DIR_UP
 101      wxART_EXECUTABLE_FILE
 102      wxART_NORMAL_FILE
 103      wxART_TICK_MARK
 104      wxART_CROSS_MARK
 105      wxART_MISSING_IMAGE
 106      wxART_NEW
 107      wxART_FILE_OPEN
 108      wxART_FILE_SAVE
 109      wxART_FILE_SAVE_AS
 110      wxART_DELETE
 111      wxART_COPY
 112      wxART_CUT
 113      wxART_PASTE
 114      wxART_UNDO
 115      wxART_REDO
 116      wxART_QUIT
 117      wxART_FIND
 118      wxART_FIND_AND_REPLACE
 119      wxART_HARDDISK
 120      wxART_FLOPPY
 121      wxART_CDROM
 122      wxART_REMOVABLE
 123
 124
 125     Additionally, any string recognized by custom art providers registered using
 126     wxArtProvider::Push may be used.
 127
 128     @library{wxcore}
 129     @category{FIXME}
 130
 131     @see See the artprov() sample for an example of wxArtProvider usage.
 132 */
 133 class wxArtProvider : public wxObject
 134 {
 135 public:
 136     /**
 137         The destructor automatically removes the provider from the provider stack used
 138         by GetBitmap().
 139     */
 140     ~wxArtProvider();
 141
 142     /**
 143         Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
 144         function. It is represented by wxClientID type and can have one of these
 145         values:
 146          wxART_TOOLBAR
 147          wxART_MENU
 148          wxART_BUTTON
 149          wxART_FRAME_ICON
 150          wxART_CMN_DIALOG
 151          wxART_HELP_BROWSER
 152          wxART_MESSAGE_BOX
 153          wxART_OTHER (used for all requests that don't fit into any of the categories
 154         above)
 155         Client ID servers as a hint to wxArtProvider that is supposed to help it to
 156         choose the best looking bitmap. For example it is often desirable to use
 157         slightly different icons in menus and toolbars even though they represent the
 158         same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really
 159         only a hint for wxArtProvider -- it is common that
 160         GetBitmap()
 161         returns identical bitmap for different @e client values!
 162
 163         @see See the artprov() sample for an example of wxArtProvider usage.
 164     */
 165
 166
 167     /**
 168         Derived art provider classes must override this method to create requested art
 169         resource. Note that returned bitmaps are cached by wxArtProvider and it is
 170         therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
 171         create wxBitmap objects from XPMs here).
 172
 173         @param id
 174             wxArtID unique identifier of the bitmap.
 175         @param client
 176             wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 177             This only servers as a hint.
 178         @param size
 179             Preferred size of the bitmap. The function may return a bitmap of different
 180             dimensions, it will be automatically rescaled to meet client's request.
 181
 182         @see CreateIconBundle()
 183     */
 184     wxBitmap CreateBitmap(const wxArtID& id,
 185                           const wxArtClient& client,
 186                           const wxSize& size);
 187
 188     /**
 189         This method is similar to CreateBitmap() but
 190         can be used when a bitmap (or an icon) exists in several sizes.
 191     */
 192     wxIconBundle CreateIconBundle(const wxArtID& id,
 193                                   const wxArtClient& client);
 194
 195     /**
 196         Delete the given @e provider.
 197     */
 198     static bool Delete(wxArtProvider* provider);
 199
 200     /**
 201         Query registered providers for bitmap with given ID.
 202
 203         @param id
 204             wxArtID unique identifier of the bitmap.
 205         @param client
 206             wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 207         @param size
 208             Size of the returned bitmap or wxDefaultSize if size doesn't matter.
 209
 210         @returns The bitmap if one of registered providers recognizes the ID or
 211                  wxNullBitmap otherwise.
 212     */
 213     static wxBitmap GetBitmap(const wxArtID& id,
 214                               const wxArtClient& client = wxART_OTHER,
 215                               const wxSize& size = wxDefaultSize);
 216
 217     //@{
 218     /**
 219         Returns a suitable size hint for the given @e wxArtClient. If
 220         @a platform_default is @true, return a size based on the current platform,
 221         otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
 222         be
 223         returned if the client doesn't have a specified size, like wxART_OTHER for
 224         example.
 225     */
 226     static wxIcon GetIcon(const wxArtID& id,
 227                           const wxArtClient& client = wxART_OTHER,
 228                           const wxSize& size = wxDefaultSize);
 229     static wxSize GetSizeHint(const wxArtClient& client,
 230                               bool platform_default = false);
 231     //@}
 232
 233     /**
 234         Query registered providers for icon bundle with given ID.
 235
 236         @param id
 237             wxArtID unique identifier of the icon bundle.
 238         @param client
 239             wxArtClient identifier of the client (i.e. who is asking for the icon
 240         bundle).
 241
 242         @returns The icon bundle if one of registered providers recognizes the ID
 243                  or wxNullIconBundle otherwise.
 244     */
 245     static wxIconBundle GetIconBundle(const wxArtID& id,
 246                                       const wxArtClient& client = wxART_OTHER);
 247
 248     /**
 249         Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
 250         is used when
 251         requesting a resource from it. The ID is represented by wxArtID type and can
 252         have one of these predefined values (you can see bitmaps represented by these
 253         constants in the artprov() sample):
 254
 255          wxART_ERROR
 256          wxART_QUESTION
 257          wxART_WARNING
 258          wxART_INFORMATION
 259          wxART_ADD_BOOKMARK
 260          wxART_DEL_BOOKMARK
 261          wxART_HELP_SIDE_PANEL
 262          wxART_HELP_SETTINGS
 263          wxART_HELP_BOOK
 264          wxART_HELP_FOLDER
 265          wxART_HELP_PAGE
 266          wxART_GO_BACK
 267          wxART_GO_FORWARD
 268          wxART_GO_UP
 269          wxART_GO_DOWN
 270          wxART_GO_TO_PARENT
 271          wxART_GO_HOME
 272          wxART_PRINT
 273          wxART_HELP
 274          wxART_TIP
 275          wxART_REPORT_VIEW
 276          wxART_LIST_VIEW
 277          wxART_NEW_DIR
 278          wxART_FOLDER
 279          wxART_FOLDER_OPEN
 280          wxART_GO_DIR_UP
 281          wxART_EXECUTABLE_FILE
 282          wxART_NORMAL_FILE
 283          wxART_TICK_MARK
 284          wxART_CROSS_MARK
 285          wxART_MISSING_IMAGE
 286          wxART_NEW
 287          wxART_FILE_OPEN
 288          wxART_FILE_SAVE
 289          wxART_FILE_SAVE_AS
 290          wxART_DELETE
 291          wxART_COPY
 292          wxART_CUT
 293          wxART_PASTE
 294          wxART_UNDO
 295          wxART_REDO
 296          wxART_QUIT
 297          wxART_FIND
 298          wxART_FIND_AND_REPLACE
 299          wxART_HARDDISK
 300          wxART_FLOPPY
 301          wxART_CDROM
 302          wxART_REMOVABLE
 303         Additionally, any string recognized by custom art providers registered using
 304         Push() may be used.
 305     */
 306
 307
 308     /**
 309         Register new art provider and add it to the bottom of providers stack (i.e.
 310         it will be queried as the last one).
 311
 312         @see Push()
 313     */
 314     static void Insert(wxArtProvider* provider);
 315
 316     /**
 317         Remove latest added provider and delete it.
 318     */
 319     static bool Pop();
 320
 321     /**
 322         Register new art provider and add it to the top of providers stack (i.e. it
 323         will be queried as the first provider).
 324
 325         @see Insert()
 326     */
 327     static void Push(wxArtProvider* provider);
 328
 329     /**
 330         Remove a provider from the stack if it is on it. The provider is not
 331         deleted, unlike when using Delete().
 332     */
 333     static bool Remove(wxArtProvider* provider);
 334 };
 335