fix GetTextExtent with non-null font argument, fixes #13750

[wxWidgets.git] / interface / wx / artprov.h

diff --git a/interface/wx/artprov.h b/interface/wx/artprov.h
index fc50474b81324a0d3163bf882e2478b7facd5977..3b4f092095129979b4db23e22c929fb05f5cc24a 100644 (file)
--- a/interface/wx/artprov.h
+++ b/interface/wx/artprov.h
@@ -3,12 +3,22 @@
 // Purpose:     interface of wxArtProvider
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxArtProvider
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    This type identifies the client of the art objects requested to wxArtProvider.
+*/
+typedef class wxString wxArtClient;
+
+/**
+    This type identifies a specific art object which can be requested to wxArtProvider.
+*/
+typedef class wxString wxArtID;
+
+

 /**
     @class wxArtProvider
 /**
     @class wxArtProvider

-    @wxheader{artprov.h}

 
     wxArtProvider class is used to customize the look of wxWidgets application.
 
 
     wxArtProvider class is used to customize the look of wxWidgets application.
 


@@ -46,69 +56,70 @@
     code and use platform native icons as provided by wxArtProvider::GetBitmap or
     wxArtProvider::GetIcon.
 
     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
+    @section artprovider_identify Identifying art resources

 
     Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
 
     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
+    is used when requesting a resource from it. The ID is represented by the ::wxArtID type

     and can have one of these predefined values (you can see bitmaps represented by these
     and can have one of these predefined values (you can see bitmaps represented by these

-    constants in the @ref page_samples_artprovider):
+    constants in the @ref page_samples_artprov):

 
     <table>
     <tr><td>
 
     <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
+     @li @c wxART_ERROR
+     @li @c wxART_QUESTION
+     @li @c wxART_WARNING
+     @li @c wxART_INFORMATION
+     @li @c wxART_ADD_BOOKMARK
+     @li @c wxART_DEL_BOOKMARK
+     @li @c wxART_HELP_SIDE_PANEL
+     @li @c wxART_HELP_SETTINGS
+     @li @c wxART_HELP_BOOK
+     @li @c wxART_HELP_FOLDER
+     @li @c wxART_HELP_PAGE
+     @li @c wxART_GO_BACK
+     @li @c wxART_GO_FORWARD
+     @li @c wxART_GO_UP
+     @li @c wxART_GO_DOWN
+     @li @c wxART_GO_TO_PARENT
+     @li @c wxART_GO_HOME
+     @li @c wxART_GOTO_FIRST (since 2.9.2)
+     </td><td>
+     @li @c wxART_GOTO_LAST (since 2.9.2)
+     @li @c wxART_PRINT
+     @li @c wxART_HELP
+     @li @c wxART_TIP
+     @li @c wxART_REPORT_VIEW
+     @li @c wxART_LIST_VIEW
+     @li @c wxART_NEW_DIR
+     @li @c wxART_FOLDER
+     @li @c wxART_FOLDER_OPEN
+     @li @c wxART_GO_DIR_UP
+     @li @c wxART_EXECUTABLE_FILE
+     @li @c wxART_NORMAL_FILE
+     @li @c wxART_TICK_MARK
+     @li @c wxART_CROSS_MARK
+     @li @c wxART_MISSING_IMAGE
+     @li @c wxART_NEW
+     @li @c wxART_FILE_OPEN
+     @li @c wxART_FILE_SAVE
+     </td><td>
+     @li @c wxART_FILE_SAVE_AS
+     @li @c wxART_DELETE
+     @li @c wxART_COPY
+     @li @c wxART_CUT
+     @li @c wxART_PASTE
+     @li @c wxART_UNDO
+     @li @c wxART_REDO
+     @li @c wxART_PLUS (since 2.9.2)
+     @li @c wxART_MINUS (since 2.9.2)
+     @li @c wxART_CLOSE
+     @li @c wxART_QUIT
+     @li @c wxART_FIND
+     @li @c wxART_FIND_AND_REPLACE
+     @li @c wxART_HARDDISK
+     @li @c wxART_FLOPPY
+     @li @c wxART_CDROM
+     @li @c wxART_REMOVABLE

     </td></tr>
     </table>
 
     </td></tr>
     </table>
 


@@ -117,32 +128,40 @@
 
     @note
     When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") 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).
+    as well:
+    @code
+    #ifdef __WXGTK__
+        wxBitmap bmp = wxArtProvider::GetBitmap("gtk-cdrom", wxART_MENU);
+    #endif
+    @endcode
+    For a list of the GTK+ stock items please refer to the
+    <a href="http://library.gnome.org/devel/gtk/stable/gtk-Stock-Items.html">GTK+ documentation
+    page</a>.
+    It is also possible to load icons from the current icon theme by specifying their name 
+    (without extension and directory components).
+    Icon themes recognized by GTK+ follow the freedesktop.org
+    <a href="http://freedesktop.org/Standards/icon-theme-spec">Icon Themes specification</a>.

     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.
 
 
     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
+    @section artprovider_clients Clients

 
 

-    Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function.
+    The @e 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:
 
     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
+    @li @c wxART_TOOLBAR
+    @li @c wxART_MENU
+    @li @c wxART_BUTTON
+    @li @c wxART_FRAME_ICON
+    @li @c wxART_CMN_DIALOG
+    @li @c wxART_HELP_BROWSER
+    @li @c wxART_MESSAGE_BOX
+    @li @c wxART_OTHER (used for all requests that don't fit into any of the

         categories above)
 
         categories above)
 

-    Client ID servers as a hint to wxArtProvider that is supposed to help it to
+    Client ID serve 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
     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


@@ -150,9 +169,10 @@
     identical bitmap for different client values!
 
     @library{wxcore}
     identical bitmap for different client values!
 
     @library{wxcore}

-    @category{misc,data}
+    @category{misc}

 
 

-    @see the @ref page_samples_artprovider for an example of wxArtProvider usage.
+    @see @ref page_samples_artprov for an example of wxArtProvider usage;
+         @ref page_stockitems "stock ID list"

 */
 class wxArtProvider : public wxObject
 {
 */
 class wxArtProvider : public wxObject
 {


@@ -194,11 +214,29 @@ public:
                           const wxSize& size = wxDefaultSize);
 
     /**
                           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.
+        Returns native icon size for use specified by @a client hint.
+
+        If the platform has no commonly used default for this use or if
+        @a client is not recognized, returns wxDefaultSize.
+
+        @note In some cases, a platform may have @em several appropriate
+              native sizes (for example, wxART_FRAME_ICON for frame icons).
+              In that case, this method returns only one of them, picked
+              reasonably.
+
+        @since 2.9.0
+     */
+    static wxSize GetNativeSizeHint(const wxArtClient& client);
+
+    /**
+        Returns a suitable size hint for the given @e wxArtClient.
+
+        If @a platform_default is @true, return a size based on the current
+        platform using GetNativeSizeHint(), 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.
+
+        @see GetNativeSizeHint()

     */
     static wxSize GetSizeHint(const wxArtClient& client,
                               bool platform_default = false);
     */
     static wxSize GetSizeHint(const wxArtClient& client,
                               bool platform_default = false);


@@ -219,10 +257,21 @@ public:
                                       const wxArtClient& client = wxART_OTHER);
 
     /**
                                       const wxArtClient& client = wxART_OTHER);
 
     /**

-        Register new art provider and add it to the bottom of providers stack
-        (i.e. it will be queried as the last one).
+        Returns true if the platform uses native icons provider that should
+        take precedence over any customizations.

 
 

-        @see Push()
+        This is true for any platform that has user-customizable icon themes,
+        currently only wxGTK.
+
+        A typical use for this method is to decide whether a custom art provider
+        should be plugged in using Push() or PushBack().
+
+        @since 2.9.0
+     */
+    static bool HasNativeProvider();
+
+    /**
+        @deprecated Use PushBack() instead.

     */
     static void Insert(wxArtProvider* provider);
 
     */
     static void Insert(wxArtProvider* provider);
 


@@ -235,10 +284,21 @@ public:
         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()
+        @see PushBack()

     */
     static void Push(wxArtProvider* provider);
 
     */
     static void Push(wxArtProvider* provider);
 

+    /**
+        Register new art provider and add it to the bottom of providers stack.
+        In other words, it will be queried as the last one, after all others,
+        including the default provider.
+
+        @see Push()
+
+        @since 2.9.0
+    */
+    static void PushBack(wxArtProvider* provider);
+

     /**
         Remove a provider from the stack if it is on it. The provider is not
         deleted, unlike when using Delete().
     /**
         Remove a provider from the stack if it is on it. The provider is not
         deleted, unlike when using Delete().