Updated gdk docs with 2.12 API.

svn path=/trunk/; revision=2923

7 files changed, 339 insertions, 11 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 35f8f92c..9790d12c 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,12 @@
+2007-10-21  Gian Mario Tagliaretti  <gianmt@gnome.org>
+
+	* pygtk-gdk-functions.xml:
+	* pygtk-gdkwindow.xml:
+	* pygtk-gdkevent.xml:
+	* pygtk-gdkkeymap.xml:
+	* pygtk-gdkdisplay.xml:
+	* pygtk-gdkcolor.xml: Updated with 2.12 API.
+
 2007-10-18  Gian Mario Tagliaretti  <gianmt@gnome.org>
 
 	* pygtk-gtktextview.xml: fix bug #389422.
diff --git a/docs/reference/pygtk-gdk-functions.xml b/docs/reference/pygtk-gdk-functions.xml
index 004c0e60..7abc3598 100644
--- a/docs/reference/pygtk-gdk-functions.xml
+++ b/docs/reference/pygtk-gdk-functions.xml
@@ -588,12 +588,17 @@ linkend="function-gdk--get-display-arg-name">gtk.gdk.get_display_arg_name</link>
 	<methodparam></methodparam>
   </methodsynopsis><methodsynopsis language="python">
 	<methodname><link
-linkend="function-gdk--gdk-pango-context-get-for-screen">gtk.gdk.gdk_pango_context_get_for_screen</link></methodname>
+linkend="function-gdk--pango-context-get-for-screen">gtk.gdk.pango_context_get_for_screen</link></methodname>
 	<methodparam><parameter
 		       role="keyword">screen</parameter></methodparam>
   </methodsynopsis><methodsynopsis language="python">
 	<methodname><link
-linkend="function-gdk--gdk-pango-context-get">gtk.gdk.gdk_pango_context_get</link></methodname>
+linkend="function-gdk--pango-context-get">gtk.gdk.pango_context_get</link></methodname>
+  </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gdk--x11-display-get-startup-notification-id">gtk.gdk.x11_display_get_startup_notification_id</link></methodname>
+  <methodparam><parameter
+		       role="keyword">display</parameter></methodparam>
   </methodsynopsis></programlisting>
 
     </refsect2>
@@ -1463,11 +1468,11 @@ returns the display name specified in the command line arguments, if any or
 
     </refsect2>
 
-    <refsect2 id="function-gdk--gdk-pango-context-get-for-screen">
-      <title>gtk.gdk.gdk_pango_context_get_for_screen</title>
+    <refsect2 id="function-gdk--pango-context-get-for-screen">
+      <title>gtk.gdk.pango_context_get_for_screen</title>
 
       <programlisting><methodsynopsis language="python">
-	  <methodname>gtk.gdk.gdk_pango_context_get_for_screen</methodname>
+	  <methodname>gtk.gdk.pango_context_get_for_screen</methodname>
 	  <methodparam><parameter
 			 role="keyword">screen</parameter></methodparam>
 	</methodsynopsis></programlisting>
@@ -1490,7 +1495,7 @@ object</simpara></listitem>
       </note>
 
       <para>The
-<function>gtk.gdk.gdk_pango_context_get_for_screen</function>() function
+<function>gtk.gdk.pango_context_get_for_screen</function>() function
 creates a new <link
 linkend="class-pangocontext"><classname>pango.Context</classname></link>
 object for the <link
@@ -1503,11 +1508,11 @@ the widget you intend to render text onto.</para>
 
     </refsect2>
 
-    <refsect2 id="function-gdk--gdk-pango-context-get">
-      <title>gtk.gdk.gdk_pango_context_get</title>
+    <refsect2 id="function-gdk--pango-context-get">
+      <title>gtk.gdk.pango_context_get</title>
 
       <programlisting><methodsynopsis language="python">
-	  <methodname>gtk.gdk.gdk_pango_context_get</methodname>
+	  <methodname>gtk.gdk.pango_context_get</methodname>
 	</methodsynopsis></programlisting>
       <variablelist>
 	<varlistentry>
