X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..de536319f16406adf967003637b2655c61f6cb09:/interface/artprov.h diff --git a/interface/artprov.h b/interface/artprov.h index 695c9d500b..fc50474b81 100644 --- a/interface/artprov.h +++ b/interface/artprov.h @@ -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,96 +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? + (@note 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_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} - @see See the artprov() sample for an example of wxArtProvider usage. + @see the @ref page_samples_artprovider for an example of wxArtProvider usage. */ class wxArtProvider : public wxObject { @@ -137,178 +161,67 @@ public: The destructor automatically removes the provider from the provider stack used by GetBitmap(). */ - ~wxArtProvider(); + virtual ~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! - - @see 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. - - @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. - */ - wxIconBundle CreateIconBundle(const wxArtID& id, - const wxArtClient& client); - - /** - 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. - - @returns The bitmap if one of registered providers recognizes the ID or - wxNullBitmap otherwise. + + @return The bitmap if one of registered providers recognizes the ID or + wxNullBitmap otherwise. */ static wxBitmap GetBitmap(const wxArtID& id, const wxArtClient& client = wxART_OTHER, const wxSize& size = wxDefaultSize); - //@{ + /** + 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 + be returned if the client doesn't have a specified size, like wxART_OTHER for example. */ - 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); - //@} /** 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). - - @returns The icon bundle if one of registered providers recognizes the ID - or wxNullIconBundle otherwise. + bundle). + + @return The icon bundle if one of registered providers recognizes the ID + 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). - @see Push() */ static void Insert(wxArtProvider* provider); @@ -319,9 +232,9 @@ public: 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). + @see Insert() */ static void Push(wxArtProvider* provider); @@ -331,5 +244,40 @@ public: 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); };