path: root/docs/reference/pygtk-gtkscale.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkscale">
  <refnamediv>
    <refname>gtk.Scale</refname>
    <refpurpose>a base class for the scale widgets.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Scale</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkrange">gtk.Range</link></classname></ooclass>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--set-digits">set_digits</link></methodname>
	<methodparam><parameter
		       role="keyword">digits</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--get-digits">get_digits</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--set-draw-value">set_draw_value</link></methodname>
	<methodparam><parameter
		       role="keyword">draw_value</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--get-draw-value">get_draw_value</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--set-value-pos">set_value_pos</link></methodname>
	<methodparam><parameter role="keyword">pos</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--get-value-pos">get_value_pos</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--get-layout">get_layout</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkscale--get-layout-offsets">get_layout_offsets</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>

      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkscale--add-mark">add_mark</link></methodname>
        <methodparam><parameter role="keyword">value</parameter></methodparam>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">markup</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkscale--clear-marks">clear_marks</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkrange">gtk.Range</link>
        +-- <link linkend="class-gtkscale">gtk.Scale</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkscale"><classname>gtk.Scale</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkscale">
    <title>gtk.Scale Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkrange">gtk.Range Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"digits"</entry>
	      <entry>Read-Write</entry>
	      <entry>The number of decimal places that are displayed in the
value</entry>
	    </row>

	    <row valign="top">
	      <entry>"draw-value"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal> the current value is
displayed as a string next to the slider</entry>
	    </row>

	    <row valign="top">
	      <entry>"value-pos"</entry>
	      <entry>Read-Write</entry>
	      <entry>The position in which the current value is displayed:
<literal>gtk.POS_LEFT</literal>, <literal>gtk.POS_RIGHT</literal>,
<literal>gtk.POS_TOP</literal> or <literal>gtk.POS_BOTTOM</literal></entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkscale">
    <title>gtk.Scale Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
    <para><link linkend="style-properties-gtkrange">gtk.Range Style Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"slider-length"</entry>
	      <entry>Read</entry>
	      <entry>The length of scale's slider</entry>
	    </row>

	    <row valign="top">
	      <entry>"value-spacing"</entry>
	      <entry>Read</entry>
	      <entry>The space between value text and the slider or trough
	      area</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkscale">
    <title>gtk.Scale Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkrange">gtk.Range Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkscale--format-value">format-value</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>scale</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkscale"><classname>gtk.Scale</classname></link> widget is
an abstract base class, used only for deriving the subclasses <link
linkend="class-gtkhscale"><classname>gtk.HScale</classname></link> and <link
linkend="class-gtkvscale"><classname>gtk.VScale</classname></link>. A <link
linkend="class-gtkscale"><classname>gtk.Scale</classname></link> is a slider
control used to select a numeric value. Since <link
linkend="class-gtkscale"><classname>gtk.Scale</classname></link> is a
subclass of <link
linkend="class-gtkrange"><classname>gtk.Range</classname></link>, see the
<link linkend="class-gtkrange"><classname>gtk.Range</classname></link>
methods for additional methods. To set the value of a scale, you would
normally use <link
linkend="method-gtkrange--set-value"><methodname>set_value</methodname>()</link>. 
To detect changes to the value, you would normally use the "value_changed"
signal.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkscale--set-digits">
      <title>gtk.Scale.set_digits</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_digits</methodname>
	  <methodparam><parameter
			 role="keyword">digits</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">digits</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of decimal places to
display</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_digits</methodname>() method sets the
"digits" property to the value specified by <parameter>digits</parameter>.
The value of <parameter>digits</parameter> specifies the number of decimal
places that are displayed in the value. The value of the adjustment is also
rounded off to this number of digits if "draw-value" is
<literal>True</literal>, so the retrieved value matches the value the user
sees. If the "draw-value" property has been set to <literal>False</literal>
by using the <link
linkend="method-gtkscale--set-draw-value"><methodname>set_draw_value</methodname>()</link>
method, the adjustment value will not be rounded at all.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--get-digits">
      <title>gtk.Scale.get_digits</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_digits</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the number of decimal places that are
displayed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_digits</methodname>() method returns the
value of the "digits" property that indicates the number of decimal places
that are displayed in the value.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--set-draw-value">
      <title>gtk.Scale.set_draw_value</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_draw_value</methodname>
	  <methodparam><parameter
			 role="keyword">draw_value</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">draw_value</parameter>&nbsp;:</term>
	  <listitem><simpara>If <literal>True</literal> draw the current
value next to the slider</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_draw_value</methodname>() method sets the
"draw-value" property to the value specified by
<parameter>draw_value</parameter>. If <parameter>draw_value</parameter> is
<parameter>True</parameter> the current value is displayed next to the
slider.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--get-draw-value">
      <title>gtk.Scale.get_draw_value</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_draw_value</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the current value is
