Allow pango.Context creation

Wrap and document pango.Context constructor, set_font_map() and
pango.FontMap.create_context() methods.  Bug #550855.

4 files changed, 133 insertions, 9 deletions

diff --git a/docs/reference/pygtk-pangocontext.xml b/docs/reference/pygtk-pangocontext.xml
index 1a9dbd70..ddb3fdd2 100644
--- a/docs/reference/pygtk-pangocontext.xml
+++ b/docs/reference/pygtk-pangocontext.xml
@@ -16,6 +16,18 @@ rendering.</refpurpose>
       <ooclass><classname>pango.Context</classname></ooclass>
       <ooclass><classname><link
 linkend="class-gobject">gobject.GObject</link></classname></ooclass>
+      <constructorsynopsis language="python">
+	<methodname><link linkend="constructor-pangocontext">pango.Context</link></methodname>
+	<methodparam></methodparam>
+      </constructorsynopsis>
+      <methodsynopsis language="python">
+	<methodname><link linkend="method-pangocontext--get-font-map">get_font_map</link></methodname>
+	<methodparam></methodparam>
+      </methodsynopsis>
+      <methodsynopsis language="python">
+	<methodname><link linkend="method-pangocontext--set-font-map">set_font_map</link></methodname>
+	<methodparam><parameter role="keyword">font_map</parameter></methodparam>
+      </methodsynopsis>
       <methodsynopsis language="python">
 	<methodname><link
 linkend="method-pangocontext--list-families">list_families</link></methodname>
@@ -122,9 +134,85 @@ method.</para>
 
   </refsect1>
 
+  <refsect1 id="constructor-pangocontext">
+    <title>Constructor</title>
+
+    <programlisting><constructorsynopsis language="python">
+	<methodname>pango.Context</methodname>
+    </constructorsynopsis></programlisting>
+    <variablelist>
+      <varlistentry>
+	<term><emphasis>Returns</emphasis>&nbsp;:</term>
+	<listitem><simpara>a new <link linkend="class-pangocontext"><classname>pango.Context</classname></link>
+            <emphasis>without</emphasis> an associated font map</simpara></listitem>
+      </varlistentry>
+    </variablelist>
+
+    <note>
+      <para>Constructor is available in PyGTK 2.16 and above.</para>
+    </note>
+
+    <para>Creates a new PangoContext initialized to default values.</para>
+
+    <para>This constructor is not particularly useful as it should always be followed by a
+      call to <link linkend="method-pangocontext--set-font-map">set_font_map</link>
+      method.  Method <link linkend="method-pangofontmap--create-context">pango.FontMap.create_context</link>
+      does these two steps together and hence users are recommended to use that.</para>
+
+    <para>If you are using Pango as part of a higher-level system, that system may have
+      it's own way of create a <link linkend="class-pangocontext">pango.Context</link>.
+      For instance, the GTK+ toolkit has, among others,
+      <link linkend="function-gdk--pango-context-get-for-screen">gtk.gdk.pango_context_get_for_screen</link>
+      and <link linkend="method-gtkwidget--get-pango-context">gtk.Widget.get_pango_context</link>.
+      Use those instead.
+    </para>
+  </refsect1>
+
   <refsect1>
     <title>Methods</title>
 
+    <refsect2 id="method-pangocontext--get-font-map">
+      <title>pango.Context.get_font_map</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>get_font_map</methodname>
+	  <methodparam></methodparam>
+      </methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>the font map for the
+              <link linkend="class-pangocontext"><classname>pango.Context</classname></link>.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2 id="method-pangocontext--set-font-map">
+      <title>pango.Context.get_font_map</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>set_font_map</methodname>
+	  <methodparam><parameter role="keyword">font_map</parameter></methodparam>
+      </methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><parameter role="keyword">font_map</parameter>&nbsp;:</term>
+	  <listitem><simpara>the <link linkend="class-pangofontmap"><classname>pango.FontMap</classname>
+                to set</link> object</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <note>
+        <para>This method is available in PyGTK 2.16 and above.</para>
+      </note>
+
+      <para>Sets the font map to be searched when fonts are looked-up in this
+        context. This is only for internal use by Pango backends,
+        a <link linkend="class-pangocontext"><classname>pango.Context</classname></link>
+        obtained via one of the recommended methods should already have a suitable font
+        map.</para>
+    </refsect2>
+
     <refsect2 id="method-pangocontext--list-families">
       <title>pango.Context.list_families</title>
 
