path: root/docs/reference/pygtk-gtkspinbutton.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-gtkspinbutton">
  <refnamediv>
    <refname>gtk.SpinButton</refname>
    <refpurpose>retrieve an integer or floating-point number from the
user.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.SpinButton</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkentry">gtk.Entry</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkspinbutton">gtk.SpinButton</link></methodname>
	<methodparam><parameter
		       role="keyword">adjustment</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">climb_rate</parameter><initializer>0.0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">digits</parameter><initializer>0</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--configure">configure</link></methodname>
	<methodparam><parameter
		       role="keyword">adjustment</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">climb_rate</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">digits</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-adjustment">set_adjustment</link></methodname>
	<methodparam><parameter
		       role="keyword">adjustment</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-adjustment">get_adjustment</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-digits">set_digits</link></methodname>
	<methodparam><parameter
		       role="keyword">digits</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-digits">get_digits</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-increments">set_increments</link></methodname>
	<methodparam><parameter
		       role="keyword">step</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">page</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-increments">get_increments</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-range">set_range</link></methodname>
	<methodparam><parameter role="keyword">min</parameter></methodparam>
	<methodparam><parameter role="keyword">max</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-range">get_range</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-value">get_value</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-value-as-int">get_value_as_int</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-value">set_value</link></methodname>
	<methodparam><parameter
		       role="keyword">value</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-update-policy">set_update_policy</link></methodname>
	<methodparam><parameter
		       role="keyword">policy</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-update-policy">get_update_policy</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-numeric">set_numeric</link></methodname>
	<methodparam><parameter
		       role="keyword">numeric</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-numeric">get_numeric</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--spin">spin</link></methodname>
	<methodparam><parameter
		       role="keyword">direction</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">increment</parameter><initializer>1.0</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-wrap">set_wrap</link></methodname>
	<methodparam><parameter
		       role="keyword">wrap</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-wrap">get_wrap</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--set-snap-to-ticks">set_snap_to_ticks</link></methodname>
	<methodparam><parameter
		       role="keyword">snap_to_ticks</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--get-snap-to-ticks">get_snap_to_ticks</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkspinbutton--update">update</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-gtkentry">gtk.Entry</link> (implements <link linkend="class-gtkeditable">gtk.Editable</link>, <link linkend="class-gtkcelleditable">gtk.CellEditable</link>)
        +-- <link linkend="class-gtkspinbutton">gtk.SpinButton</link>
</synopsis>

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


  <refsect1 id="properties-gtkspinbutton">
    <title>gtk.SpinButton 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-gtkentry">gtk.Entry 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>"adjustment"</entry>
	      <entry>Read-Write</entry>
	      <entry>The adjustment that holds the value of the
spinbutton</entry>
	    </row>

	    <row valign="top">
	      <entry>"climb-rate"</entry>
	      <entry>Read-Write</entry>
	      <entry>The acceleration rate when you hold down a
button</entry>
	    </row>

	    <row valign="top">
	      <entry>"digits"</entry>
	      <entry>Read-Write</entry>
	      <entry>The number of decimal places to display</entry>
	    </row>

	    <row valign="top">
	      <entry>"numeric"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, non-numeric characters
should be ignored</entry>
	    </row>

	    <row valign="top">
	      <entry>"snap-to-ticks"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, erroneous values are
automatically changed to a spin button's nearest step increment</entry>
	    </row>

	    <row valign="top">
	      <entry>"update-policy"</entry>
	      <entry>Read-Write</entry>
	      <entry>either <literal>gtk.UPDATE_ALWAYS</literal> (the spin
button should update always), or <literal>gtk.UPDATE_IF_VALID</literal> the
spin button should update only when the value is legal)</entry>
	    </row>

	    <row valign="top">
	      <entry>"value"</entry>
	      <entry>Read-Write</entry>
	      <entry>the current value</entry>
	    </row>

	    <row valign="top">
	      <entry>"wrap"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, a spin button should wrap
upon reaching its limits</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="style-properties-gtkspinbutton">
    <title>gtk.SpinButton Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
    <para><link linkend="style-properties-gtkentry">gtk.Entry 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>"shadow-type"</entry>
	      <entry>Read</entry>
	      <entry>the shadow type of the spinbutton - one of:
