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