X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..7c0d297a1f761de31d3a4ac924fa2080b5bbaf41:/interface/artprov.h diff --git a/interface/artprov.h b/interface/artprov.h index d46f0d8ae7..e6e13df265 100644 --- a/interface/artprov.h +++ b/interface/artprov.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: artprov.h -// Purpose: documentation for wxArtProvider class +// Purpose: interface of wxArtProvider // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,26 +9,26 @@ /** @class wxArtProvider @wxheader{artprov.h} - + wxArtProvider class is used to customize the look of wxWidgets application. + When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file dialog), it does not use a hard-coded resource but asks wxArtProvider for it instead. This way users can plug in their own wxArtProvider class and easily - replace standard art with their own version. All - that is needed is to derive a class from wxArtProvider, override either its - wxArtProvider::CreateBitmap and/or its - wxArtProvider::CreateIconBundle methods - and register the provider with - wxArtProvider::Push: - + replace standard art with their own version. + + All that is needed is to derive a class from wxArtProvider, override either its + wxArtProvider::CreateBitmap() and/or its wxArtProvider::CreateIconBundle() methods + and register the provider with wxArtProvider::Push(): + @code - class MyProvider : public wxArtProvider + class MyProvider : public wxArtProvider { protected: - wxBitmap CreateBitmap(const wxArtID& id, + wxBitmap CreateBitmap(const wxArtID& id, const wxArtClient& client, const wxSize size) - + // optionally override this one as well wxIconBundle CreateIconBundle(const wxArtID& id, const wxArtClient& client) @@ -37,99 +37,122 @@ ... wxArtProvider::Push(new MyProvider); @endcode - + If you need bitmap images (of the same artwork) that should be displayed at - different sizes - you should probably consider overriding wxArtProvider::CreateIconBundle + different sizes you should probably consider overriding wxArtProvider::CreateIconBundle and supplying icon bundles that contain different bitmap sizes. - + There's another way of taking advantage of this class: you can use it in your - code and use - platform native icons as provided by wxArtProvider::GetBitmap or - wxArtProvider::GetIcon (NB: this is not yet really - possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too - small). - - - wxArtProvider::~wxArtProvider - wxArtProvider::CreateBitmap - wxArtProvider::CreateIconBundle - wxArtProvider::Delete - wxArtProvider::GetBitmap - wxArtProvider::GetIconBundle - wxArtProvider::GetIcon - wxArtProvider::Insert - wxArtProvider::Pop - wxArtProvider::Push - wxArtProvider::Remove - - - Identifying art resources - + code and use platform native icons as provided by wxArtProvider::GetBitmap or + wxArtProvider::GetIcon. + + @todo IS THIS NB TRUE? + (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider + bitmaps is too small). + + @section wxartprovider_identify Identifying art resources + Every bitmap and icon bundle are known to wxArtProvider under an unique ID that - is used when - requesting a resource from it. The ID is represented by wxArtID type and can - have one of these predefined values (you can see bitmaps represented by these - constants in the artprov sample): - - wxART_ERROR - wxART_QUESTION - wxART_WARNING - wxART_INFORMATION - wxART_ADD_BOOKMARK - wxART_DEL_BOOKMARK - wxART_HELP_SIDE_PANEL - wxART_HELP_SETTINGS - wxART_HELP_BOOK - wxART_HELP_FOLDER - wxART_HELP_PAGE - wxART_GO_BACK - wxART_GO_FORWARD - wxART_GO_UP - wxART_GO_DOWN - wxART_GO_TO_PARENT - wxART_GO_HOME - wxART_PRINT - wxART_HELP - wxART_TIP - wxART_REPORT_VIEW - wxART_LIST_VIEW - wxART_NEW_DIR - wxART_FOLDER - wxART_FOLDER_OPEN - wxART_GO_DIR_UP - wxART_EXECUTABLE_FILE - wxART_NORMAL_FILE - wxART_TICK_MARK - wxART_CROSS_MARK - wxART_MISSING_IMAGE - wxART_NEW - wxART_FILE_OPEN - wxART_FILE_SAVE - wxART_FILE_SAVE_AS - wxART_DELETE - wxART_COPY - wxART_CUT - wxART_PASTE - wxART_UNDO - wxART_REDO - wxART_QUIT - wxART_FIND - wxART_FIND_AND_REPLACE - wxART_HARDDISK - wxART_FLOPPY - wxART_CDROM - wxART_REMOVABLE - - - Additionally, any string recognized by custom art providers registered using + is used when requesting a resource from it. The ID is represented by wxArtID type + and can have one of these predefined values (you can see bitmaps represented by these + constants in the @ref page_samples_artprovider): + + + +
+ @li wxART_ERROR + @li wxART_QUESTION + @li wxART_WARNING + @li wxART_INFORMATION + @li wxART_ADD_BOOKMARK + @li wxART_DEL_BOOKMARK + @li wxART_HELP_SIDE_PANEL + @li wxART_HELP_SETTINGS + @li wxART_HELP_BOOK + @li wxART_HELP_FOLDER + @li wxART_HELP_PAGE + @li wxART_GO_BACK + @li wxART_GO_FORWARD + @li wxART_GO_UP + + @li wxART_GO_DOWN + @li wxART_GO_TO_PARENT + @li wxART_GO_HOME + @li wxART_PRINT + @li wxART_HELP + @li wxART_TIP + @li wxART_REPORT_VIEW + @li wxART_LIST_VIEW + @li wxART_NEW_DIR + @li wxART_FOLDER + @li wxART_FOLDER_OPEN + @li wxART_GO_DIR_UP + @li wxART_EXECUTABLE_FILE + @li wxART_NORMAL_FILE + @li wxART_TICK_MARK + @li wxART_CROSS_MARK + + @li wxART_MISSING_IMAGE + @li wxART_NEW + @li wxART_FILE_OPEN + @li wxART_FILE_SAVE + @li wxART_FILE_SAVE_AS + @li wxART_DELETE + @li wxART_COPY + @li wxART_CUT + @li wxART_PASTE + @li wxART_UNDO + @li wxART_REDO + @li wxART_QUIT + @li wxART_FIND + @li wxART_FIND_AND_REPLACE + @li wxART_HARDDISK + @li wxART_FLOPPY + @li wxART_CDROM + @li wxART_REMOVABLE +
+ + Additionally, any string recognized by custom art providers registered using wxArtProvider::Push may be used. - + + @note + When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used + as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is also + possible to load icons from current icon theme by specifying their name (without + extension and directory components). + Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification + (see http://freedesktop.org/Standards/icon-theme-spec). + Note that themes are not guaranteed to contain all icons, so wxArtProvider may + return ::wxNullBitmap or ::wxNullIcon. + The default theme is typically installed in @c /usr/share/icons/hicolor. + + + @section wxartprovider_clients Clients + + Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function. + It is represented by wxClientID type and can have one of these values: + + @li wxART_TOOLBAR + @li wxART_MENU + @li wxART_BUTTON + @li wxART_FRAME_ICON + @li wxART_CMN_DIALOG + @li wxART_HELP_BROWSER + @li wxART_MESSAGE_BOX + @li wxART_OTHER (used for all requests that don't fit into any of the + categories above) + + Client ID servers as a hint to wxArtProvider that is supposed to help it to + choose the best looking bitmap. For example it is often desirable to use + slightly different icons in menus and toolbars even though they represent + the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a + hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns + identical bitmap for different client values! + @library{wxcore} - @category{FIXME} - - @seealso - See the artprov sample for an example of wxArtProvider usage. + @category{misc,data} + + @see the @ref page_samples_artprovider for an example of wxArtProvider usage. */ class wxArtProvider : public wxObject { @@ -138,205 +161,123 @@ public: The destructor automatically removes the provider from the provider stack used by GetBitmap(). */ - ~wxArtProvider(); - - /** - Client is the entity that calls wxArtProvider's GetBitmap or GetIcon - function. It is represented by wxClientID type and can have one of these - values: - - wxART_TOOLBAR - wxART_MENU - wxART_BUTTON - wxART_FRAME_ICON - wxART_CMN_DIALOG - wxART_HELP_BROWSER - wxART_MESSAGE_BOX - wxART_OTHER (used for all requests that don't fit into any of the categories - above) - - Client ID servers as a hint to wxArtProvider that is supposed to help it to - choose the best looking bitmap. For example it is often desirable to use - slightly different icons in menus and toolbars even though they represent the - same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really - only a hint for wxArtProvider -- it is common that - GetBitmap() - returns identical bitmap for different @e client values! - - @sa See the artprov sample for an example of wxArtProvider usage. - */ - - - /** - Derived art provider classes must override this method to create requested art - resource. Note that returned bitmaps are cached by wxArtProvider and it is - therefore not necessary to optimize CreateBitmap() for speed (e.g. you may - create wxBitmap objects from XPMs here). - - @param id - wxArtID unique identifier of the bitmap. - - @param client - wxArtClient identifier of the client (i.e. who is asking for the bitmap). - This only servers as a hint. - - @param size - Preferred size of the bitmap. The function may return a bitmap of different - dimensions, it will be automatically rescaled to meet client's request. - - @sa CreateIconBundle() - */ - wxBitmap CreateBitmap(const wxArtID& id, - const wxArtClient& client, - const wxSize& size); - - /** - This method is similar to CreateBitmap() but - can be used when a bitmap (or an icon) exists in several sizes. - */ - wxIconBundle CreateIconBundle(const wxArtID& id, - const wxArtClient& client); + virtual ~wxArtProvider(); /** - Delete the given @e provider. + Delete the given @a provider. */ static bool Delete(wxArtProvider* provider); /** Query registered providers for bitmap with given ID. - - @param id - wxArtID unique identifier of the bitmap. - - @param client - wxArtClient identifier of the client (i.e. who is asking for the bitmap). - - @param size - Size of the returned bitmap or wxDefaultSize if size doesn't matter. - + + @param id + wxArtID unique identifier of the bitmap. + @param client + wxArtClient identifier of the client (i.e. who is asking for the bitmap). + @param size + Size of the returned bitmap or wxDefaultSize if size doesn't matter. + @returns The bitmap if one of registered providers recognizes the ID or - wxNullBitmap otherwise. + wxNullBitmap otherwise. */ static wxBitmap GetBitmap(const wxArtID& id, const wxArtClient& client = wxART_OTHER, const wxSize& size = wxDefaultSize); - //@{ /** - Returns a suitable size hint for the given @e wxArtClient. If - @e platform_default is @true, return a size based on the current platform, - otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may - be - returned if the client doesn't have a specified size, like wxART_OTHER for - example. + Same as wxArtProvider::GetBitmap, but return a wxIcon object + (or ::wxNullIcon on failure). */ static wxIcon GetIcon(const wxArtID& id, const wxArtClient& client = wxART_OTHER, const wxSize& size = wxDefaultSize); - static wxSize GetSizeHint(const wxArtClient& client, - bool platform_default = @false); - //@} + + /** + Returns a suitable size hint for the given @e wxArtClient. If + @a platform_default is @true, return a size based on the current platform, + otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may + be returned if the client doesn't have a specified size, like wxART_OTHER for + example. + */ + static wxSize GetSizeHint(const wxArtClient& client, + bool platform_default = false); /** Query registered providers for icon bundle with given ID. - - @param id - wxArtID unique identifier of the icon bundle. - - @param client - wxArtClient identifier of the client (i.e. who is asking for the icon bundle). - + + @param id + wxArtID unique identifier of the icon bundle. + @param client + wxArtClient identifier of the client (i.e. who is asking for the icon + bundle). + @returns The icon bundle if one of registered providers recognizes the ID - or wxNullIconBundle otherwise. + or wxNullIconBundle otherwise. */ static wxIconBundle GetIconBundle(const wxArtID& id, const wxArtClient& client = wxART_OTHER); /** - Every bitmap and icon bundle are known to wxArtProvider under an unique ID that - is used when - requesting a resource from it. The ID is represented by wxArtID type and can - have one of these predefined values (you can see bitmaps represented by these - constants in the artprov sample): - - wxART_ERROR - wxART_QUESTION - wxART_WARNING - wxART_INFORMATION - wxART_ADD_BOOKMARK - wxART_DEL_BOOKMARK - wxART_HELP_SIDE_PANEL - wxART_HELP_SETTINGS - wxART_HELP_BOOK - wxART_HELP_FOLDER - wxART_HELP_PAGE - wxART_GO_BACK - wxART_GO_FORWARD - wxART_GO_UP - wxART_GO_DOWN - wxART_GO_TO_PARENT - wxART_GO_HOME - wxART_PRINT - wxART_HELP - wxART_TIP - wxART_REPORT_VIEW - wxART_LIST_VIEW - wxART_NEW_DIR - wxART_FOLDER - wxART_FOLDER_OPEN - wxART_GO_DIR_UP - wxART_EXECUTABLE_FILE - wxART_NORMAL_FILE - wxART_TICK_MARK - wxART_CROSS_MARK - wxART_MISSING_IMAGE - wxART_NEW - wxART_FILE_OPEN - wxART_FILE_SAVE - wxART_FILE_SAVE_AS - wxART_DELETE - wxART_COPY - wxART_CUT - wxART_PASTE - wxART_UNDO - wxART_REDO - wxART_QUIT - wxART_FIND - wxART_FIND_AND_REPLACE - wxART_HARDDISK - wxART_FLOPPY - wxART_CDROM - wxART_REMOVABLE - - Additionally, any string recognized by custom art providers registered using - Push() may be used. - */ + Register new art provider and add it to the bottom of providers stack + (i.e. it will be queried as the last one). - - /** - Register new art provider and add it to the bottom of providers stack (i.e. - it will be queried as the last one). - - @sa Push() + @see Push() */ static void Insert(wxArtProvider* provider); /** Remove latest added provider and delete it. */ -#define static bool Pop() /* implementation is private */ + static bool Pop(); /** - Register new art provider and add it to the top of providers stack (i.e. it - will be queried as the first provider). - - @sa Insert() + Register new art provider and add it to the top of providers stack + (i.e. it will be queried as the first provider). + + @see Insert() */ static void Push(wxArtProvider* provider); /** - Remove a provider from the stack if it is on it. The provider is not + Remove a provider from the stack if it is on it. The provider is not deleted, unlike when using Delete(). */ static bool Remove(wxArtProvider* provider); + +protected: + + /** + Derived art provider classes must override this method to create requested art + resource. Note that returned bitmaps are cached by wxArtProvider and it is + therefore not necessary to optimize CreateBitmap() for speed (e.g. you may + create wxBitmap objects from XPMs here). + + @param id + wxArtID unique identifier of the bitmap. + @param client + wxArtClient identifier of the client (i.e. who is asking for the bitmap). + This only servers as a hint. + @param size + Preferred size of the bitmap. The function may return a bitmap of different + dimensions, it will be automatically rescaled to meet client's request. + + @note + This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap + or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider + for a resource. + + @see CreateIconBundle() + */ + virtual wxBitmap CreateBitmap(const wxArtID& id, + const wxArtClient& client, + const wxSize& size); + + /** + This method is similar to CreateBitmap() but can be used when a bitmap + (or an icon) exists in several sizes. + */ + virtual wxIconBundle CreateIconBundle(const wxArtID& id, + const wxArtClient& client); }; +