<literal>gtk.SHADOW_NONE</literal>, <literal>gtk.SHADOW_IN</literal>,
<literal>gtk.SHADOW_OUT</literal>, <literal>gtk.SHADOW_ETCHED_IN</literal>
or <literal>gtk.SHADOW_ETCHED_OUT</literal></entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkspinbutton">
    <title>gtk.SpinButton 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-gtkentry">gtk.Entry Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkeditable">gtk.Editable Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcelleditable">gtk.CellEditable Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkspinbutton--change-value">change-value</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>spinbutton</parameter></methodparam>
            <methodparam><parameter>scrolltype</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkspinbutton--input">input</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>spinbutton</parameter></methodparam>
            <methodparam><parameter>value_ptr</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkspinbutton--output">output</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>spinbutton</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkspinbutton--value-changed">value-changed</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>spinbutton</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkspinbutton--wrapped">wrapped</link></term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>spinbutton</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gtkspinbutton"><classname>gtk.SpinButton</classname></link>
is a subclass of <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> that
provides a way for a user to set the value of some numeric attribute within
a predefined range. Rather than having to directly type a number into a
<link linkend="class-gtkentry"><classname>gtk.Entry</classname></link>, a
<link
linkend="class-gtkspinbutton"><classname>gtk.SpinButton</classname></link>
allows the user to click on one of two arrows to increment or decrement the
displayed value. A value can still be typed in and validated. A <link
linkend="class-gtkspinbutton"><classname>gtk.SpinButton</classname></link>
uses a <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
to specify the range and value of interest. See the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
section for more details about an adjustment's properties.</para>

  </refsect1>

  <refsect1 id="constructor-gtkspinbutton">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.SpinButton</methodname>
	<methodparam><parameter
		       role="keyword">adjustment</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">climb_rate</parameter><initializer>0.0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">digits</parameter><initializer>0</initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">adjustment</parameter>&nbsp;:</term>
	<listitem><simpara>a <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
or None to create a new adjustment</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">climb_rate</parameter>&nbsp;:</term>
	<listitem><simpara>the acceleration factor</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">digits</parameter>&nbsp;:</term>
	<listitem><simpara>the number of decimal places to
display</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtkspinbutton"><classname>gtk.SpinButton</classname></link>
widget</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkspinbutton"><classname>gtk.SpinButton</classname></link>
widget using the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
specified by <parameter>adjustment</parameter>, the acceleration factor
specified by <parameter>climb_rate</parameter> and displaying the number of
decimals specified by <parameter>digits</parameter>. If
<parameter>adjustment</parameter> is <literal>None</literal> or is not
specified a new <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
will be created. If <parameter>climb_rate</parameter> is not specified it
defaults to 0.0. If <parameter>digits</parameter> is not specified it
defaults to 0.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkspinbutton--configure">
      <title>gtk.SpinButton.configure</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>configure</methodname>
	  <methodparam><parameter
			 role="keyword">adjustment</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">climb_rate</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">digits</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">adjustment</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
or None to create a new adjustment</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">climb_rate</parameter>&nbsp;:</term>
	  <listitem><simpara>the acceleration factor</simpara></listitem>
	</varlistentry>
	<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>configure</methodname>() method changes the
properties of an existing spin button by associating the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
specified by <parameter>adjustment</parameter>, setting the acceleration
rate to the c value specified by <parameter>climb_rate</parameter> and
setting  the number of decimal places to display to the value specified by
<parameter>digits</parameter>. If <parameter>adjustment</parameter> is
<literal>None</literal> a new <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
will be created. </para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-adjustment">
      <title>gtk.SpinButton.set_adjustment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_adjustment</methodname>
	  <methodparam><parameter
			 role="keyword">adjustment</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">adjustment</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
to replace the existing adjustment</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_adjustment</methodname>() method sets the
"adjustment" property to the value  specified by
<parameter>adjustment</parameter> replacing the current adjustment object
associated with the spinbutton.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-adjustment">
      <title>gtk.SpinButton.get_adjustment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_adjustment</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
object associated with the spinbutton</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_adjustment</methodname>() method returns the
value of the "adjustment" property.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-digits">
      <title>gtk.SpinButton.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 be displayed
