<?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-gdkregion">
  <refnamediv>
    <refname>gtk.gdk.Region</refname>
    <refpurpose>an object representing a set of pixels on the screen (new in
    PyGTK 2.10)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.gdk.Region</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gdkregion">gtk.gdk.Region</link></methodname>
	<methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--get-clipbox">get_clipbox</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--empty">empty</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--equal">equal</link></methodname>
	<methodparam><parameter
		       role="keyword">other</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--point-in">point_in</link></methodname>
	<methodparam><parameter
		       role="keyword">x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--rect-in">rect_in</link></methodname>
	<methodparam><parameter
		       role="keyword">rect</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--copy">copy</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--offset">offset</link></methodname>
	<methodparam><parameter
		       role="keyword">dx</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">dy</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--shrink">shrink</link></methodname>
	<methodparam><parameter
		       role="keyword">dx</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">dy</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--union-with-rect">union_with_rect</link></methodname>
	<methodparam><parameter
		       role="keyword">rect</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--intersect">intersect</link></methodname>
	<methodparam><parameter
		       role="keyword">source2</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--union">union</link></methodname>
	<methodparam><parameter
		       role="keyword">source2</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--subtract">subtract</link></methodname>
	<methodparam><parameter
		       role="keyword">source2</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkregion--xor">xor</link></methodname>
	<methodparam><parameter
		       role="keyword">source2</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

    <programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
  <methodname><link
linkend="function-gdk--region-rectangle">gtk.gdk.region_rectangle</link></methodname>
  <methodparam><parameter
                   role="keyword">rectangle</parameter></methodparam>
</methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
    linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>
    is an objrect holding a set of arbitrary pixels, and is usually used for
    clipping graphical operations (see the <link
    linkend="method-gdkgc--set-clip-region"><methodname>gtk.gdk.GC.set_clip_region</methodname>()</link>
    method).</para>

    <para>
      Starting with PyGTK 2.14 <classname>gtk.gdk.Region</classname> objects are
      properly comparable.  By Python rules, regions (being mutable) are now
      unhashable.
    </para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.gdk.Region</methodname>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>
