synchronize GTK2 minimum version in docs

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

diff --git a/interface/wx/iconbndl.h b/interface/wx/iconbndl.h
index aecfe287f5976907922ad7b42659d9fdeb1890bf..c33009d0effd7724010c84f16a381f771e0f6754 100644 (file)
--- a/interface/wx/iconbndl.h
+++ b/interface/wx/iconbndl.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxIconBundle
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxIconBundle
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -21,6 +21,28 @@
 class wxIconBundle : public wxGDIObject
 {
 public:
 class wxIconBundle : public wxGDIObject
 {
 public:

+    /**
+        The elements of this enum determine what happens if GetIcon() doesn't
+        find the icon of exactly the requested size.
+
+        @since 2.9.4
+     */
+    enum
+    {
+        /// Return invalid icon if exact size is not found.
+        FALLBACK_NONE = 0,
+
+        /// Return the icon of the system icon size if exact size is not found.
+        /// May be combined with other non-NONE enum elements to determine what
+        /// happens if the system icon size is not found neither.
+        FALLBACK_SYSTEM = 1,
+
+        /// Return the icon of closest larger size or, if there is no icon of
+        /// larger size in the bundle, the closest icon of smaller size.
+        FALLBACK_NEAREST_LARGER = 2
+    };
+
+

     /**
         Default ctor.
     */
     /**
         Default ctor.
     */


@@ -34,6 +56,10 @@ public:
     /**
         Initializes the bundle with the icon(s) found in the stream.
 
     /**
         Initializes the bundle with the icon(s) found in the stream.
 

+        Notice that the @a stream must be seekable, at least if it contains
+        more than one icon. The stream pointer is positioned after the last
+        icon read from the stream when this function returns.
+

         @since 2.9.0
     */
     wxIconBundle(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY);
         @since 2.9.0
     */
     wxIconBundle(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY);


@@ -65,6 +91,10 @@ public:
         collection already contains icons with the same width and height, they
         are replaced by the new ones.
 
         collection already contains icons with the same width and height, they
         are replaced by the new ones.
 

+        Notice that, as well as in the constructor loading the icon bundle from
+        stream, the @a stream must be seekable, at least if more than one icon
+        is to be loaded from it.
+

         @since 2.9.0
     */
     void AddIcon(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY);
         @since 2.9.0
     */
     void AddIcon(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY);


@@ -77,19 +107,31 @@ public:
     void AddIcon(const wxIcon& icon);
 
     /**
     void AddIcon(const wxIcon& icon);
 
     /**

-        Returns the icon with the given size; if no such icon exists, returns
-        the icon with size @c wxSYS_ICON_X and @c wxSYS_ICON_Y; if no such icon
-        exists, returns the first icon in the bundle.
+        Returns the icon with the given size.
+
+        If @a size is ::wxDefaultSize, it is interpreted as the standard system
+        icon size, i.e. the size returned by wxSystemSettings::GetMetric() for
+        @c wxSYS_ICON_X and @c wxSYS_ICON_Y.

 
 

-        If size = wxDefaultSize, returns the icon with size @c wxSYS_ICON_X and
-        @c wxSYS_ICON_Y.
+        If the bundle contains an icon with exactly the requested size, it's
+        always returned. Otherwise, the behaviour depends on the flags. If only
+        ::FALLBACK_NONE is given, the function returns an invalid icon. If
+        ::FALLBACK_SYSTEM is given, it tries to find the icon of standard
+        system size, regardless of the size passed as parameter. Otherwise, or
+        if the icon system size is not found neither, but
+        ::FALLBACK_NEAREST_LARGER flag is specified, the function returns the
+        smallest icon of the size larger than the requested one or, if this
+        fails too, just the icon closest to the specified size.
+
+        The @a flags parameter is available only since wxWidgets 2.9.4.

     */
     */

-    wxIcon GetIcon(const wxSize& size) const;
+    wxIcon GetIcon(const wxSize& size, int flags = FALLBACK_SYSTEM) const;

 
     /**
         Same as @code GetIcon( wxSize( size, size ) ) @endcode.
     */
 
     /**
         Same as @code GetIcon( wxSize( size, size ) ) @endcode.
     */

-    wxIcon GetIcon(wxCoord size = wxDefaultCoord) const;
+    wxIcon GetIcon(wxCoord size = wxDefaultCoord,
+                   int flags = FALLBACK_SYSTEM) const;

 
     /**
         Returns the icon with exactly the given size or ::wxNullIcon if this
 
     /**
         Returns the icon with exactly the given size or ::wxNullIcon if this


@@ -97,6 +139,16 @@ public:
     */
     wxIcon GetIconOfExactSize(const wxSize& size) const;
 
     */
     wxIcon GetIconOfExactSize(const wxSize& size) const;
 

+    /**
+       return the number of available icons
+    */
+    size_t GetIconCount() const;
+
+    /**
+       return the icon at index (must be < GetIconCount())
+    */
+    wxIcon GetIconByIndex(size_t n) const;
+

     /**
         Returns @true if the bundle doesn't contain any icons, @false otherwise
         (in which case a call to GetIcon() with default parameter should return
     /**
         Returns @true if the bundle doesn't contain any icons, @false otherwise
         (in which case a call to GetIcon() with default parameter should return


@@ -109,15 +161,6 @@ public:
     */
     wxIconBundle& operator=(const wxIconBundle& ic);
 
     */
     wxIconBundle& operator=(const wxIconBundle& ic);
 

-    /**
-        Equality operator. This returns @true if two icon bundles are equal.
-    */
-    bool operator ==(const wxIconBundle& ic);
-
-    /**
-        Inequality operator. This returns true if two icon bundles are not equal.
-    */
-    bool operator !=(const wxIconBundle& ic);

 };
 
 
 };