path: root/docs/reference/pygtk-gtkadjustment.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-gtkadjustment">
  <refnamediv>
    <refname>gtk.Adjustment</refname>
      <refpurpose>an object representing an adjustable bounded
value</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Adjustment</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkobject">gtk.Object</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkadjustment">gtk.Adjustment</link></methodname>
	<methodparam><parameter
		       role="keyword">value</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">lower</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">upper</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">step_incr</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">page_incr</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">page_size</parameter><initializer>0</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkadjustment--set-all">set_all</link></methodname>
	<methodparam><parameter
		       role="keyword">value</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">lower</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">upper</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">step_increment</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">page_increment</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">page_size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkadjustment--changed">changed</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkadjustment--value-changed">value_changed</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkadjustment--clamp-page">clamp_page</link></methodname>
	<methodparam><parameter
		       role="keyword">lower</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">upper</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkadjustment--get-value">get_value</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkadjustment--set-value">set_value</link></methodname>
	<methodparam><parameter
		       role="keyword">value</parameter></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-gtkadjustment">gtk.Adjustment</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Signal Prototypes</title>

    <variablelist>
      <varlistentry>
	<term>"<link
linkend="signal-gtkadjustment--changed">changed</link>"</term>
	<listitem>
	  <methodsynopsis
	    language="python"><methodname>callback</methodname>
	    <methodparam><parameter>adjustment</parameter>
	    </methodparam>
	    <methodparam><parameter>user_param1</parameter>
	    </methodparam>
	    <methodparam><parameter>...</parameter>
	    </methodparam>
	  </methodsynopsis>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>"<link
