/* $Id: expander.hg,v 1.9 2006/04/12 11:11:25 murrayc Exp $ */

/* expander.h
 * 
 * Copyright (C) 2003 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <gtkmm/bin.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/bin_p.h)


namespace Gtk
{

/** A container which can hide its child.
 *
 * An Expander allows the user to hide or show its child by clicking on an
 * expander triangle similar to the triangles used in a Gtk::TreeView.
 *
 * Normally you use an expander as you would use any other descendant
 * of Gtk::Bin; you create the child widget and use add() to add it to 
 * the expander.  When the expander is toggled, it will take care of 
 * showing and hiding the child automatically.
 *
 * Special Usage: There are situations in which you may prefer to show and
 * hide the expanded widget yourself, such as when you want to
 * actually create the widget at expansion time.  In this case,
 * create an Expander but do not add a child to it.  The
 * expander widget has an <tt>expanded</tt> property
 * which can be used to monitor its expansion state.  You should
 * watch this property with a signal connection as follows:
 * @code
 * expander.property_expanded().signal_changed().connect(
 *   sigc::mem_fun(*this, &SomeClass::on_expander_changed)
 * );
 * @endcode
 *
 * @ingroup Widgets
 * @ingroup Containers
 */
class Expander : public Bin
{
  _CLASS_GTKOBJECT(Expander, GtkExpander, GTK_EXPANDER, Gtk::Bin, GtkBin)
public:

  /** Creates a new Expander.
   *
   * The Expander has an empty label.
   * 
   * @newin2p4
   */
  _CTOR_DEFAULT;

  /** Creates a new Expander with a label.
   *
   * Creates a new expander using label as the text of the label. Settin @a mnemonic to true
   * will allow you to precede characters in the label with an underscore which will make them
   * underlined. If you need a literal underscore character in a label, use '__' (two underscores).
   * The first underlined character represents a keyboard accelerator called a mnemonic.
   * Pressing Alt and that key activates the button.
   * 
   * @param label The string for the label describing the Expander.
   * @param mnemonic Wether the label may contain underscores to set up accelerators.
   
   * @newin2p4
   */
  explicit Expander(const Glib::ustring& label, bool mnemonic = false);
  _IGNORE(gtk_expander_new, gkt_expander_new_with_mnemonic)

  _WRAP_METHOD(void set_expanded(bool expanded = true), gtk_expander_set_expanded)
  _WRAP_METHOD(bool get_expanded() const, gtk_expander_get_expanded)

  _WRAP_METHOD(void set_spacing(int spacing), gtk_expander_set_spacing)
  _WRAP_METHOD(int get_spacing() const, gtk_expander_get_spacing)

  _WRAP_METHOD(void set_label(const Glib::ustring& label), gtk_expander_set_label)
  _WRAP_METHOD(Glib::ustring get_label() const, gtk_expander_get_label)

  _WRAP_METHOD(void set_use_underline(bool use_underline = true), gtk_expander_set_use_underline)
  _WRAP_METHOD(bool get_use_underline() const, gtk_expander_get_use_underline)

  _WRAP_METHOD(void set_use_markup(bool use_markup = true), gtk_expander_set_use_markup)
  _WRAP_METHOD(bool get_use_markup() const, gtk_expander_get_use_markup)

  _WRAP_METHOD(void set_label_widget(Widget& label_widget), gtk_expander_set_label_widget)
  _WRAP_METHOD(Widget* get_label_widget(), gtk_expander_get_label_widget)
  _WRAP_METHOD(const Widget* get_label_widget() const, gtk_expander_get_label_widget, constversion)

  _IGNORE_SIGNAL("activate") //keybinding

  _WRAP_PROPERTY("expanded", bool)
  _WRAP_PROPERTY("label", Glib::ustring)
  _WRAP_PROPERTY("use_underline", bool)
  _WRAP_PROPERTY("use_markup", bool)
  _WRAP_PROPERTY("spacing", int)
  _WRAP_PROPERTY("label_widget", Widget*)            
};


} // namespace Gtk