// -*- c++ -*-
// Generated by gtkmmproc -- DO NOT MODIFY!
#ifndef _GTKMM_ICONSET_H
#define _GTKMM_ICONSET_H


#include <glibmm/ustring.h>
#include <sigc++/sigc++.h>

/* $Id: iconset.hg,v 1.3 2006/07/30 20:49:50 murrayc Exp $ */

/* iconset.h
 *
 * Copyright(C) 1998-2002 The gtkmm Development Team
 *
 * This library is free software, ) you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation, ) either
 * version 2.1 of the License, or(at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY, ) without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library, ) if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#include <gtkmm/stylecontext.h>
#include <gdkmm/pixbuf.h>
#include <gtkmm/iconsource.h>
//#include <gtkmm/widget.h>
#include <gtkmm/stockid.h>


namespace Gtk
{

class StyleContext;
class Widget;


/** This manages a set of variants of a particular icon 
 * An IconSet contains variants for different sizes and widget states. 
 * Icons in an icon factory are named by a stock ID, which is a simple string identifying the icon. Each GtkStyle has a list of GtkIconFactory derived from the current theme; those icon factories are consulted first when searching for an icon. If the theme doesn't set a particular icon, GTK+ looks for the icon in a list of default icon factories, maintained by gtk_icon_factory_add_default() and gtk_icon_factory_remove_default(). Applications with icons should add a default icon factory with their icons, which will allow themes to override the icons for the application. 
 */
class IconSet
{
  //GtkIconSet is registered as a boxed type, but it has ref/unref functions instead of copy/free,
  //so we use it via RefPtr.
  public:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
  typedef IconSet CppObjectType;
  typedef GtkIconSet BaseObjectType;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */

  static Glib::RefPtr<IconSet> create();

  /** Increment the reference count for this object.
   * You should never need to do this manually - use the object via a RefPtr instead.
   */
  void reference()   const;

  /** Decrement the reference count for this object.
   * You should never need to do this manually - use the object via a RefPtr instead.
   */
  void unreference() const;

  ///Provides access to the underlying C instance.
  GtkIconSet*       gobj();

  ///Provides access to the underlying C instance.
  const GtkIconSet* gobj() const;

  ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
  GtkIconSet* gobj_copy() const;

protected:
  // Do not derive this.  Gtk::IconSet can neither be constructed nor deleted.
  IconSet();
  void operator delete(void*, size_t);

private:
  // noncopyable
  IconSet(const IconSet&);
  IconSet& operator=(const IconSet&);


public:
  //TODO: Documentation
  static Glib::RefPtr<IconSet> create(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);

  
  /** Copies @a icon_set by value.
   * @return A new Gtk::IconSet identical to the first.
   */
  Glib::RefPtr<IconSet> copy() const;

  
  /** Renders an icon using gtk_render_icon_pixbuf(). In most cases,
   * Gtk::Widget::render_icon_pixbuf() is better, since it automatically provides
   * most of the arguments from the current widget settings.  This
   * function never returns <tt>0</tt>; if the icon can't be rendered
   * (perhaps because an image file fails to load), a default "missing
   * image" icon will be returned instead.
   * 
   * @newin{3,0}
   * @param context A Gtk::StyleContext.
   * @param size Icon size. A size of (GtkIconSize)-1
   * means render at the size of the source and don't scale.
   * @return A Gdk::Pixbuf to be displayed.
   */
  Glib::RefPtr<Gdk::Pixbuf> render_icon_pixbuf(const Glib::RefPtr<StyleContext>& context, IconSize size);
   //deprecated.
  
  
  /** Icon sets have a list of Gtk::IconSource, which they use as base
   * icons for rendering icons in different states and sizes. Icons are
   * scaled, made to look insensitive, etc. in
   * render_icon(), but Gtk::IconSet needs base images to
   * work with. The base images and when to use them are described by
   * a Gtk::IconSource.
   * 
   * This function copies @a source, so you can reuse the same source immediately
   * without affecting the icon set.
   * 
   * An example of when you'd use this function: a web browser's "Back
   * to Previous Page" icon might point in a different direction in
   * Hebrew and in English; it might look different when insensitive;
   * and it might change size depending on toolbar mode (small/large
   * icons). So a single icon set would contain all those variants of
   * the icon, and you might add a separate source for each one.
   * 
   * You should nearly always add a "default" icon source with all
   * fields wildcarded, which will be used as a fallback if no more
   * specific source matches. Gtk::IconSet always prefers more specific
   * icon sources to more generic icon sources. The order in which you
   * add the sources to the icon set does not matter.
   * 
   * new_from_pixbuf() creates a new icon set with a
   * default icon source based on the given pixbuf.
   * @param source A Gtk::IconSource.
   */
  void add_source(const IconSource& source);

  std::vector<IconSize> get_sizes() const;

  
  /** Looks for an icon in the list of default icon factories.  For
   * display to the user, you should use Gtk::Style::lookup_icon_set() on
   * the Gtk::Style for the widget that will display the icon, instead of
   * using this function directly, so that themes are taken into
   * account.
   * @param stock_id An icon name.
   * @return A Gtk::IconSet, or <tt>0</tt>.
   */
  static Glib::RefPtr<IconSet> lookup_default(const Gtk::StockID& stock_id);


};

} /* namespace Gtk */


namespace Glib
{

  /** A Glib::wrap() method for this object.
   * 
   * @param object The C instance.
   * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
   * @result A C++ instance that wraps this C instance.
   *
   * @relates Gtk::IconSet
   */
  Glib::RefPtr<Gtk::IconSet> wrap(GtkIconSet* object, bool take_copy = false);

} // namespace Glib


#endif /* _GTKMM_ICONSET_H */

