interface/artprov.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        artprov.h
   3 // Purpose:     documentation for wxArtProvider class
   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     @seealso
 132     See the artprov sample for an example of wxArtProvider usage.
 133 */
 134 class wxArtProvider : public wxObject
 135 {
 136 public:
 137     /**
 138         The destructor automatically removes the provider from the provider stack used
 139         by GetBitmap().
 140     */
 141     ~wxArtProvider();
 142
 143     /**
 144         Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
 145         function. It is represented by wxClientID type and can have one of these
 146         values:
 147
 148          wxART_TOOLBAR
 149          wxART_MENU
 150          wxART_BUTTON
 151          wxART_FRAME_ICON
 152          wxART_CMN_DIALOG
 153          wxART_HELP_BROWSER
 154          wxART_MESSAGE_BOX
 155          wxART_OTHER (used for all requests that don't fit into any of the categories
 156         above)
 157
 158         Client ID servers as a hint to wxArtProvider that is supposed to help it to
 159         choose the best looking bitmap. For example it is often desirable to use
 160         slightly different icons in menus and toolbars even though they represent the
 161         same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really
 162         only a hint for wxArtProvider -- it is common that
 163         GetBitmap()
 164         returns identical bitmap for different @e client values!
 165
 166         @sa See the artprov sample for an example of wxArtProvider usage.
 167     */
 168
 169
 170     /**
 171         Derived art provider classes must override this method to create requested art
 172         resource. Note that returned bitmaps are cached by wxArtProvider and it is
 173         therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
 174         create wxBitmap objects from XPMs here).
 175
 176         @param id
 177         wxArtID unique identifier of the bitmap.
 178
 179         @param client
 180         wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 181         This only servers as a hint.
 182
 183         @param size
 184         Preferred size of the bitmap. The function may return a bitmap of different
 185         dimensions, it will be automatically rescaled to meet client's request.
 186
 187         @sa CreateIconBundle()
 188     */
 189     wxBitmap CreateBitmap(const wxArtID& id,
 190                           const wxArtClient& client,
 191                           const wxSize& size);
 192
 193     /**
 194         This method is similar to CreateBitmap() but
 195         can be used when a bitmap (or an icon) exists in several sizes.
 196     */
 197     wxIconBundle CreateIconBundle(const wxArtID& id,
 198                                   const wxArtClient& client);
 199
 200     /**
 201         Delete the given @e provider.
 202     */
 203     static bool Delete(wxArtProvider* provider);
 204
 205     /**
 206         Query registered providers for bitmap with given ID.
 207
 208         @param id
 209         wxArtID unique identifier of the bitmap.
 210
 211         @param client
 212         wxArtClient identifier of the client (i.e. who is asking for the bitmap).
 213
 214         @param size
 215         Size of the returned bitmap or wxDefaultSize if size doesn't matter.
 216
 217         @returns The bitmap if one of registered providers recognizes the ID or
 218                    wxNullBitmap otherwise.
 219     */
 220     static wxBitmap GetBitmap(const wxArtID& id,
 221                               const wxArtClient& client = wxART_OTHER,
 222                               const wxSize& size = wxDefaultSize);
 223
 224     //@{
 225     /**
 226         Returns a suitable size hint for the given @e wxArtClient. If
 227         @e platform_default is @true, return a size based on the current platform,
 228         otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
 229         be
 230         returned if the client doesn't have a specified size, like wxART_OTHER for
 231         example.
 232     */
 233     static wxIcon GetIcon(const wxArtID& id,
 234                           const wxArtClient& client = wxART_OTHER,
 235                           const wxSize& size = wxDefaultSize);
 236     static wxSize GetSizeHint(const wxArtClient& client,
 237                               bool platform_default = @false);
 238     //@}
 239
 240     /**
 241         Query registered providers for icon bundle with given ID.
 242
 243         @param id
 244         wxArtID unique identifier of the icon bundle.
 245
 246         @param client
 247         wxArtClient identifier of the client (i.e. who is asking for the icon bundle).
 248
 249         @returns The icon bundle if one of registered providers recognizes the ID
 250                    or wxNullIconBundle otherwise.
 251     */
 252     static wxIconBundle GetIconBundle(const wxArtID& id,
 253                                       const wxArtClient& client = wxART_OTHER);
 254
 255     /**
 256         Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
 257         is used when
 258         requesting a resource from it. The ID is represented by wxArtID type and can
 259         have one of these predefined values (you can see bitmaps represented by these
 260         constants in the artprov sample):
 261
 262          wxART_ERROR
 263          wxART_QUESTION
 264          wxART_WARNING
 265          wxART_INFORMATION
 266          wxART_ADD_BOOKMARK
 267          wxART_DEL_BOOKMARK
 268          wxART_HELP_SIDE_PANEL
 269          wxART_HELP_SETTINGS
 270          wxART_HELP_BOOK
 271          wxART_HELP_FOLDER
 272          wxART_HELP_PAGE
 273          wxART_GO_BACK
 274          wxART_GO_FORWARD
 275          wxART_GO_UP
 276          wxART_GO_DOWN
 277          wxART_GO_TO_PARENT
 278          wxART_GO_HOME
 279          wxART_PRINT
 280          wxART_HELP
 281          wxART_TIP
 282          wxART_REPORT_VIEW
 283          wxART_LIST_VIEW
 284          wxART_NEW_DIR
 285          wxART_FOLDER
 286          wxART_FOLDER_OPEN
 287          wxART_GO_DIR_UP
 288          wxART_EXECUTABLE_FILE
 289          wxART_NORMAL_FILE
 290          wxART_TICK_MARK
 291          wxART_CROSS_MARK
 292          wxART_MISSING_IMAGE
 293          wxART_NEW
 294          wxART_FILE_OPEN
 295          wxART_FILE_SAVE
 296          wxART_FILE_SAVE_AS
 297          wxART_DELETE
 298          wxART_COPY
 299          wxART_CUT
 300          wxART_PASTE
 301          wxART_UNDO
 302          wxART_REDO
 303          wxART_QUIT
 304          wxART_FIND
 305          wxART_FIND_AND_REPLACE
 306          wxART_HARDDISK
 307          wxART_FLOPPY
 308          wxART_CDROM
 309          wxART_REMOVABLE
 310
 311         Additionally, any string recognized by custom art providers registered using
 312         Push() may be used.
 313     */
 314
 315
 316     /**
 317         Register new art provider and add it to the bottom of providers stack (i.e.
 318         it will be queried as the last one).
 319
 320         @sa Push()
 321     */
 322     static void Insert(wxArtProvider* provider);
 323
 324     /**
 325         Remove latest added provider and delete it.
 326     */
 327 #define static bool Pop()     /* implementation is private */
 328
 329     /**
 330         Register new art provider and add it to the top of providers stack (i.e. it
 331         will be queried as the first provider).
 332
 333         @sa Insert()
 334     */
 335     static void Push(wxArtProvider* provider);
 336
 337     /**
 338         Remove a provider from the stack if it is on it. The provider is not
 339         deleted, unlike when using Delete().
 340     */
 341     static bool Remove(wxArtProvider* provider);
 342 };