for the spin button's value</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 "digits" determines the number of decimal places (up to 20
digits) to be displayed by the spinbutton.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-digits">
      <title>gtk.SpinButton.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 current number of decimal places to be
displayed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_digits</methodname>() method returns the
value of the "digits" property. The value of "digits" determines the number
of decimal places the spinbutton displays. See the <link
linkend="method-gtkspinbutton--set-digits"><methodname>set_digits</methodname>()</link> 
method for more detail.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-increments">
      <title>gtk.SpinButton.set_increments</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_increments</methodname>
	  <methodparam><parameter
			 role="keyword">step</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">page</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">step</parameter>&nbsp;:</term>
	  <listitem><simpara>increment applied for each
<mousebutton>left</mousebutton> mousebutton press.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">page</parameter>&nbsp;:</term>
	  <listitem><simpara>increment applied for each
<mousebutton>middle</mousebutton> mousebutton press.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_increments</methodname>() method sets the
<literal>step_increment</literal> and <literal>page_increment</literal>
attributes of the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
associated with the spinbutton to the values specified by
<parameter>step</parameter> and <parameter>page</parameter> respectively.
These affect how quickly the value changes when the spin button's arrows are
activated.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-increments">
      <title>gtk.SpinButton.get_increments</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_increments</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the step and page
increments</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_increments</methodname>() method returns a
tuple containing the values of the <literal>step_increment</literal> and
<literal>page_increment</literal> attributes of the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
associated with the spinbutton. See the <link
linkend="method-gtkspinbutton--set-increments"><methodname>set_increments</methodname>()</link> 
method for more detail.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-range">
      <title>gtk.SpinButton.set_range</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_range</methodname>
	  <methodparam><parameter
			 role="keyword">min</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">max</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">min</parameter>&nbsp;:</term>
	  <listitem><simpara>the minimum allowable
value</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">max</parameter>&nbsp;:</term>
	  <listitem><simpara>the maximum allowable
value</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_range</methodname>() method sets the minimum
and maximum allowable values for spinbutton by setting the
<literal>lower</literal> and <literal>upper</literal> attributes of the
associated <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
to the values of <parameter>min</parameter> and <parameter>max</parameter>
respectively.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-range">
      <title>gtk.SpinButton.get_range</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_range</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the minimum and maximum
allowed values</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_range</methodname>() method returns a tuple
containing the range allowed for the spinbutton. See the <link
linkend="method-gtkspinbutton--set-range"><methodname>set_range</methodname>()</link> 
method for more detail.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-value">
      <title>gtk.SpinButton.get_value</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_value</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the value of the
spin_button</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_value</methodname>() method returns the
value of the "value" property of the spinbutton (really the
<literal>value</literal> attribute of the associated <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>).</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-value-as-int">
      <title>gtk.SpinButton.get_value_as_int</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_value_as_int</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the value of the spinbutton as an
integer</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_value_as_int</methodname>() method returns
the value of the spinbutton represented as an integer.</para>

      </refsect2>

    <refsect2 id="method-gtkspinbutton--set-value">
      <title>gtk.SpinButton.set_value</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_value</methodname>
	  <methodparam><parameter
			 role="keyword">value</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">value</parameter>&nbsp;:</term>
	  <listitem><simpara>the new value</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_value</methodname>() method sets the value