diff --git a/docs/reference/pygtk-pangofontmap.xml b/docs/reference/pygtk-pangofontmap.xml
index a8dbeef4..791b7343 100644
--- a/docs/reference/pygtk-pangofontmap.xml
+++ b/docs/reference/pygtk-pangofontmap.xml
@@ -17,6 +17,10 @@ particular rendering system.</refpurpose>
       <ooclass><classname><link
 linkend="class-gobject">gobject.GObject</link></classname></ooclass>
       <methodsynopsis language="python">
+	<methodname><link linkend="method-pangofontmap--create-context">create_context</link></methodname>
+	<methodparam></methodparam>
+      </methodsynopsis>
+      <methodsynopsis language="python">
 	<methodname><link
 linkend="method-pangofontmap--load-font">load_font</link></methodname>
 	<methodparam><parameter
@@ -72,6 +76,40 @@ object in <literal>PyGTK</literal>.</para>
   <refsect1>
     <title>Methods</title>
 
+    <refsect2 id="method-pangofontmap--create-context">
+      <title>pango.FontMap.create_context</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>create_context</methodname>
+	  <methodparam></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>the newly allocated
+              <link linkend="class-pangocontext"><classname>pango.Context</classname></link>.</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <note>
+        <para>This method is available in PyGTK 2.16 and above.</para>
+      </note>
+
+      <para>Creates
+        a <link linkend="class-pangocontext"><classname>pango.Context</classname></link>
+        connected to fontmap. This is equivalent to calling the class
+        constructor followed
+        by <link linkend="method-pangocontext--set-font-map">pango.Context.set_font_map</link>.</para>
+
+      <para>If you are using Pango as part of a higher-level system, that system may have
+        it's own way of create a <link linkend="class-pangocontext">pango.Context</link>.
+        For instance, the GTK+ toolkit has, among others,
+        <link linkend="function-gdk--pango-context-get-for-screen">gtk.gdk.pango_context_get_for_screen</link>
+        and <link linkend="method-gtkwidget--get-pango-context">gtk.Widget.get_pango_context</link>.
+        Use those instead.
+      </para>
+    </refsect2>
+
     <refsect2 id="method-pangofontmap--load-font">
       <title>pango.FontMap.load_font</title>
 
diff --git a/pango.defs b/pango.defs
index d90f4e17..6935c964 100644
--- a/pango.defs
+++ b/pango.defs
@@ -1473,6 +1473,13 @@
   (return-type "const-char*")
 )
 
+(define-method create_context
+  (of-object "PangoFontMap")
+  (c-name "pango_font_map_create_context")
+  (return-type "PangoContext*")
+  (caller-owns-return #t)
+)
+
 (define-virtual load_font
   (of-object "PangoFontMap")
   (return-type "PangoFont*")
diff --git a/pango.override b/pango.override
index dcb86cf8..afe43aba 100644
--- a/pango.override
+++ b/pango.override
@@ -540,7 +540,6 @@ ignore
   pango_layout_get_log_attrs
 %%
 ignore
-  pango_context_set_font_map
   pango_glyph_string_index_to_x
   pango_glyph_string_x_to_index
   pango_break
@@ -2066,11 +2065,3 @@ _wrap_pango_language_tp_str(PyObject *self)
 {
     return _wrap_pango_language_to_string(self);
 }
-%%
-override pango_context_new kwargs
-static int
-_wrap_pango_context_new(PyObject *self, PyObject *args, PyObject *kwargs)
-{
-    PyErr_SetString(PyExc_TypeError, "pango.Context cannot be instantiated directly");
-    return -1;
-}