| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: iconbndl.h |
| 3 | // Purpose: interface of wxIconBundle |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | @class wxIconBundle |
| 11 | |
| 12 | This class contains multiple copies of an icon in different sizes. |
| 13 | It is typically used in wxDialog::SetIcons and wxTopLevelWindow::SetIcons. |
| 14 | |
| 15 | @library{wxcore} |
| 16 | @category{gdi} |
| 17 | |
| 18 | @stdobjects |
| 19 | ::wxNullIconBundle |
| 20 | */ |
| 21 | class wxIconBundle : public wxGDIObject |
| 22 | { |
| 23 | public: |
| 24 | /** |
| 25 | The elements of this enum determine what happens if GetIcon() doesn't |
| 26 | find the icon of exactly the requested size. |
| 27 | |
| 28 | @since 2.9.4 |
| 29 | */ |
| 30 | enum |
| 31 | { |
| 32 | /// Return invalid icon if exact size is not found. |
| 33 | FALLBACK_NONE = 0, |
| 34 | |
| 35 | /// Return the icon of the system icon size if exact size is not found. |
| 36 | /// May be combined with other non-NONE enum elements to determine what |
| 37 | /// happens if the system icon size is not found neither. |
| 38 | FALLBACK_SYSTEM = 1, |
| 39 | |
| 40 | /// Return the icon of closest larger size or, if there is no icon of |
| 41 | /// larger size in the bundle, the closest icon of smaller size. |
| 42 | FALLBACK_NEAREST_LARGER = 2 |
| 43 | }; |
| 44 | |
| 45 | |
| 46 | /** |
| 47 | Default ctor. |
| 48 | */ |
| 49 | wxIconBundle(); |
| 50 | |
| 51 | /** |
| 52 | Initializes the bundle with the icon(s) found in the file. |
| 53 | */ |
| 54 | wxIconBundle(const wxString& file, wxBitmapType type = wxBITMAP_TYPE_ANY); |
| 55 | |
| 56 | /** |
| 57 | Initializes the bundle with the icon(s) found in the stream. |
| 58 | |
| 59 | Notice that the @a stream must be seekable, at least if it contains |
| 60 | more than one icon. The stream pointer is positioned after the last |
| 61 | icon read from the stream when this function returns. |
| 62 | |
| 63 | @since 2.9.0 |
| 64 | */ |
| 65 | wxIconBundle(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY); |
| 66 | |
| 67 | /** |
| 68 | Initializes the bundle with a single icon. |
| 69 | */ |
| 70 | wxIconBundle(const wxIcon& icon); |
| 71 | |
| 72 | /** |
| 73 | Copy constructor. |
| 74 | */ |
| 75 | wxIconBundle(const wxIconBundle& ic); |
| 76 | |
| 77 | /** |
| 78 | Destructor. |
| 79 | */ |
| 80 | virtual ~wxIconBundle(); |
| 81 | |
| 82 | /** |
| 83 | Adds all the icons contained in the file to the bundle; if the |
| 84 | collection already contains icons with the same width and height, they |
| 85 | are replaced by the new ones. |
| 86 | */ |
| 87 | void AddIcon(const wxString& file, wxBitmapType type = wxBITMAP_TYPE_ANY); |
| 88 | |
| 89 | /** |
| 90 | Adds all the icons contained in the stream to the bundle; if the |
| 91 | collection already contains icons with the same width and height, they |
| 92 | are replaced by the new ones. |
| 93 | |
| 94 | Notice that, as well as in the constructor loading the icon bundle from |
| 95 | stream, the @a stream must be seekable, at least if more than one icon |
| 96 | is to be loaded from it. |
| 97 | |
| 98 | @since 2.9.0 |
| 99 | */ |
| 100 | void AddIcon(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY); |
| 101 | |
| 102 | /** |
| 103 | Adds the icon to the collection; if the collection already |
| 104 | contains an icon with the same width and height, it is |
| 105 | replaced by the new one. |
| 106 | */ |
| 107 | void AddIcon(const wxIcon& icon); |
| 108 | |
| 109 | /** |
| 110 | Returns the icon with the given size. |
| 111 | |
| 112 | If @a size is ::wxDefaultSize, it is interpreted as the standard system |
| 113 | icon size, i.e. the size returned by wxSystemSettings::GetMetric() for |
| 114 | @c wxSYS_ICON_X and @c wxSYS_ICON_Y. |
| 115 | |
| 116 | If the bundle contains an icon with exactly the requested size, it's |
| 117 | always returned. Otherwise, the behaviour depends on the flags. If only |
| 118 | ::FALLBACK_NONE is given, the function returns an invalid icon. If |
| 119 | ::FALLBACK_SYSTEM is given, it tries to find the icon of standard |
| 120 | system size, regardless of the size passed as parameter. Otherwise, or |
| 121 | if the icon system size is not found neither, but |
| 122 | ::FALLBACK_NEAREST_LARGER flag is specified, the function returns the |
| 123 | smallest icon of the size larger than the requested one or, if this |
| 124 | fails too, just the icon closest to the specified size. |
| 125 | |
| 126 | The @a flags parameter is available only since wxWidgets 2.9.4. |
| 127 | */ |
| 128 | wxIcon GetIcon(const wxSize& size, int flags = FALLBACK_SYSTEM) const; |
| 129 | |
| 130 | /** |
| 131 | Same as @code GetIcon( wxSize( size, size ) ) @endcode. |
| 132 | */ |
| 133 | wxIcon GetIcon(wxCoord size = wxDefaultCoord, |
| 134 | int flags = FALLBACK_SYSTEM) const; |
| 135 | |
| 136 | /** |
| 137 | Returns the icon with exactly the given size or ::wxNullIcon if this |
| 138 | size is not available. |
| 139 | */ |
| 140 | wxIcon GetIconOfExactSize(const wxSize& size) const; |
| 141 | |
| 142 | /** |
| 143 | return the number of available icons |
| 144 | */ |
| 145 | size_t GetIconCount() const; |
| 146 | |
| 147 | /** |
| 148 | return the icon at index (must be < GetIconCount()) |
| 149 | */ |
| 150 | wxIcon GetIconByIndex(size_t n) const; |
| 151 | |
| 152 | /** |
| 153 | Returns @true if the bundle doesn't contain any icons, @false otherwise |
| 154 | (in which case a call to GetIcon() with default parameter should return |
| 155 | a valid icon). |
| 156 | */ |
| 157 | bool IsEmpty() const; |
| 158 | |
| 159 | /** |
| 160 | Assignment operator, using @ref overview_refcount "reference counting". |
| 161 | */ |
| 162 | wxIconBundle& operator=(const wxIconBundle& ic); |
| 163 | |
| 164 | }; |
| 165 | |
| 166 | |
| 167 | /** |
| 168 | An empty wxIconBundle. |
| 169 | */ |
| 170 | wxIconBundle wxNullIconBundle; |
| 171 | |
| 172 | |