of the "value" property to the value specified by
<parameter>value</parameter> (sets the <literal>value</literal> attribute of
the associated <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-update-policy">
      <title>gtk.SpinButton.set_update_policy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_update_policy</methodname>
	  <methodparam><parameter
			 role="keyword">policy</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">policy</parameter>&nbsp;:</term>
	  <listitem><simpara>the new update policy</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_update_policy</methodname>() method sets the
"update-policy" property to the value of <parameter>policy</parameter>. The
value of <parameter>policy</parameter> is either of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.UPDATE_ALWAYS</literal></term>
	  <listitem>
	    <simpara>the value is always displayed.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UPDATE_IF_VALID</literal></term>
	  <listitem>
	    <simpara>the value is only displayed if it is valid within the
bounds of the spinbutton's <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-update-policy">
      <title>gtk.SpinButton.get_update_policy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_update_policy</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the current update policy</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_update_policy</methodname>() method returns
the value of the "update-policy" property that determines the update
behavior of a spin button. See the <link
linkend="method-gtkspinbutton--set-update-policy"><methodname>set_update_policy</methodname>()</link> 
method for more detail.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-numeric">
      <title>gtk.SpinButton.set_numeric</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_numeric</methodname>
	  <methodparam><parameter
			 role="keyword">numeric</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">numeric</parameter>&nbsp;:</term>
	  <listitem><simpara>a flag indicating if only numeric entry is
allowed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_numeric</methodname>() method sets the value
of the "numeric" property to the value of <parameter>numeric</parameter>. If
<parameter>numeric</parameter> is <literal>True</literal> only numeric text
can be typed into the spin button.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-numeric">
      <title>gtk.SpinButton.get_numeric</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_numeric</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if only numeric text
can be entered</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_numeric</methodname>() method returns the
value of the "numeric" preoperty. See the <link
linkend="method-gtkspinbutton--set-numeric"><methodname>set_numeric</methodname>()</link> 
method for more detail.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--spin">
      <title>gtk.SpinButton.spin</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>spin</methodname>
	  <methodparam><parameter
			 role="keyword">direction</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">increment</parameter><initializer>1.0</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">direction</parameter>&nbsp;:</term>
	  <listitem><simpara>the direction to spin.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">increment</parameter>&nbsp;:</term>
	  <listitem><simpara>the step increment to apply in the specified
direction.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>spin</methodname>() method increments or
decrements a spin button's value in the direction specified by
<parameter>direction</parameter> with a step size specified by
<parameter>increment</parameter>. The value of
<parameter>increment</parameter> is only used if direction is
<literal>gtk.SPIN_USER_DEFINED</literal>. The value of
<parameter>direction</parameter> must be one of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.SPIN_STEP_FORWARD</literal></term>
	  <listitem>
	    <simpara>forward by step_increment</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.SPIN_STEP_BACKWARD</literal></term>
	  <listitem>
	    <simpara>backward by step_increment</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.SPIN_PAGE_FORWARD</literal></term>
	  <listitem>
	    <simpara>forward by step_increment</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.SPIN_PAGE_BACKWARD</literal></term>
	  <listitem>
	    <simpara>backward by step_increment</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.SPIN_HOME</literal></term>
	  <listitem>
	    <simpara>move to minimum value</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.SPIN_END</literal></term>
	  <listitem>
	    <simpara>move to maximum value</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.SPIN_USER_DEFINED</literal></term>
	  <listitem>
	    <simpara>add <parameter>increment</parameter> to the
value</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-wrap">
      <title>gtk.SpinButton.set_wrap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_wrap</methodname>
	  <methodparam><parameter
			 role="keyword">wrap</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">wrap</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> wrapping is
performed.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_wrap</methodname>() method sets the "wrap"
property to the value of <parameter>wrap</parameter>. If
<parameter>wrap</parameter> is <literal>True</literal> the spin button value
wraps around to the opposite limit when the upper or lower limit of the
range is exceeded.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-wrap">
      <title>gtk.SpinButton.get_wrap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_wrap</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the spin button
wraps</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_wrap</methodname>() method returns the value
of the "wrap" property. If the value of "wrap" is <literal>True</literal>
the spinbutton's value wraps around to the opposite limit when the upper or
lower limit of the range is exceeded. See the <link
linkend="method-gtkspinbutton--set-wrap"><methodname>set_wrap</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--set-snap-to-ticks">
      <title>gtk.SpinButton.set_snap_to_ticks</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_snap_to_ticks</methodname>
	  <methodparam><parameter
			 role="keyword">snap_to_ticks</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">snap_to_ticks</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> invalid values
should be corrected.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_snap_to_ticks</methodname>() method sets the
"snap-to-ticks" property to the value of
<parameter>snap_to_ticks</parameter>. If
<parameter>snap_to_ticks</parameter> is <literal>True</literal> values are
corrected to the nearest step increment when a spin button is activated
after providing an invalid value.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--get-snap-to-ticks">
      <title>gtk.SpinButton.get_snap_to_ticks</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_snap_to_ticks</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if values are snapped
to the nearest step.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_snap_to_ticks</methodname>() method returns
the value of the "snap-to-ticks" property. If the value of "snap-to-ticks"
is <literal>True</literal> the input values are corrected to the nearest
step. See the <link
linkend="method-gtkspinbutton--set-snap-to-ticks"><methodname>set_snap_to_ticks</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkspinbutton--update">
      <title>gtk.SpinButton.update</title>

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

      <para>The <methodname>update</methodname>() method manually forces an
update of the spin button.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkspinbutton--change-value">
      <title>The "change-value" gtk.SpinButton Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>spinbutton</parameter></methodparam>
	  <methodparam><parameter>scrolltype</parameter></methodparam>
 	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>spinbutton</parameter>&nbsp;:</term>
	  <listitem><simpara>the spinbutton that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>scrolltype</parameter>&nbsp;:</term>
	  <listitem><simpara>the scrolltype:
<literal>gtk.SCROLL_STEP_UP</literal>,
<literal>gtk.SCROLL_STEP_DOWN</literal>,
<literal>gtk.SCROLL_PAGE_UP</literal>, <literal>gtk.SCROLL_PAGE_DOWN,
<literal>gtk.SCROLL_START</literal> or
<literal>gtk.SCROLL_END</literal></literal></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>
      </variablelist>

      <para>The "change-value" signal is emitted when the spinbutton value is
changed by keyboard action using the <keycombo><keycap>Up Arrow</keycap>
</keycombo>, <keycombo><keycap>Down Arrow</keycap> </keycombo>,
<keycombo><keycap>Page Up</keycap> </keycombo>, <keycombo><keycap>Page
Down</keycap> </keycombo>, <keycombo
action="simul"><keycap>Control</keycap><keycap>Page Up</keycap> </keycombo>
or <keycombo action="simul"><keycap>Control</keycap><keycap>Page
Down</keycap> </keycombo> keys.</para>

    </refsect2>

    <refsect2 id="signal-gtkspinbutton--input">
      <title>The "input" gtk.SpinButton Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>spinbutton</parameter></methodparam>
	  <methodparam><parameter>value_ptr</parameter></methodparam>
 	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>spinbutton</parameter>&nbsp;:</term>
	  <listitem><simpara>the spinbutton that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>value_ptr</parameter>&nbsp;:</term>
	  <listitem><simpara>a pointer to the value</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><literal>True</literal> if the input value was
	  retrieved and handled; <literal>False</literal> if not handled and
	  -1 if an error occurred during processing.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "input" signal is emitted when the value changes. The
value_ptr is a GPointer to the value that cannot be accessed from PyGTK.
This signal cannot be handled in PyGTK.</para>

    </refsect2>

    <refsect2 id="signal-gtkspinbutton--output">
      <title>The "output" gtk.SpinButton Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>spinbutton</parameter>&nbsp;:</term>
	  <listitem><simpara>the spinbutton that received the
signal</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><literal>True</literal> if no further
	  processing is required.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "output" signal is emitted when the spinbutton display value
is changed either by setting a new value or changing the digits and on
realizing the widget. Returns <literal>True</literal> if the handler
successfully set the text and no further processing is required.</para>

    </refsect2>

    <refsect2 id="signal-gtkspinbutton--value-changed">
      <title>The "value-changed" gtk.SpinButton Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>spinbutton</parameter>&nbsp;:</term>
	  <listitem><simpara>the spinbutton that received the
signal</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>
      </variablelist>

      <para>The "value-changed" signal is emitted when any of the settings (i.e. value, digits) that change the display of the spinbutton are changed.</para>

    </refsect2>

    <refsect2 id="signal-gtkspinbutton--wrapped">
      <title>The "wrapped" gtk.SpinButton Signal</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter>spinbutton</parameter>&nbsp;:</term>
          <listitem><simpara>the object which received the signal
 the object which received the signal.</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>
      </variablelist>

      <note>
        <para>This signal is available in GTK+ 2.10 and above.</para>
      </note>

      <para>The "wrapped" signal is emitted right after the spinbutton wraps
      from its maximum to minimum value or vice-versa.</para>

    </refsect2>

  </refsect1>

</refentry>