interface/wx/iconbndl.h

   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