Initial revision

1 files changed, 249 insertions, 0 deletions

diff --git a/docs/reference/pygtk-gtkfontselection.xml b/docs/reference/pygtk-gtkfontselection.xml
new file mode 100644
index 00000000..cbbb0a7e
--- /dev/null
+++ b/docs/reference/pygtk-gtkfontselection.xml
@@ -0,0 +1,249 @@
+<?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-gtkfontselection">
+  <refnamediv>
+    <refname>gtk.FontSelection</refname>
+    <refpurpose>a widget for selecting fonts.</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Synopsis</title>
+
+    <classsynopsis language="python">
+      <ooclass><classname>gtk.FontSelection</classname></ooclass>
+      <ooclass><classname><link
+linkend="class-gtkvbox">gtk.VBox</link></classname></ooclass>
+      <constructorsynopsis language="python">
+	<methodname><link
+linkend="constructor-gtkfontselection">gtk.FontSelection</link></methodname>
+	<methodparam></methodparam>  </constructorsynopsis>
+      <methodsynopsis language="python">
+	<methodname><link
+linkend="method-gtkfontselection--get-font-name">get_font_name</link></methodname>
+	<methodparam></methodparam>  </methodsynopsis>
+      <methodsynopsis language="python">
+	<methodname><link
+linkend="method-gtkfontselection--set-font-name">set_font_name</link></methodname>
+	<methodparam><parameter
+		       role="keyword">fontname</parameter></methodparam>
+      </methodsynopsis>
+      <methodsynopsis language="python">
+	<methodname><link
+linkend="method-gtkfontselection--get-preview-text">get_preview_text</link></methodname>
+	<methodparam></methodparam>  </methodsynopsis>
+      <methodsynopsis language="python">
+	<methodname><link
+linkend="method-gtkfontselection--set-preview-text">set_preview_text</link></methodname>
+	<methodparam><parameter
+		       role="keyword">text</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-gtkcontainer">gtk.Container</link>
+        +-- <link linkend="class-gtkbox">gtk.Box</link>
+          +-- <link linkend="class-gtkvbox">gtk.VBox</link>
+            +-- <link linkend="class-gtkfontselection">gtk.FontSelection</link>
+</synopsis>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Properties</title>
+
+    <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>"font-name"</entry>
+	      <entry>Read/Write</entry>
+	<entry>The string that names the font</entry>
+	  </row>
+
+	<row valign="top">
+	  <entry>"font"</entry>
+	  <entry>Read</entry>
+	  <entry>The gtk.gdk.Font that is
+currently selected. This property is deprecated.</entry>
+	</row>
+
+	<row valign="top">
+	  <entry>"preview-text"</entry>
+	  <entry>Read/Write</entry>
+	  <entry>The text to display in order to demonstrate the selected
+font.
+</entry>
+	</row>
+
+	</tbody>
+      </tgroup>
+      </informaltable>
+    </blockquote>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <link
+linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link> 
+widget lists the available fonts, styles and sizes, allowing the user to
+select a font. It is used in the <link
+linkend="class-gtkfontselectiondialog"><classname>gtk.FontSelectionDialog</classname></link> 
+widget to provide a dialog box for selecting fonts. The <link
+linkend="method-gtkfontselection--set-font-name"><methodname>set_font_name</methodname>()</link> 
+method sets the initial font selection. The current font selection is
+retrieved using the <link
+linkend="method-gtkfontselection--get-font-name"><methodname>get_font_name</methodname>()</link> 
+method.</para>
+
+    <para>The fontselection has a preview area that contains a <link
+linkend="class-gtkentry"><classname>gtk.Entry</classname></link> that
+displays text using the currently selected font. The preview text can be
+retrieved with the <link
+linkend="method-gtkfontselection--get-preview-text"><methodname>get_preview_text</methodname>()</link> 
+method and set with the <link
+linkend="method-gtkfontselection--set-preview-text"><methodname>set_preview_text</methodname>()</link> 
+method.</para>
+
+    <para>Filters can be used to limit the font selections. There are 2
+filters in the <link
+linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link> 
+- a base filter and a user filter. The base filter cannot be changed by the
+user, so this can be used when the user must choose from the restricted set
+of fonts (e.g. for a terminal-type application you may want to force the
+user to select a fixed-width font). The user filter can be changed or reset
+by the user, by using the <guibutton>Reset Filter</guibutton> button or
+changing the options on the <guilabel>Filter</guilabel> page of the
+widget.</para>
+
+  </refsect1>
+
+  <refsect1 id="constructor-gtkfontselection">
+    <title>Constructor</title>
+
+    <programlisting><constructorsynopsis language="python">
+	<methodname>gtk.FontSelection</methodname>
+	<methodparam></methodparam>  </constructorsynopsis></programlisting>
+    <variablelist>
+      <varlistentry>
+	<term><emphasis>Returns</emphasis>&nbsp;:</term>
+	<listitem><simpara>a new fontselection widget</simpara></listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Creates a new <link
+linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link> 
+widget.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Methods</title>
+
+    <refsect2 id="method-gtkfontselection--get-font-name">
+      <title>gtk.FontSelection.get_font_name</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>get_font_name</methodname>
+	  <methodparam></methodparam>  </methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>a string containing the selected font
+name</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>get_font_name</methodname>() method returns the
+name of the currently selected font.</para>
+
+    </refsect2>
+
+    <refsect2 id="method-gtkfontselection--set-font-name">
+      <title>gtk.FontSelection.set_font_name</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>set_font_name</methodname>
+	  <methodparam><parameter
+			 role="keyword">fontname</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><parameter role="keyword">fontname</parameter>&nbsp;:</term>
+	  <listitem><simpara>a string containing the name of a
+font</simpara></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara><literal>TRUE</literal> if the font could be
+set</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>set_font_name</methodname>() method sets the
+currently selected font in the fontselection using the value of
+<parameter>fontname</parameter>. The method returns <literal>TRUE</literal>
+if the font is found and can be selected in the fontselection.</para>
+
+    </refsect2>
+
+    <refsect2 id="method-gtkfontselection--get-preview-text">
+      <title>gtk.FontSelection.get_preview_text</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>get_preview_text</methodname>
+	  <methodparam></methodparam>  </methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>a string containing the preview
+text</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>get_preview_text</methodname>() method returns a
+string that contains the text displayed in the preview area entry.</para>
+
+    </refsect2>
+
+    <refsect2 id="method-gtkfontselection--set-preview-text">
+      <title>gtk.FontSelection.set_preview_text</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>set_preview_text</methodname>
+	  <methodparam><parameter
+			 role="keyword">text</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><parameter role="keyword">text</parameter>&nbsp;:</term>
+	  <listitem><simpara>the new preview text
+string</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <methodname>set_preview_text</methodname>() method sets the
+text to be displayed in the preview area entry using the string in
+<parameter>text</parameter>.</para>
+
+    </refsect2>
+
+  </refsect1>
+
+</refentry>