@@ -1522,7 +1527,7 @@ for the default display.</simpara></listitem>
         <para>This function is available in PyGTK 2.8 and above</para>
       </note>
 
-      <para>The <function>gtk.gdk.gdk_pango_context_get</function>()
+      <para>The <function>gtk.gdk.pango_context_get</function>()
 function creates a new <link
 linkend="class-pangocontext"><classname>pango.Context</classname></link> for
 the default display. Normally you should use the <link
@@ -1531,6 +1536,37 @@ method instead of this function, to get the appropriate Pango context for
 the widget you intend to render text onto.</para>
 
     </refsect2>
+    
+    <refsect2 id="function-gdk--x11-display-get-startup-notification-id">
+      <title>gtk.gdk.x11_display_get_startup_notification_id</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>gtk.gdk.x11_display_get_startup_notification_id</methodname>
+	  <methodparam><parameter
+			 role="keyword">display</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><parameter role="keyword">display</parameter>&nbsp;:</term>
+	  <listitem><simpara>a <link
+linkend="class-gdkdisplay"><classname>gtk.gdk.Display</classname></link></simpara></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>the startup notification ID for <parameter>display</parameter>
+      </simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <note>
+        <para>This function is available in PyGTK 2.12 and above</para>
+      </note>
+
+      <para>The
+<function>gtk.gdk.x11_display_get_startup_notification_id</function>() function
+gets the startup notification ID for a display.</para>
+
+    </refsect2>
 
   </refsect1>
 
diff --git a/docs/reference/pygtk-gdkcolor.xml b/docs/reference/pygtk-gdkcolor.xml
index 36e987ec..ccd69e8b 100644
--- a/docs/reference/pygtk-gdkcolor.xml
+++ b/docs/reference/pygtk-gdkcolor.xml
@@ -29,7 +29,14 @@ linkend="constructor-gdkcolor">gtk.gdk.Color</link></methodname>
 	<methodparam><parameter
 		       role="keyword">pixel</parameter>
 	  <initializer>0</initializer></methodparam>
-      </constructorsynopsis></classsynopsis>
+      </constructorsynopsis>
+      
+      <methodsynopsis language="python">
+        <methodname><link linkend="method-gdkcolor--to-string">to_string</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    
+    </classsynopsis>
 
     <programlisting>
 <emphasis role="bold">Functions</emphasis>
@@ -160,6 +167,37 @@ value of <parameter>pixel</parameter> will be overwritten when the color is
 allocated.</para>
 
   </refsect1>
+  
+    <refsect1>
+        <title>Methods</title>
+
+        <refsect2 id="method-gdkcolor--to-string">
+            <title>gtk.gdk.Color.to_string</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>to_string</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                        <listitem><simpara>a string</simpara></listitem>
+                </varlistentry>
+            </variablelist>
+
+            <note>
+                <para>This method is available in PyGTK 2.12 and above.</para>
+            </note>
+
+            <para>
+                The <methodname>to_string</methodname>() method returns a textual
+                specification of color in the hexadecimal form #rrrrggggbbbb,
+                where r, g and b are hex digits representing the red,
+                green and blue components respectively.
+            </para>
+        </refsect2>
+    </refsect1>
 
   <refsect1>
     <title>Functions</title>
diff --git a/docs/reference/pygtk-gdkdisplay.xml b/docs/reference/pygtk-gdkdisplay.xml
index 9633cd4d..5cf84ac7 100644
--- a/docs/reference/pygtk-gdkdisplay.xml
+++ b/docs/reference/pygtk-gdkdisplay.xml
@@ -119,6 +119,10 @@ END NOT IMPLEMENTED -->
 	<methodparam><parameter role="keyword">distance</parameter></methodparam>
       </methodsynopsis>
       <methodsynopsis language="python">
