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

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


namespace Gtk
{

/** Abstract base clase for Gtk::HScale and Gtk::VScale.
 * 
 * A Gtk::Scale is a slider control used to select a numeric value. To use it,
 * you'll probably want to investigate the methods on its base class,
 * Gtk::Range, in addition to the methods for Gtk::Scale itself. To set the
 * value of a scale, you would normally use set_value(). To detect
 * changes to the value, you would normally use signal_value_changed().
 *
 * The Gtk::Scale widget is an abstract class, used only for deriving the
 * subclasses Gtk::HScale and Gtk::VScale, so you should instantiate them
 * instead.
 *
 * @ingroup Widgets
 */
class Scale : public Range
{
  _CLASS_GTKOBJECT(Scale,GtkScale,GTK_SCALE,Gtk::Range,GtkRange)
protected:
  _CTOR_DEFAULT
public:
  
  /** Set the number of decimal digits.
   * 
   * This also causes the adjustment to be rounded off so the retrieved value
   * matches the value the user sees. Setting digits to 1 gives for example
   * 1.0, 2 gives 1.00, etc.
   */
  _WRAP_METHOD(void set_digits(int digits), gtk_scale_set_digits)

  /** Get the number of decimal digits.
   */
  _WRAP_METHOD(int get_digits() const, gtk_scale_get_digits)

  /** Set whether the current value is displayed as a string next to the slider. 
   */
  _WRAP_METHOD(void set_draw_value(bool draw_value = true), gtk_scale_set_draw_value)

  /** Get whether the current value is displayed as a string next to the slider. 
   */
  _WRAP_METHOD(bool get_draw_value() const, gtk_scale_get_draw_value)


  /** Set the position in which the value is displayed.
   */
  _WRAP_METHOD(void set_value_pos(PositionType pos), gtk_scale_set_value_pos)

  /** Get the position in which the value is displayed.
   */
  _WRAP_METHOD(PositionType get_value_pos() const, gtk_scale_get_value_pos)

  _WRAP_METHOD(Glib::RefPtr<Pango::Layout> get_layout(), gtk_scale_get_layout, refreturn)
  _WRAP_METHOD(Glib::RefPtr<const Pango::Layout> get_layout() const, gtk_scale_get_layout, refreturn, constversion)
  _WRAP_METHOD(void get_layout_offsets(int& x, int& y) const, gtk_scale_get_layout_offsets)
  
#m4 dnl// The ::format_value signal handler should return a newly allocated string.
#m4 dnl// (which is obviously not a const gchar*)
#m4 dnl// Also, ensure that format_value never returns an empty char[],
#m4 dnl// because that could be caused by an intermediate empty ustring from an initial null char*,
#m4 dnl//See bug http://bugzilla.gnome.org/show_bug.cgi?id=168747.
#m4 _CONVERSION(`Glib::ustring',`gchar*',`(strlen($3.c_str()) ? g_strdup($3.c_str()) : 0)')

  /** Determines how the value is formatted.
   * 
   * This can be used to connect a custom function for determining how the
   * value is formatted. The function (or function object) is given a the value
   * as a double and should return the representation of it as a Glib::ustring.
   */ 
  _WRAP_SIGNAL(Glib::ustring format_value(double value), "format_value")
  // TODO: When we can break ABI, this signal needs to be
  // Glib::ustring format_value(double value, bool& use_default_formatting), 
  // where use_default_formatting specifies whether the return value will actually be a null char*.

  /** Number of displayed decimal digits.
   */
  _WRAP_PROPERTY("digits", int)

  /** Whether to draw the value as a string next to slider.
   */
  _WRAP_PROPERTY("draw-value", bool)

  /** The position in which the value is displayed.
   */
  _WRAP_PROPERTY("value-pos", PositionType)

protected:

  _WRAP_VFUNC(void draw_value(), draw_value)
  
  virtual int calc_digits_(double step) const;
};

/** A vertical slider for selecting values.
 * 
 * The Gtk::VScale widget is used to allow the user to select a value using a
 * vertical slider. See the Gtk::Scale documentation for more information
 * on how to use a Gtk::VScale.
 *
 * @ingroup Widgets
 */
class VScale : public Scale
{
  _CLASS_GTKOBJECT(VScale,GtkVScale,GTK_VSCALE,Gtk::Scale,GtkScale)
public:
  VScale();

  /**
  * Construct a VScale with the given minimum and maximum. The step size is the
  * distance the slider moves when the arrow keys are used to adjust the scale
  * value.
  */
  VScale(double min, double max, double step);
  explicit VScale(Adjustment& adjustment);
  
};

/** A horizontal slider for selecting values.
 *
 * The Gtk::HScale widget is used to allow the user to select a value using a
 * horizontal slider. See the Gtk::Scale documentation for more information
 * on how to use a Gtk::HScale.
 * 
 * @ingroup Widgets
 */
class HScale : public Scale
{
  _CLASS_GTKOBJECT(HScale,GtkHScale,GTK_HSCALE,Gtk::Scale,GtkScale)
public:
  HScale();
  /**
  * Construct a HScale with the given minimum and maximum. The step size is the
  * distance the slider moves when the arrow keys are used to adjust the scale
  * value.
  */
  HScale(double min, double max, double step);
  explicit HScale(Adjustment& adjustment);
  
};

} /* namespace Gtk */

