Bug 527212 – types with well-defined equality semantics are not properly

2008-08-02  Paul Pogonyshev  <pogonyshev@gmx.net>

	Bug 527212 – types with well-defined equality semantics are not
	properly comparable

	* gtk/gdk.override (_wrap_pygdk_region_tp_richcompare): New
	function.

	* gtk/gdkcolor.override (_wrap_gdk_color_tp_richcompare): New
	function.

	* gtk/gdkrectangle.override (_wrap_gdk_rectangle_tp_richcompare):
	New function.

	* tests/test_conversion.py (testColorCreation): Move to thematic
	test file.

	* tests/Makefile.am:
	* tests/test_color.py:
	* tests/test_rectangle.py: Two new test files.

2008-08-02  Paul Pogonyshev  <pogonyshev@gmx.net>

	Bug 527212 – types with well-defined equality semantics are not
	properly comparable

	* pygtk-gdkcolor.xml: Document new constructor option.  Document
	proper comparison as of PyGTK 2.14.

	* pygtk-gdkregion.xml: Document proper comparison as of PyGTK
	2.14.

	* pygtk-gdkrectangle.xml: Document proper comparison as of PyGTK
	2.14.

svn path=/trunk/; revision=3014

4 files changed, 61 insertions, 0 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 0635f42e..00db8482 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,17 @@
+2008-08-02  Paul Pogonyshev  <pogonyshev@gmx.net>
+
+	Bug 527212 – types with well-defined equality semantics are not
+	properly comparable
+
+	* pygtk-gdkcolor.xml: Document new constructor option.  Document
+	proper comparison as of PyGTK 2.14.
+
+	* pygtk-gdkregion.xml: Document proper comparison as of PyGTK
+	2.14.
+
+	* pygtk-gdkrectangle.xml: Document proper comparison as of PyGTK
+	2.14.
+
 2008-07-26  Paul Pogonyshev  <pogonyshev@gmx.net>
 
 	* pygtk-gtkbuilder.xml (connect_signals): Fix signature and
diff --git a/docs/reference/pygtk-gdkcolor.xml b/docs/reference/pygtk-gdkcolor.xml
index ccd69e8b..efc21fd6 100644
--- a/docs/reference/pygtk-gdkcolor.xml
+++ b/docs/reference/pygtk-gdkcolor.xml
@@ -109,6 +109,14 @@ objects since these colors will be allocated when an attempt is made to use
 the <link linkend="class-gtkstyle"><classname>gtk.Style</classname></link>
 object.</para>
 
+    <para>
+      Starting with PyGTK 2.14 <classname>gtk.gdk.Color</classname> objects are properly
+      comparable.  By Python rules, colors (being mutable) are now unhashable.  If you
+      need to use them as dictionary keys, use string representation instead.  You can
+      convert string representation to <classname>gtk.gdk.Color</classname> objects using
+      the constructor.
+    </para>
+
   </refsect1>
 
   <refsect1 id="constructor-gdkcolor">
@@ -128,6 +136,11 @@ object.</para>
 	<methodparam><parameter
 		       role="keyword">pixel</parameter>
 	  <initializer>0</initializer></methodparam>
+    </constructorsynopsis></programlisting>
+    <programlisting><constructorsynopsis language="python">
+	<methodname>gtk.gdk.Color</methodname>
+	<methodparam><parameter
+		       role="keyword">spec</parameter></methodparam>
       </constructorsynopsis></programlisting>
     <variablelist>
       <varlistentry>
@@ -151,6 +164,10 @@ object.</para>
 colormap</simpara></listitem>
       </varlistentry>
       <varlistentry>
+	<term><parameter role="keyword">spec</parameter>&nbsp;:</term>
+	<listitem><simpara>String containing color specification</simpara></listitem>
+      </varlistentry>
+      <varlistentry>
 	<term><emphasis>Returns</emphasis>&nbsp;:</term>
 	<listitem><simpara>a new <link
 linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
@@ -158,6 +175,10 @@ object</simpara></listitem>
       </varlistentry>
     </variablelist>
 
+    <note>
+      <para>Second form of the constructor is available in PyGTK 2.14 and above.</para>
+    </note>
+
     <para>Creates a new <link
 linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link> object
 with the color component values specified by <parameter>red</parameter>,
@@ -166,6 +187,9 @@ with the color component values specified by <parameter>red</parameter>,
 value of <parameter>pixel</parameter> will be overwritten when the color is
 allocated.</para>
 
+    <para>Second form of the constructor is analogous to
+      <link linkend="function-gdk--color-parse"><function>gtk.gdk.color_parse</function></link>.</para>
+
   </refsect1>
   
     <refsect1>
diff --git a/docs/reference/pygtk-gdkrectangle.xml b/docs/reference/pygtk-gdkrectangle.xml
index 19de9bb3..222ab3f5 100644
--- a/docs/reference/pygtk-gdkrectangle.xml
+++ b/docs/reference/pygtk-gdkrectangle.xml
@@ -101,6 +101,18 @@ holds the position and size of a rectangle. The position is specified by the
 "x" and "y" attributes and the size, by the "width" and "height"
 attributes.</para>
 
+    <para>
+      Starting with PyGTK 2.14 <classname>gtk.gdk.Rectangle</classname> objects are
+      properly comparable.  By Python rules, rectangles (being mutable) are now
+      unhashable.  If you need to use them as dictionary keys, convert rectangle objects
+      to tuples first.  You can convert such tuples back
+      to <classname>gtk.gdk.Rectangle</classname> using the following code:
+    </para>
+
+    <programlisting>
+  rectangle = gtk.gdk.Rectangle(*tuple)
+    </programlisting>
+
   </refsect1>
 
   <refsect1 id="constructor-gdkrectangle">
diff --git a/docs/reference/pygtk-gdkregion.xml b/docs/reference/pygtk-gdkregion.xml
index d2631743..5cfa1830 100644
--- a/docs/reference/pygtk-gdkregion.xml
+++ b/docs/reference/pygtk-gdkregion.xml
@@ -125,6 +125,12 @@ linkend="function-gdk--region-rectangle">gtk.gdk.region_rectangle</link></method
     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">
@@ -228,6 +234,11 @@ object</simpara></listitem>
       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">