X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..3d6c68c1c9688885c64e8033cc6680194e8559dd:/interface/artprov.h diff --git a/interface/artprov.h b/interface/artprov.h index b54939e512..9883b6b777 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 @@ -11,18 +11,18 @@ @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, @@ -39,97 +39,120 @@ @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). - + code and use platform native icons as provided by wxArtProvider::GetBitmap or + wxArtProvider::GetIcon. - wxArtProvider::~wxArtProvider - wxArtProvider::CreateBitmap - wxArtProvider::CreateIconBundle - wxArtProvider::Delete - wxArtProvider::GetBitmap - wxArtProvider::GetIconBundle - wxArtProvider::GetIcon - wxArtProvider::Insert - wxArtProvider::Pop - wxArtProvider::Push - wxArtProvider::Remove + @todo IS THIS NB TRUE? + (NB: this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider + bitmaps is too small). - - Identifying art resources + @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 + 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_utils_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} + @category{misc,data} - @seealso - See the artprov sample for an example of wxArtProvider usage. + @see the @ref page_utils_samples_artprovider for an example of wxArtProvider usage. */ class wxArtProvider : public wxObject { @@ -140,33 +163,6 @@ public: */ ~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 @@ -174,25 +170,28 @@ public: create wxBitmap objects from XPMs here). @param id - wxArtID unique identifier of the bitmap. - + 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. - + 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. + 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. - @sa CreateIconBundle() + @see 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. + 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); @@ -206,131 +205,70 @@ public: Query registered providers for bitmap with given ID. @param id - wxArtID unique identifier of the bitmap. - + wxArtID unique identifier of the bitmap. @param client - wxArtClient identifier of the client (i.e. who is asking for the bitmap). - + 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. + 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); + + /** + 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); - //@} + bool platform_default = false); /** Query registered providers for icon bundle with given ID. @param id - wxArtID unique identifier of the icon bundle. - + wxArtID unique identifier of the icon bundle. @param client - wxArtClient identifier of the client (i.e. who is asking for the icon bundle). + 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 + Register new art provider and add it to the bottom of providers stack + (i.e. it will be queried as the last one). - 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). - - @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). + 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() + @see Insert() */ static void Push(wxArtProvider* provider); @@ -340,3 +278,4 @@ public: */ static bool Remove(wxArtProvider* provider); }; +