libs/gtkmm2/gtk/src/scale.hg

   1 /* $Id: scale.hg,v 1.7 2006/04/12 11:11:25 murrayc Exp $ */
   2
   3 /* scale.h
   4  *
   5  * Copyright (C) 1998-2002 The gtkmm Development Team
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the Free
  19  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20  */
  21
  22 #include <gtkmm/range.h>
  23 _DEFS(gtkmm,gtk)
  24 _DEFS(gtkmm,gtk)
  25 _DEFS(gtkmm,gtk)
  26 _PINCLUDE(gtkmm/private/range_p.h)
  27
  28
  29 namespace Gtk
  30 {
  31
  32 /** Abstract base clase for Gtk::HScale and Gtk::VScale.
  33  *
  34  * A Gtk::Scale is a slider control used to select a numeric value. To use it,
  35  * you'll probably want to investigate the methods on its base class,
  36  * Gtk::Range, in addition to the methods for Gtk::Scale itself. To set the
  37  * value of a scale, you would normally use set_value(). To detect
  38  * changes to the value, you would normally use signal_value_changed().
  39  *
  40  * The Gtk::Scale widget is an abstract class, used only for deriving the
  41  * subclasses Gtk::HScale and Gtk::VScale, so you should instantiate them
  42  * instead.
  43  *
  44  * @ingroup Widgets
  45  */
  46 class Scale : public Range
  47 {
  48   _CLASS_GTKOBJECT(Scale,GtkScale,GTK_SCALE,Gtk::Range,GtkRange)
  49 protected:
  50   _CTOR_DEFAULT
  51 public:
  52
  53   /** Set the number of decimal digits.
  54    *
  55    * This also causes the adjustment to be rounded off so the retrieved value
  56    * matches the value the user sees. Setting digits to 1 gives for example
  57    * 1.0, 2 gives 1.00, etc.
  58    */
  59   _WRAP_METHOD(void set_digits(int digits), gtk_scale_set_digits)
  60
  61   /** Get the number of decimal digits.
  62    */
  63   _WRAP_METHOD(int get_digits() const, gtk_scale_get_digits)
  64
  65   /** Set whether the current value is displayed as a string next to the slider.
  66    */
  67   _WRAP_METHOD(void set_draw_value(bool draw_value = true), gtk_scale_set_draw_value)
  68
  69   /** Get whether the current value is displayed as a string next to the slider.
  70    */
  71   _WRAP_METHOD(bool get_draw_value() const, gtk_scale_get_draw_value)
  72
  73
  74   /** Set the position in which the value is displayed.
  75    */
  76   _WRAP_METHOD(void set_value_pos(PositionType pos), gtk_scale_set_value_pos)
  77
  78   /** Get the position in which the value is displayed.
  79    */
  80   _WRAP_METHOD(PositionType get_value_pos() const, gtk_scale_get_value_pos)
  81
  82   _WRAP_METHOD(Glib::RefPtr<Pango::Layout> get_layout(), gtk_scale_get_layout, refreturn)
  83   _WRAP_METHOD(Glib::RefPtr<const Pango::Layout> get_layout() const, gtk_scale_get_layout, refreturn, constversion)
  84   _WRAP_METHOD(void get_layout_offsets(int& x, int& y) const, gtk_scale_get_layout_offsets)
  85
  86 #m4 dnl// The ::format_value signal handler should return a newly allocated string.
  87 #m4 dnl// (which is obviously not a const gchar*)
  88 #m4 dnl// Also, ensure that format_value never returns an empty char[],
  89 #m4 dnl// because that could be caused by an intermediate empty ustring from an initial null char*,
  90 #m4 dnl//See bug http://bugzilla.gnome.org/show_bug.cgi?id=168747.
  91 #m4 _CONVERSION(`Glib::ustring',`gchar*',`(strlen($3.c_str()) ? g_strdup($3.c_str()) : 0)')
  92
  93   /** Determines how the value is formatted.
  94    *
  95    * This can be used to connect a custom function for determining how the
  96    * value is formatted. The function (or function object) is given a the value
  97    * as a double and should return the representation of it as a Glib::ustring.
  98    */
  99   _WRAP_SIGNAL(Glib::ustring format_value(double value), "format_value")
 100   // TODO: When we can break ABI, this signal needs to be
 101   // Glib::ustring format_value(double value, bool& use_default_formatting),
 102   // where use_default_formatting specifies whether the return value will actually be a null char*.
 103
 104   /** Number of displayed decimal digits.
 105    */
 106   _WRAP_PROPERTY("digits", int)
 107
 108   /** Whether to draw the value as a string next to slider.
 109    */
 110   _WRAP_PROPERTY("draw-value", bool)
 111
 112   /** The position in which the value is displayed.
 113    */
 114   _WRAP_PROPERTY("value-pos", PositionType)
 115
 116 protected:
 117
 118   _WRAP_VFUNC(void draw_value(), draw_value)
 119
 120   virtual int calc_digits_(double step) const;
 121 };
 122
 123 /** A vertical slider for selecting values.
 124  *
 125  * The Gtk::VScale widget is used to allow the user to select a value using a
 126  * vertical slider. See the Gtk::Scale documentation for more information
 127  * on how to use a Gtk::VScale.
 128  *
 129  * @ingroup Widgets
 130  */
 131 class VScale : public Scale
 132 {
 133   _CLASS_GTKOBJECT(VScale,GtkVScale,GTK_VSCALE,Gtk::Scale,GtkScale)
 134 public:
 135   VScale();
 136
 137   /**
 138   * Construct a VScale with the given minimum and maximum. The step size is the
 139   * distance the slider moves when the arrow keys are used to adjust the scale
 140   * value.
 141   */
 142   VScale(double min, double max, double step);
 143   explicit VScale(Adjustment& adjustment);
 144
 145 };
 146
 147 /** A horizontal slider for selecting values.
 148  *
 149  * The Gtk::HScale widget is used to allow the user to select a value using a
 150  * horizontal slider. See the Gtk::Scale documentation for more information
 151  * on how to use a Gtk::HScale.
 152  *
 153  * @ingroup Widgets
 154  */
 155 class HScale : public Scale
 156 {
 157   _CLASS_GTKOBJECT(HScale,GtkHScale,GTK_HSCALE,Gtk::Scale,GtkScale)
 158 public:
 159   HScale();
 160   /**
 161   * Construct a HScale with the given minimum and maximum. The step size is the
 162   * distance the slider moves when the arrow keys are used to adjust the scale
 163   * value.
 164   */
 165   HScale(double min, double max, double step);
 166   explicit HScale(Adjustment& adjustment);
 167
 168 };
 169
 170 } /* namespace Gtk */
 171