linkend="signal-gtkadjustment--value-changed">value-changed</link>"</term>
	<listitem>
	  <methodsynopsis
	    language="python"><methodname>callback</methodname>
	    <methodparam><parameter>adjustment</parameter>
	    </methodparam>
	    <methodparam><parameter>user_param1</parameter>
	    </methodparam>
	    <methodparam><parameter>...</parameter>
	    </methodparam>
	  </methodsynopsis>
	</listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Properties</title>

    <note>
      <para>These properties are only available in GTK+ 2.4 and above. The
      GTK+ version is contained in the 3-tuple gtk.gtk_version.</para>
    </note>

    <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>"lower"</entry>
	      <entry>Read-Write</entry>
	      <entry>The minimum value of the adjustment. (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"page-increment"</entry>
	      <entry>Read-Write</entry>
	      <entry>The page increment of the adjustment. (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"page-size"</entry>
	      <entry>Read-Write</entry>
	      <entry>The page size of the adjustment. (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"step-increment"</entry>
	      <entry>Read-Write</entry>
	      <entry>The step increment of the adjustment. (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"upper"</entry>
	      <entry>Read-Write</entry>
	      <entry>The maximum value of the adjustment. (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"value"</entry>
	      <entry>Read-Write</entry>
	      <entry>The value of the adjustment. (float)</entry>
	    </row>

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

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <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>"value"</entry>
	      <entry>Read-Write</entry>
	      <entry>the current value (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"lower"</entry>
	      <entry>Read-Write</entry>
	      <entry>the minimum value (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"upper"</entry>
	      <entry>Read-Write</entry>
	      <entry>the maximum value (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"step_increment"</entry>
	      <entry>Read-Write</entry>
	      <entry>the increment to use to make minor changes to the
value. In a <link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>
this increment is used when the mouse is clicked on the arrows at the top
and bottom of the scrollbar, to scroll by a small amount. (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"page_increment"</entry>
	      <entry>Read-Write</entry>
	      <entry>the increment to use to make major changes to the
value. In a <link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>
this increment is used when the mouse is clicked in the trough, to scroll by
a large amount. (float)</entry>
	    </row>

	    <row valign="top">
	      <entry>"page_size"</entry>
	      <entry>Read-Write</entry>
	      <entry>a widget specific size. In a <link
linkend="class-gtkscrollbar"><classname>gtk.Scrollbar</classname></link>
this is the size of the area which is currently visible. (float)</entry>
	    </row>

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

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
object contains a value which has an associated lower and upper bound,
together with step and page increments, and a page size. It is used in
conjunction with several PyGTK widgets, including <link
linkend="class-gtkadjustment"><classname>gtk.SpinButton</classname></link>,
<link
linkend="class-gtkadjustment"><classname>gtk.Viewport</classname></link>,
and <link
linkend="class-gtkadjustment"><classname>gtk.Range</classname></link> (which
is a base class for <link
linkend="class-gtkadjustment"><classname>gtk.HScrollbar</classname></link>,
<link
linkend="class-gtkadjustment"><classname>gtk.VScrollbar</classname></link>,
<link
linkend="class-gtkadjustment"><classname>gtk.HScale</classname></link>, and
<link
linkend="class-gtkadjustment"><classname>gtk.VScale</classname></link>).</para>

    <para>A <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
can be shared by multiple widgets. The <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
object does not update the value itself. Instead it is left up to the
associated widget(s) that use the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
to control the value.</para>

    <para>The widget using the <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
typically calls the <link
linkend="method-gtkadjustment--value-changed"><methodname>value_changed</methodname>()</link> 
or <link
linkend="method-gtkadjustment--changed"><methodname>changed</methodname>()</link> 
methods after changing the value or its bounds. This results in the emission
of the "value_changed" or "changed" signal respectively.</para>

    <para>A <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
object contains several attributes that provide access to its value and
bounds:</para>
    <itemizedlist>
      <listitem>
	<simpara>value</simpara>
      </listitem>
       <listitem>
	<simpara>lower</simpara>
      </listitem>
      <listitem>
	<simpara>upper</simpara>
      </listitem>
      <listitem>
	<simpara>step_increment</simpara>
      </listitem>
     <listitem>
	<simpara>page_increment</simpara>
      </listitem>
     <listitem>
	<simpara>page_size</simpara>
      </listitem>
    </itemizedlist>

    <para>The attribute values can be retrieved and set similar to:</para>

    <programlisting>
  adjustment.upper = 25.0
  lower = adjustment.lower
</programlisting>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Adjustment</methodname>
	<methodparam><parameter
		       role="keyword">value</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">lower</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">upper</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">step_incr</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">page_incr</parameter><initializer>0</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">page_size</parameter><initializer>0</initializer></methodparam>
      </constructorsynopsis></programlisting>

    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">value</parameter>&nbsp;:</term>
	<listitem><simpara>the initial value.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">lower</parameter>&nbsp;:</term>
	<listitem><simpara>the minimum value.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">upper</parameter>&nbsp;:</term>
	<listitem><simpara>the maximum value.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">step_incr</parameter>&nbsp;:</term>
	<listitem><simpara>the step increment.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">page_incr</parameter>&nbsp;:</term>
	<listitem><simpara>the page increment.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">page_size</parameter>&nbsp;:</term>
	<listitem><simpara>the page size.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new gtk.Adjustment object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para><function>gtk.Adjustment</function>() creates a new <link
linkend="class-gtkadjustment"><classname>gtk.Adjustment</classname></link>
object with the specified attributes. Any attributes not specified are set
to 0.0 by default.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkadjustment--set-all">
      <title>gtk.Adjustment.set_all</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_all</methodname>
	  <methodparam><parameter
			 role="keyword">value</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">lower</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">upper</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">step_increment</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">page_increment</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">page_size</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">value</parameter>&nbsp;:</term>
	  <listitem><simpara>the new value.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">lower</parameter>&nbsp;:</term>
	  <listitem><simpara>the new minimum value.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">upper</parameter>&nbsp;:</term>
	  <listitem><simpara>the new maximum value.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">step_increment</parameter>&nbsp;:</term>
	  <listitem><simpara>the new step increment.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">page_increment</parameter>&nbsp;:</term>
	  <listitem><simpara>the new page increment.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">page_size</parameter>&nbsp;:</term>
	  <listitem><simpara>the new page size.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_all</methodname>() method sets the
attributes of the adjustment to the specified values.</para>

    </refsect2>

    <refsect2 id="method-gtkadjustment--changed">
      <title>gtk.Adjustment.changed</title>

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

      <para>The <methodname>changed</methodname>() method emits a "changed"
signal from the adjustment. This must typically be called if any of the
adjustment attributes other than value has changed so that the widget(s)
using the adjustment can reflect the changes. Applications usually will not
need to use this method since setting the attributes directly will automatically
invoke this method.</para>

    </refsect2>


    <refsect2 id="method-gtkadjustment--value-changed">
      <title>gtk.Adjustment.value_changed</title>

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

      <para>The <methodname>value_changed</methodname>() method emits a
"value_changed" signal from the adjustment. This must typically be called
after the value attribute of the adjustment has changed. Applications
usually will not need to use this method since setting the attribute
directly will automatically invoke this method as will using the <link
linkend="method-gtkadjustment--set-value"><methodname>set_value</methodname>()</link> 
method.</para>

    </refsect2>


    <refsect2 id="method-gtkadjustment--clamp-page">
      <title>gtk.Adjustment.clamp_page</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>clamp_page</methodname>
	  <methodparam><parameter role="keyword">lower</parameter></methodparam>
	  <methodparam><parameter role="keyword">upper</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">lower</parameter>&nbsp;:</term>
	  <listitem>the lower value<simpara></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">upper</parameter>&nbsp;:</term>
	  <listitem><simpara>the upper value</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>clamp_page</methodname>() method updates the
adjustment value to ensure that the range between
<parameter>lower</parameter> and <parameter>upper</parameter> is in the
current page (i.e. between value and value + page_size). If the range is
larger than the page size, then only the start of it will be in the current
page. A "changed" signal will be emitted if the value is changed.</para>

    </refsect2>


    <refsect2 id="method-gtkadjustment--get-value">
      <title>gtk.Adjustment.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 current value of the
adjustment.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_value</methodname>() method gets the current
value of the adjustment.</para>

    </refsect2>


    <refsect2 id="method-gtkadjustment--set-value">
      <title>gtk.Adjustment.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 adjustment to the specified <parameter>value</parameter>.</para>

    </refsect2>


  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkadjustment--changed">
      <title>The "changed" gtk.Adjustment Signal</title>

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

    <variablelist>
      <varlistentry>
	<term><parameter>adjustment</parameter>&nbsp;:</term>
	<listitem><simpara>the object 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 "changed" signal is emitted when one (or more) of the
adjustment attributes (except the value attribute) has changed.</para>

    </refsect2>

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

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

    <variablelist>
      <varlistentry>
	<term><parameter>adjustment</parameter>&nbsp;:</term>
	<listitem><simpara>the object 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 the adjustment value
attribute has changed.</para>

    </refsect2>
  </refsect1>

</refentry>