to be drawn next to the slider</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_draw_value</methodname>() method returns the
value of the "draw-value" property. If "draw-value" is
<literal>True</literal> the current scale value is drawn next to the
slider.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--set-value-pos">
      <title>gtk.Scale.set_value_pos</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_value_pos</methodname>
	  <methodparam><parameter
			 role="keyword">pos</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pos</parameter>&nbsp;:</term>
	  <listitem><simpara>the position where the current value is
displayed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_value_pos</methodname>() method sets the
value of the "value-pos" property to the value specified by
<parameter>pos</parameter>. The value of <parameter>pos</parameter> must be
one of: <literal>gtk.POS_LEFT</literal>, <literal>gtk.POS_RIGHT</literal>,
<literal>gtk.POS_TOP</literal> or <literal>gtk.POS_BOTTOM</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--get-value-pos">
      <title>gtk.Scale.get_value_pos</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_value_pos</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the position where the current value is
displayed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_value_pos</methodname>() method returns the
value of the "value-pos" property. See the <link
linkend="method-gtkscale--set-value-pos"><methodname>set_value_pos</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--get-layout">
      <title>gtk.Scale.get_layout</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_layout</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
	  linkend="class-pangolayout"><classname>pango.Layout</classname></link>
	  for this scale or <literal>None</literal> if the draw_value
	  property is <literal>False</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>get_layout</methodname>() method returns the
<link linkend="class-pangolayout"><classname>pango.Layout</classname></link>
used to display the scale.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--get-layout-offsets">
      <title>gtk.Scale.get_layout_offsets</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_layout_offsets</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the coordinates where the
	  scale will draw the <link
	  linkend="class-pangolayout"><classname>pango.Layout</classname></link>
	  representing the text in the scale</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>get_layout_offsets</methodname>() method returns
a 2-tuple containing the coordinates where the scale will draw the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
representing the text in the scale. Remember when using the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link>
function you need to convert to and from pixels using the <link
linkend="function-pango--PIXELS"><function>pango.PIXELS</function>()</link>
function or <literal>pango.SCALE</literal>. If the "draw-value" property is
<literal>False</literal>, the return values are undefined.</para>

    </refsect2>

    <refsect2 id="method-gtkscale--add-mark">
      <title>gtk.Scale.add_mark</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_mark</methodname>
        <methodparam><parameter role="keyword">value</parameter></methodparam>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">markup</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">value</parameter>&nbsp;:</term>
          <listitem><simpara>the value at which the mark is placed, must be between the lower and upper limits of the scales' adjustment.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>where to draw the mark. For a horizontal scale, <literal>gtk.POS_TOP</literal> is drawn above the scale,
          anything else below. For a vertical scale, <literal>gtk.POS_LEFT</literal> is drawn to the left of the scale, anything else
          to the right.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">markup</parameter>&nbsp;:</term>
          <listitem><simpara>text to be shown at the mark, using <link linkend="pango-markup-language">Pango markup</link>, or <literal>None</literal>.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.16 and above.</para>
      </note>

      <para>The <methodname>add_mark</methodname>() method adds a mark at value.
      A mark is indicated visually by drawing a tick mark next to the scale, and GTK+
      makes it easy for the user to position the scale exactly at the marks value.
      If markup is not <literal>None</literal>, text is shown next to the tick mark.
      To remove marks from a scale, use <link linkend="method-gtkscale--clear-marks"><methodname>clear_marks</methodname></link>().</para>

    </refsect2>

    <refsect2 id="method-gtkscale--clear-marks">
      <title>gtk.Scale.clear_marks</title>

      <programlisting><methodsynopsis language="python">
        <methodname>clear_marks</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <note>
        <para>This method is available in PyGTK 2.16 and above.</para>
      </note>

      <para>The <methodname>clear_marks</methodname>() method removes any marks that have been
      added with <link linkend="method-gtkscale--add-mark"><methodname>add_mark</methodname></link>().</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkscale--format-value">
      <title>The "format-value" gtk.Scale Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>scale</parameter></methodparam>
	  <methodparam><parameter>value</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>scale</parameter>&nbsp;:</term>
	  <listitem><simpara>the scale that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>value</parameter>&nbsp;:</term>
	  <listitem><simpara>the value to be formatted</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a string representing
	  <parameter>value</parameter> for display</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "format-value" signal is emitted when the scale is being
redrawn with a value displayed. The "format-value" signal handler should
return a formatted string containing <parameter>value</parameter>.</para>

    </refsect2>

  </refsect1>

</refentry>