+	<methodname><link linkend="method-gdkdisplay--supports-cursor-alpha">supports_composite</link></methodname>
+	<methodparam></methodparam>
+      </methodsynopsis>
+      <methodsynopsis language="python">
 	<methodname><link linkend="method-gdkdisplay--supports-cursor-alpha">supports_cursor_alpha</link></methodname>
 	<methodparam></methodparam>
       </methodsynopsis>
@@ -850,6 +854,35 @@ set this, it is a global user-configured setting.</para>
 
     </refsect2>
 
+    <refsect2 id="method-gdkdisplay--supports-composite">
+      <title>gtk.gdk.Display.supports_composite</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>supports_composite</methodname>
+	  <methodparam></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara><literal>True</literal> if windows may be composited.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <note>
+	<para>This method is available in PyGTK 2.12 and above.</para>
+      </note>
+
+      <para>The <methodname>supports_composite</methodname>() method
+returns <literal>True</literal> if <link linkend="method-gdkwindow--set-composite">
+<methodname>gtk.gdk.Window.set_composite</methodname></link>() can be used to redirect
+drawing on the window using compositing.
+    </para>
+      <para>
+        Currently this only works on X11 with XComposite and XDamage extensions available.
+    </para>
+
+    </refsect2>
+    
     <refsect2 id="method-gdkdisplay--supports-cursor-alpha">
       <title>gtk.gdk.Display.supports_cursor_alpha</title>
 
diff --git a/docs/reference/pygtk-gdkevent.xml b/docs/reference/pygtk-gdkevent.xml
index ff36df22..c995aaa2 100644
--- a/docs/reference/pygtk-gdkevent.xml
+++ b/docs/reference/pygtk-gdkevent.xml
@@ -100,6 +100,10 @@ linkend="function-gdk--get-show-events">gtk.gdk.get_show_events</link></methodna
 linkend="function-gdk--event-handler-set">gtk.gdk.event_handler_set</link></methodname>
 	<methodparam><parameter>func</parameter></methodparam>
 	<methodparam><parameter>data</parameter><initializer>None</initializer></methodparam>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gdk--event-request-motions">gtk.gdk.event_request_motions</link></methodname>
+	<methodparam><parameter>event</parameter></methodparam>
       </methodsynopsis></programlisting>
 
   </refsect1>
@@ -2448,6 +2452,40 @@ returns the setting of the internal debug events flag.</para>
       <parameter>data</parameter>.</para>
 
     </refsect2>
+    
+    <refsect2 id="function-gdk--event-request-motions">
+      <title>gtk.gdk.event_request_motions</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>gtk.gdk.event_request_motions</methodname>
+	  <methodparam><parameter>event</parameter></methodparam>
+	</methodsynopsis></programlisting>
+
+      <variablelist>
+	<varlistentry>
+	  <term><parameter>event</parameter>&nbsp;:</term>
+	  <listitem><simpara>a valid <link
+      linkend="class-gdkevent"><classname>gtk.gdk.Event</classname></link>
+      </simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <note>
+        <para>This function is available in PyGTK 2.12 and above.</para>
+      </note>
+
+      <para>The <function>gtk.gdk.event_request_motions</function>() function
+      request more motion notifies if event is a motion notify hint event.
+      This function should be used instead of <methodname><link
+      linkend="method-gdkwindow--get-pointer">gtk.gdk.Window.get_pointer</link></methodname>() to
+      request further motion notifies, because it also works for extension
+      events where motion notifies are provided for devices other than the core pointer.
+      </para>
+
+      <!-- FIXME Coordinate extraction, processing and requesting more motion events from a
+      gtk.gdk.MOTION_NOTIFY event usually works like this:-->
+
+    </refsect2>
 
   </refsect1>
 
diff --git a/docs/reference/pygtk-gdkkeymap.xml b/docs/reference/pygtk-gdkkeymap.xml
index adce874d..22cf3049 100644
--- a/docs/reference/pygtk-gdkkeymap.xml
+++ b/docs/reference/pygtk-gdkkeymap.xml
@@ -40,6 +40,10 @@ linkend="class-gobject">gobject.GObject</link></classname></ooclass>
 	<methodname><link
 linkend="method-gdkkeymap--get-direction">get_direction</link></methodname>
 	<methodparam></methodparam>  </methodsynopsis>
