interface/wx/iconbndl.h

   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         Copy constructor.
  73     */
  74     wxIconBundle(const wxIconBundle& ic);
  75
  76     /**
  77         Destructor.
  78     */
  79     virtual ~wxIconBundle();
  80
  81     /**
  82         Adds all the icons contained in the file to the bundle; if the
  83         collection already contains icons with the same width and height, they
  84         are replaced by the new ones.
  85     */
  86     void AddIcon(const wxString& file, wxBitmapType type = wxBITMAP_TYPE_ANY);
  87
  88     /**
  89         Adds all the icons contained in the stream to the bundle; if the
  90         collection already contains icons with the same width and height, they
  91         are replaced by the new ones.
  92
  93         Notice that, as well as in the constructor loading the icon bundle from
  94         stream, the @a stream must be seekable, at least if more than one icon
  95         is to be loaded from it.
  96
  97         @since 2.9.0
  98     */
  99     void AddIcon(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY);
 100
 101     /**
 102         Adds the icon to the collection; if the collection already
 103         contains an icon with the same width and height, it is
 104         replaced by the new one.
 105     */
 106     void AddIcon(const wxIcon& icon);
 107
 108     /**
 109         Returns the icon with the given size.
 110
 111         If @a size is ::wxDefaultSize, it is interpreted as the standard system
 112         icon size, i.e. the size returned by wxSystemSettings::GetMetric() for
 113         @c wxSYS_ICON_X and @c wxSYS_ICON_Y.
 114
 115         If the bundle contains an icon with exactly the requested size, it's
 116         always returned. Otherwise, the behaviour depends on the flags. If only
 117         ::FALLBACK_NONE is given, the function returns an invalid icon. If
 118         ::FALLBACK_SYSTEM is given, it tries to find the icon of standard
 119         system size, regardless of the size passed as parameter. Otherwise, or
 120         if the icon system size is not found neither, but
 121         ::FALLBACK_NEAREST_LARGER flag is specified, the function returns the
 122         smallest icon of the size larger than the requested one or, if this
 123         fails too, just the icon closest to the specified size.
 124
 125         The @a flags parameter is available only since wxWidgets 2.9.4.
 126     */
 127     wxIcon GetIcon(const wxSize& size, int flags = FALLBACK_SYSTEM) const;
 128
 129     /**
 130         Same as @code GetIcon( wxSize( size, size ) ) @endcode.
 131     */
 132     wxIcon GetIcon(wxCoord size = wxDefaultCoord,
 133                    int flags = FALLBACK_SYSTEM) const;
 134
 135     /**
 136         Returns the icon with exactly the given size or ::wxNullIcon if this
 137         size is not available.
 138     */
 139     wxIcon GetIconOfExactSize(const wxSize& size) const;
 140
 141     /**
 142        return the number of available icons
 143     */
 144     size_t GetIconCount() const;
 145
 146     /**
 147        return the icon at index (must be < GetIconCount())
 148     */
 149     wxIcon GetIconByIndex(size_t n) const;
 150
 151     /**
 152         Returns @true if the bundle doesn't contain any icons, @false otherwise
 153         (in which case a call to GetIcon() with default parameter should return
 154         a valid icon).
 155     */
 156     bool IsEmpty() const;
 157
 158     /**
 159         Assignment operator, using @ref overview_refcount "reference counting".
 160     */
 161     wxIconBundle& operator=(const wxIconBundle& ic);
 162
 163 };
 164
 165
 166 /**
 167     An empty wxIconBundle.
 168 */
 169 wxIconBundle wxNullIconBundle;
 170
 171