]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/artprov.h
added test of focusing/selecting another item
[wxWidgets.git] / interface / artprov.h
index 91660de670bb0064b659dddace1d41c7cb8eccb4..9883b6b77769ba5fd9a76aad7379dc09a8eafe5d 100644 (file)
@@ -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
     @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,
     @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
+    code and use platform native icons as provided by wxArtProvider::GetBitmap or
+    wxArtProvider::GetIcon.
 
+    @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):
 
+    <table>
+    <tr><td>
+     @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
+    </td><td>
+     @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
+    </td><td>
+     @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
+    </td></tr>
+    </table>
 
     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,31 +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!
-        
-        @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
@@ -179,6 +177,11 @@ public:
         @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()
     */
@@ -187,8 +190,8 @@ public:
                           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);
@@ -215,21 +218,23 @@ public:
                               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.
@@ -238,7 +243,7 @@ public:
             wxArtID unique identifier of the icon bundle.
         @param client
             wxArtClient identifier of the client (i.e. who is asking for the icon
-        bundle).
+            bundle).
         
         @returns The icon bundle if one of registered providers recognizes the ID
                  or wxNullIconBundle otherwise.
@@ -247,68 +252,8 @@ public:
                                       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()
     */
@@ -320,8 +265,8 @@ 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()
     */
@@ -333,3 +278,4 @@ public:
     */
     static bool Remove(wxArtProvider* provider);
 };
+