+      <methodsynopsis language="python">
+	<methodname><link
+linkend="method-gdkkeymap--have-bidi-layouts">have_bidi_layouts</link></methodname>
+	<methodparam></methodparam>  </methodsynopsis>
     </classsynopsis>
 
     <programlisting>
@@ -453,6 +457,26 @@ method for more information.</para>
       <para>The <methodname>get_direction</methodname>() method returns the direction of the keymap.</para>
 
     </refsect2>
+    
+    <refsect2 id="method-gdkkeymap--have-bidi-layouts">
+    <title>gtk.gdk.Keymap.have_bidi_layouts</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>have_bidi_layouts</methodname>
+	  <methodparam></methodparam>  </methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara><literal>True</literal> if there are layouts in both directions,
+      <literal>FALSE</literal> otherwise.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>have_bidi_layouts</methodname>() method
+      determines if keyboard layouts for both right-to-left and left-to-right
+      languages are in use.</para>
+
+    </refsect2>
 
   </refsect1>
 
diff --git a/docs/reference/pygtk-gdkwindow.xml b/docs/reference/pygtk-gdkwindow.xml
index dd7a0b20..5cdab06a 100644
--- a/docs/reference/pygtk-gdkwindow.xml
+++ b/docs/reference/pygtk-gdkwindow.xml
@@ -664,6 +664,23 @@ linkend="method-gdkwindow--input-shape-combine-region">input_shape_combine_regio
 	<methodparam><parameter
 		       role="keyword">offset_y</parameter></methodparam>
       </methodsynopsis>
+      
+        <methodsynopsis language="python">
+            <methodname><link linkend="method-gdkwindow--beep">beep</link></methodname>
+            <methodparam></methodparam>
+        </methodsynopsis>
+        <methodsynopsis language="python">
+            <methodname><link linkend="method-gdkwindow--set-composited">set_composited</link></methodname>
+            <methodparam><parameter role="keyword">composited</parameter></methodparam>
+        </methodsynopsis>
+        <methodsynopsis language="python">
+            <methodname><link linkend="method-gdkwindow--set-opacity">set_opacity</link></methodname>
+            <methodparam><parameter role="keyword">opacity</parameter></methodparam>
+        </methodsynopsis>
+        <methodsynopsis language="python">
+            <methodname><link linkend="method-gdkwindow--set-startup-id">set_startup_id</link></methodname>
+            <methodparam><parameter role="keyword">startup_id</parameter></methodparam>
+        </methodsynopsis>
     </classsynopsis>
 
     <programlisting>
@@ -4102,6 +4119,139 @@ the window</simpara></listitem>
       extension.</para>
 
     </refsect2>
