path: root/docs/reference/pygtk-gtkcurve.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-gtkcurve">
  <refnamediv>
    <refname>gtk.Curve</refname>
    <refpurpose>allows direct editing of a curve.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Curve</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkdrawingarea">gtk.DrawingArea</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkcurve">gtk.Curve</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcurve--reset">reset</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcurve--set-gamma">set_gamma</link></methodname>
	<methodparam><parameter
		       role="keyword">gamma</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcurve--set-range">set_range</link></methodname>
	<methodparam><parameter
		       role="keyword">min_x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">max_x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">min_y</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">max_y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcurve--get-vector">get_vector</link></methodname>
	<methodparam><parameter
		       role="keyword">size</parameter><initializer>-1</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcurve--set-vector">set_vector</link></methodname>
	<methodparam><parameter
		       role="keyword">vector</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcurve--set-curve-type">set_curve_type</link></methodname>
	<methodparam><parameter
		       role="keyword">type</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-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkdrawingarea">gtk.DrawingArea</link>
        +-- <link linkend="class-gtkcurve">gtk.Curve</link>
</synopsis>

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

  <refsect1 id="properties-gtkcurve">
    <title>gtk.Curve Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget 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="3.5in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"curve-type"</entry>
	      <entry>Read/Write</entry>
	<entry>The curve type. One of linear
(<literal>gtk.CURVE_TYPE_LINEAR</literal>), spline interpolated
(<literal>gtk.CURVE_TYPE_SPLINE</literal>), or free-form
(<literal>gtk.CURVE_TYPE_FREE</literal>).</entry>
	  </row>

	<row valign="top">
	  <entry>"max-x"</entry>
	  <entry>Read/Write</entry>
	  <entry>The maximum possible value for X</entry>
	</row>

	<row valign="top">
	  <entry>"max-y"</entry>
	  <entry>Read/Write</entry>
	  <entry>The maximum possible value for Y</entry>
	</row>

	<row valign="top">
	  <entry>"min-x"</entry>
	  <entry>Read/Write</entry>
	  <entry>The minimum possible value for X</entry>
	</row>

	<row valign="top">
	  <entry>"min-y"</entry>
	  <entry>Read/Write</entry>
	  <entry>The minimum possible value for Y</entry>
	</row>

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

  </refsect1>


  <refsect1 id="style-properties-gtkcurve">
    <title>gtk.Curve Style Properties</title>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkcurve">
    <title>gtk.Curve 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>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcurve--curve-type-changed">curve-type-changed</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>curve</parameter>
            </methodparam>
            <methodparam><parameter>widget</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para><link linkend="class-gtkcurve"><classname>gtk.Curve</classname></link>
      is deprecated in GTK+ 2.20 and PyGTK 2.22 since it is too specialized.</para>
    </note>

    <para>The <link
linkend="class-gtkcurve"><classname>gtk.Curve</classname></link> widget
allows the user to edit a curve covering a range of values. It is typically
used to fine-tune color balances in graphics applications like the
<application>Gimp</application>. The <link
linkend="class-gtkcurve"><classname>gtk.Curve</classname></link> widget has
3 modes of operation - spline, linear and free. In spline mode the user
places points on the curve which are automatically connected together into a
smooth curve. In linear mode the user places points on the curve which are
connected by straight lines. In free mode the user can draw the points of
the curve freely, and they are not connected at all.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Curve</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new gtk.Curve object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkcurve"><classname>gtk.Curve</classname></link>
object</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcurve--reset">
      <title>gtk.Curve.reset</title>

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

      <para>The <methodname>reset</methodname>() method resets the curve to
a straight line from the minimum x and y values to the maximum x and y
values (i.e. from the bottom-left to the top-right corners). The curve type
is not changed.</para>

    </refsect2>

    <refsect2 id="method-gtkcurve--set-gamma">
      <title>gtk.Curve.set_gamma</title>

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

      <para>The <methodname>set_gamma</methodname>() method recomputes the
entire curve using the value in <parameter>gamma</parameter>. A gamma value
of 1 results in a straight line. Values greater than 1 result in a curve
above the straight line. Values less than 1 result in a curve below the
straight line. The curve type is changed to
<literal>gtk.CURVE_TYPE_FREE</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkcurve--set-range">
      <title>gtk.Curve.set_range</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_range</methodname>
	  <methodparam><parameter
			 role="keyword">min_x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">max_x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">min_y</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">max_y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">min_x</parameter>&nbsp;:</term>
	  <listitem><simpara>the new minimum x value</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">max_x</parameter>&nbsp;:</term>
	  <listitem><simpara>the maximum x value.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">min_y</parameter>&nbsp;:</term>
	  <listitem><simpara>the new minimum y value</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">max_y</parameter>&nbsp;:</term>
	  <listitem><simpara>the maximum y value.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_range</methodname>() method sets the
"min-x", "min-y", "max-x" and "max-y" properties from<parameter>
min_x</parameter>, <parameter>min_y</parameter>,<parameter>
max_x</parameter>, and <parameter>max_y</parameter>. The curve is also reset
with a call to <link
linkend="method-gtkcurve--reset"><methodname>reset</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkcurve--get-vector">
      <title>gtk.Curve.get_vector</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_vector</methodname>
	  <methodparam><parameter
			 role="keyword">size</parameter><initializer>-1</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">size</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of points to return or -1 to return
all the points in the curve.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the
points</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_vector</methodname>() method returns a tuple
of points representing the curve. The number of points to return is
specified by <parameter>size</parameter>; if <parameter>size</parameter> is
-1 all the points in the curve are returned.</para>

    </refsect2>

    <refsect2 id="method-gtkcurve--set-vector">
      <title>gtk.Curve.set_vector</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_vector</methodname>
	  <methodparam><parameter
			 role="keyword">vector</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">vector</parameter>&nbsp;:</term>
	  <listitem><simpara>a list or tuple containing the points of the
curve</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_vector</methodname>() method sets the curve
using the points in <parameter>vector</parameter>. The curve type is set to
<literal>gtk.CURVE_TYPE_FREE</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkcurve--set-curve-type">
      <title>gtk.Curve.set_curve_type</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_curve_type</methodname>
	  <methodparam><parameter
			 role="keyword">type</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>the new curve type:
<literal>gtk.CURVE_TYPE_LINEAR</literal>,
<literal>gtk.CURVE_TYPE_SPLINE</literal> or
<literal>gtk.CURVE_TYPE_FREE</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_curve_type</methodname>() method sets the
"curve-type" property with the value of <parameter>type</parameter>. The
curve type must be one of <literal>gtk.CURVE_TYPE_LINEAR</literal>,
<literal>gtk.CURVE_TYPE_SPLINE</literal> or
<literal>gtk.CURVE_TYPE_FREE</literal>. The curve will remain unchanged
except when changing from a free curve to a linear or spline curve, in which
case the curve will be changed as little as possible.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkcurve--curve-type-changed">
      <title>The "curve-type-changed" gtk.Curve Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>curve</parameter>&nbsp;:</term>
	  <listitem><simpara>the curve 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 "curve-type-changed" signal is emitted when the curve type
has been changed. The curve type can be changed explicitly with a call to
<link
linkend="method-gtkcurve--set-curve-type"><methodname>set_curve_type</methodname>()</link>. 
It is also changed as a side-effect of calling <link
linkend="method-gtkcurve--reset"><methodname>reset</methodname>()</link> or
<link
linkend="method-gtkcurve--set-gamma"><methodname>set_gamma</methodname>()</link></para>

    </refsect2>

  </refsect1>

</refentry>