/*
 * 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/container.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/container_p.h)


namespace Gtk
{

//TODO: Add an add_pixbuf() method?
/** A container with just one child.
 *
 * This is an abstract base class from which all classes holding
 * up to 1 widget inside of them derive.  It provides access to methods
 * relevent to a single object, such as add_label, etc.
 *
 * @ingroup Widgets
 */
class GTKMM_API Bin : public Container
{
  _CLASS_GTKOBJECT(Bin,GtkBin,GTK_BIN,Gtk::Container,GtkContainer,,,GTKMM_API)
protected:

  /** This constructor is protected because only derived
   * classes should be instantiated.
   */
  _CTOR_DEFAULT
public:

  _WRAP_METHOD(Gtk::Widget* get_child(), gtk_bin_get_child)
  _WRAP_METHOD(const Gtk::Widget* get_child() const, gtk_bin_get_child)

  /** Remove the contained widget.
   * Since this can only hold one widget it is not necessary to
   * specify which widget to remove like other containers.
   *
   * Sometimes when a widget is added to a Gtk::ScrolledWindow, a Gtk::Viewport
   * is created and inserted between the ScrolledWindow and the added widget.
   * If the child is such an automatically created Viewport, remove() removes
   * the Viewport's child from the Viewport, and removes the Viewport from the
   * ScrolledWindow. The Viewport is destroyed.
   */
  void remove();

  //Convenience methods that don't correspond to GTK+ functions:

_DEPRECATE_IFDEF_START
  /** Add a Label object.
   * This does not correspond to any GTK+ function and is provided purely for
   * convenience.
   * @param label The text for the label.
   * @param mnemonic If <tt>true</tt>, characters preceded by an underscore
   * (_) will be underlined and used as a keyboard accelerator (shortcut).
   * @param x_align The horizontal alignment of the text.  This ranges from
   * 0.0 (left aligned) to 1.0 (right aligned).
   * @param y_align The vertical alignment of the text.  This ranges from
   * 0.0 (top aligned) to 1.0 (bottom aligned).
   *
   * @deprecated Use the other add_label().
   */
  void add_label(const Glib::ustring& label, bool mnemonic = false,
		 double x_align = 0.5, double y_align = 0.5);
_DEPRECATE_IFDEF_END

  /** Add a Label object.
   * This does not correspond to any GTK+ function and is provided purely for
   * convenience.
   * @param label The label text.
   * @param mnemonic If <tt>true</tt>, characters preceded by an underscore
   * (_) will be underlined and used as a keyboard accelerator (shortcut).
   * @param x_align The horizontal alignment of the text.  For possible
   * values, see Gtk::Align.
   * @param y_align The vertical alignment of the text.  For possible
   * values, see Gtk::Align.
   */
_DEPRECATE_IFDEF_START
  void add_label(const Glib::ustring& label, bool mnemonic,
    Align x_align, Align y_align = ALIGN_CENTER);
#else
  void add_label(const Glib::ustring& label, bool mnemonic = false,
    Align x_align = ALIGN_CENTER, Align y_align = ALIGN_CENTER);
_DEPRECATE_IFDEF_END

  //TODO: Change this to Pixbuf?
  /* Add Image and Label objects.
   * This does not correspond to any GTK+ function and is provided purely for
   * convenience.
   * This will create, manage, add, and show a new Image and Label (within a
   * horizontal Box) to this Bin.
   * @param pixmap A Glib::RefPtr to a Gdk::Pixmap.
   * @param mask A Glib::RefPtr to a Gdk::Bitmap.
   * @param label The text for the label.
   * @param x_align The horizontal alignment of the text in the label.
   * @param y_align The vertical alignment of the text in the label.
   */
  /*
  void add_pixlabel(const Glib::RefPtr<Gdk::Pixmap>& pixmap,
                    const Glib::RefPtr<Gdk::Bitmap>& mask,
                    const Glib::ustring& label,
                    Align x_align = ALIGN_CENTER, Align y_align = ALIGN_CENTER);
  */

_DEPRECATE_IFDEF_START
  /** Add Image and Label objects.
   * This does not correspond to any GTK+ function and is provided purely for
   * convenience.
   * This will create, manage, add, and show a new Image and Label (within a
   * horizontal Box) to this Bin.
   * @param pixfile The path to a file to be displayed.
   * @param label The text for the label.
   * @param x_align The horizontal alignment of the text in the label.
   * @param y_align The vertical alignment of the text in the label.
   *
   * @deprecated Use the other add_pixlabel().
   */
  void add_pixlabel(const std::string& pixfile,
                    const Glib::ustring& label,
		                double x_align = 0.5, double y_align = 0.5);
_DEPRECATE_IFDEF_END

  /** Add Image and Label objects.
   * This does not correspond to any GTK+ function and is provided purely for
   * convenience.
   * This will create, manage, add, and show a new Image and Label (within a
   * horizontal Box) to this Bin.
   * @param pixfile The path to a file to be displayed.
   * @param label The text for the label.
   * @param x_align The horizontal alignment of the text in the label.
   * @param y_align The vertical alignment of the text in the label.
   *
   * @newin{3,14}
   */
_DEPRECATE_IFDEF_START
  void add_pixlabel(const std::string& pixfile,
                    const Glib::ustring& label,
                    Align x_align, Align y_align = ALIGN_CENTER);
#else
  void add_pixlabel(const std::string& pixfile,
                    const Glib::ustring& label,
                    Align x_align = ALIGN_CENTER, Align y_align = ALIGN_CENTER);
_DEPRECATE_IFDEF_END
};

}  //namespace Gtk