+    
+    <refsect2 id="method-gdkwindow--beep">
+        <title>gtk.gdk.Window.beep</title>
+
+        <programlisting><methodsynopsis language="python">
+        <methodname>beep</methodname>
+        <methodparam></methodparam>
+        </methodsynopsis></programlisting>
+        
+        <variablelist>
+        </variablelist>
+
+        <note>
+            <para>This method is available in PyGTK 2.12 and above.</para>
+        </note>
+
+        <para>
+            Emits a short beep associated to window in the appropriate display,
+            if supported. Otherwise, emits a short beep on the display just as
+            <methodname><link linkend="method-gdkdisplay--beep">gtk.gdk.Display.beep</link></methodname>().
+        </para>
+
+    </refsect2>
+    
+    <refsect2 id="method-gdkwindow--set-composited">
+        <title>gtk.gdk.Window.set_composited</title>
+
+        <programlisting><methodsynopsis language="python">
+        <methodname>set_composited</methodname>
+        <methodparam><parameter role="keyword">composited</parameter></methodparam>
+        </methodsynopsis></programlisting>
+        
+        <variablelist>
+            <varlistentry>
+                <term><parameter role="keyword">composited</parameter>&nbsp;:</term>
+                <listitem><simpara><literal>True</literal> to set the window as composited</simpara></listitem>
+            </varlistentry>
+        </variablelist>
+
+        <note>
+            <para>This method is available in PyGTK 2.12 and above.</para>
+        </note>
+
+        <para>
+            Sets a GdkWindow as composited, or unsets it. Composited windows do
+            not automatically have their contents drawn to the screen. Drawing is
+            redirected to an offscreen buffer and an expose event is emitted on
+            the parent of the composited window. It is the responsibility of the
+            parent's expose handler to manually merge the off-screen content onto
+            the screen in whatever way it sees fit.
+            <!-- FIXME See Example 7, “Composited windows” for an example. -->
+        </para>
+        <para>
+            It only makes sense for child windows to be composited; see
+            <methodname><link linkend="method-gdkwindow--set-opacity">gtk.gdk.Window.set_opacity</link></methodname>()
+            if you need translucent toplevel windows.
+        </para>
+        <para>
+            An additional effect of this call is that the area of this window is no longer
+            clipped from regions marked for invalidation on its parent. Draws done on the
+            parent window are also no longer clipped by the child.
+        </para>
+        <para>
+            This call is only supported on some systems (currently, only X11 with
+            new enough Xcomposite and Xdamage extensions). You must call
+            <methodname><link linkend="method-gdkdisplay--supports-cursor-alpha">gtk.gdk.Display.supports_composite</link></methodname>()
+            to check if setting a window as composited is supported before attempting to do so.
+        </para>
+
+    </refsect2>
+    
+    <refsect2 id="method-gdkwindow--set-opacity">
+        <title>gtk.gdk.Window.set_opacity</title>
+
+        <programlisting><methodsynopsis language="python">
+        <methodname>set_opacity</methodname>
+        <methodparam><parameter role="keyword">opacity</parameter></methodparam>
+        </methodsynopsis></programlisting>
+        
+        <variablelist>
+            <varlistentry>
+                <term><parameter role="keyword">opacity</parameter>&nbsp;:</term>
+                <listitem><simpara>The opacity value.</simpara></listitem>
+            </varlistentry>
+        </variablelist>
+
+        <note>
+            <para>This method is available in PyGTK 2.12 and above.</para>
+        </note>
+
+        <para>
+            Request the windowing system to make window partially transparent, with
+            opacity 0 being fully transparent and 1 fully opaque.
+            Values of the opacity parameter are clamped to the [0,1] range.)
+        </para>
+        <para>
+            On X11, this works only on X screens with a compositing manager running.
+        </para>
+        <para>
+            For setting up per-pixel alpha, see
+            <methodname><link linkend="method-gdkscreen--get-rgba-colormap">gtk.gdk.Screen.get_rgba_colormap</link></methodname>().
+            For making non-toplevel windows translucent, see
+            <methodname><link linkend="method-gdkwindow--set-composited">gtk.gdk.Window.set_composited</link></methodname>().
+        </para>
+
+    </refsect2>
+    
+    <refsect2 id="method-gdkwindow--set-startup-id">
+        <title>gtk.gdk.Window.set_startup_id</title>
+
+        <programlisting><methodsynopsis language="python">
+        <methodname>set_startup_id</methodname>
+        <methodparam><parameter role="keyword">startup_id</parameter></methodparam>
+        </methodsynopsis></programlisting>
+        
+        <variablelist>
+            <varlistentry>
+                <term><parameter role="keyword">startup_id</parameter>&nbsp;:</term>
+                <listitem><simpara>A string with startup-notification identifier.</simpara></listitem>
+            </varlistentry>
+        </variablelist>
+
+        <note>
+            <para>This method is available in PyGTK 2.12 and above.</para>
+        </note>
+
+        <para>
+            When using GTK+, typically you should use
+            <methodname><link linkend="method-gtkwindow--set-startup-id">gtk.Window.set_startup_id</link></methodname>()
+            instead of this low-level function.
+        </para>
+
+    </refsect2>
 
   </refsect1>