object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <note>
      <para>This constructor is available in PyGTK 2.10 and above.</para>
    </note>

    <para>Creates a new <link
    linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gdkregion--get-clipbox">
      <title>gtk.gdk.Region.get_clipbox</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_clipbox</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>returns the smallest rectangle which includes all
          of the region.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_clipbox</methodname>() method returns the
      smallest rectangle which includes the entire region.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--empty">
      <title>gtk.gdk.Region.empty</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>empty</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>True if the region is empty.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>empty</methodname>() method returns True if the
      region is empty.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--equal">
      <title>gtk.gdk.Region.equal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>equal</methodname>
	  <methodparam><parameter
			 role="keyword">other</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">other</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>True if the region is equal to
	  <parameter>other</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>equal</methodname>() method returns True if the
      region specified by <parameter>other</parameter> is equal to this
      region.</para>

      <note>
        <para>Since PyGTK 2.14 Python comparison operator (<literal>==</literal>) can be
	  used for the same result.</para>
      </note>

    </refsect2>

    <refsect2 id="method-gdkregion--point-in">
      <title>gtk.gdk.Region.point_in</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>point_in</methodname>
	  <methodparam><parameter
			 role="keyword">x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">x</parameter>&nbsp;:</term>
	  <listitem><simpara>the x coordinate of a point.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y</parameter>&nbsp;:</term>
	  <listitem><simpara>the y coordinate of a point.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>True if the point (x,y) is in the
          region.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname></methodname>() method returns True if the point
      specified by the coordinates <parameter>x</parameter> and
      <parameter>y</parameter> is in a region.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--rect-in">
      <title>gtk.gdk.Region.rect_in</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>rect_in</methodname>
	  <methodparam><parameter
			 role="keyword">rect</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">rect</parameter>&nbsp;:</term>
	  <listitem><simpara>a rectangle (<link
	  linkend="class-gdkrectangle"><classname>gtk.gdk.Rectangle</classname></link>
	  or 4-tuple representing a rectangle) </simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a value indicating whether
	  <parameter>rectangle</parameter> is inside or outside the
	  region.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>rect_in</methodname>() method returns one of the
      <xref linkend="gdk-overlap-type-constants"
      endterm="gdk-overlap-type-constants-title"></xref> depending whether
      the rectangle specified by <parameter>rect</parameter> is inside,
      outside, or partly inside this region.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--copy">
      <title>gtk.gdk.Region.copy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>copy</methodname>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>
	  identical to the region</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>copy</methodname>() method returns a new <link
      linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>
      identical to this region.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--offset">
      <title>gtk.gdk.Region.offset</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>offset</methodname>
	  <methodparam><parameter
			 role="keyword">dx</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">dy</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">dx</parameter>&nbsp;:</term>
	  <listitem><simpara>the distance to move this region
          horizontally.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">dy</parameter>&nbsp;:</term>
	  <listitem><simpara>the distance to move this region
          vertically.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>offset</methodname>() method moves this region
      the distance specified by <parameter>dx</parameter> and
      <parameter>dy</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--shrink">
      <title>gtk.gdk.Region.shrink</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>shrink</methodname>
	  <methodparam><parameter
			 role="keyword">dx</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">dy</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">dx</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of pixels to shrink this region
          horizontally.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">dy</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of pixels to shrink this region
          vertically. </simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>shrink</methodname>() method resizes this region
      by the amount specified by <parameter>dx</parameter> and
      <parameter>dy</parameter>. Positive values shrink the region. Negative
      values expand it.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--union-with-rect">
      <title>gtk.gdk.Region.union_with_rect</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>union_with_rect</methodname>
	  <methodparam><parameter
			 role="keyword">rect</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">rect</parameter>&nbsp;:</term>
	  <listitem><simpara>a rectangle</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>union_with_rect</methodname>() method sets the
      area of this region to the union of the areas of this region and the
      rectangle specified by <parameter>rect</parameter>. The resulting area
      is the set of pixels contained in either the region or
      <parameter>rect</parameter>. The value of <parameter>rect</parameter>
      is either a <link
      linkend="class-gdkrectangle"><classname>gtk.gdk.Rectangle</classname></link>
      or a 4-tuple containing the position and size of a rectangle.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--intersect">
      <title>gtk.gdk.Region.intersect</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>intersect</methodname>
	  <methodparam><parameter
			 role="keyword">source2</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">source2</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>intersect</methodname>() method sets the area of
      this region to the intersection of the areas of this region and the
      region specified by <parameter>source2</parameter>. The resulting area
      is the set of pixels contained in both this region and
      <parameter>source2</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--union">
      <title>gtk.gdk.Region.union</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>union</methodname>
	  <methodparam><parameter
			 role="keyword">source2</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">source2</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>union</methodname>() method sets the area of
      this region to the union of the areas of this region and the region
      specified by <parameter>source2</parameter>. The resulting area is the
      set of pixels contained in either this region or
      <parameter>source2</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--subtract">
      <title>gtk.gdk.Region.subtract</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>subtract</methodname>
	  <methodparam><parameter
			 role="keyword">source2</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">source2</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>subtract</methodname>() method sets the area of
      this region to the subtraction of the areas of this region and the
      region specified by <parameter>source2</parameter>. The resulting area
      is the set of pixels contained in this region but not in
      <parameter>source2</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gdkregion--xor">
      <title>gtk.gdk.Region.xor</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>xor</methodname>
	  <methodparam><parameter
			 role="keyword">source2</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">source2</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>xor</methodname>() method sets the area of this
      region to the exclusive-OR of the areas of this region and the region
      specified by <parameter>source2</parameter>. The resulting area is the
      set of pixels contained in either this region or
      <parameter>source2</parameter> but not both.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gdk--region-rectangle">
      <title>gtk.gdk.region_rectangle</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.gdk.region_rectangle</methodname>
	  <methodparam><parameter
			 role="keyword">rectangle</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">rectangle</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkrectangle"><classname>gtk.gdk.Rectangle</classname></link>
	  or a 4-tuple representing a rectangle.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <function>gtk.gdk.region_rectangle</function>() function
      creates a new <link
      linkend="class-gdkregion"><classname>gtk.gdk.Region</classname></link>
      containing the area specified by
      <parameter>rectangle</parameter>.</para>

    </refsect2>

  </refsect1>

</refentry>
