path: root/docs/reference/pygtk-gtkfontselection.xml

<?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>
      
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-face">get_face</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-face-list">get_face_list</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-family">get_family</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-family-list">get_family_list</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-preview-entry">get_preview_entry</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-size">get_size</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-size-entry">get_size_entry</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselection--get-size-list">get_size_list</link></methodname>
	<methodparam></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>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkfontselection">
    <title>gtk.FontSelection Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
    <para><link linkend="properties-gtkbox">gtk.Box Properties</link></para>

    <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"</entry>
              <entry>Read</entry>
              <entry>The gtk.gdk.Font that is
              currently selected. This property is deprecated.</entry>
            </row>

            <row valign="top">
              <entry>"font-name"</entry>
              <entry>Read/Write</entry>
              <entry>The string that names the font</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 id="style-properties-gtkfontselection">
    <title>gtk.FontSelection Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

  </refsect1>

  <refsect1 id="child-properties-gtkfontselection">
    <title>gtk.FontSelection Child Properties</title>

    <para><link linkend="child-properties-gtkbox">gtk.Box Child Properties</link></para>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkfontselection">
    <title>gtk.FontSelection Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
  </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>

    <refsect2 id="method-gtkfontselection--get-face">
      <title>gtk.FontSelection.get_face</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_face</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A <link linkend="class-pangofontface"><classname>pango.FontFace</classname></link>
	  representing the selected font group details.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_face</methodname>() method gets the
	<link linkend="class-pangofontface"><classname>pango.FontFace</classname></link>
	representing the selected font group details (i.e. family, slant, weight, width, etc).
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselection--get-face-list">
      <title>gtk.FontSelection.get_face_list</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_face_list</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A
	  <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
	  that is part of fontsel.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_face_list</methodname>() method returns the
	<link linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
	which lists all styles available for the selected font. For example, 'Regular', 'Bold', etc.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselection--get-family">
      <title>gtk.FontSelection.get_family</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_family</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A <link linkend="class-pangofontselection"><classname>pango.FontSelection</classname></link>
	  representing the selected font family. Font families are a collection of font faces.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_family</methodname>() method gets the
	<link linkend="class-pangofontselection"><classname>pango.FontSelection</classname></link>
	representing the selected font family.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselection--get-family-list">
      <title>gtk.FontSelection.get_family_list</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_family_list</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A
	  <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
	  that is part of fontsel.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_family_list</methodname>() method returns the
	<link linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
	that lists font families, for example, 'Sans', 'Serif', etc.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselection--get-preview-entry">
      <title>gtk.FontSelection.get_preview_entry</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_preview_entry</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A
	  <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
	  that is part of fontsel.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_preview_entry</methodname>() method returns the
	<link linkend="class-gtkentry"><classname>gtk.Entry</classname></link>
	used to display the font as a preview.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselection--get-size">
      <title>gtk.FontSelection.get_size</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A n integer representing the selected font size,
	  or -1 if no font size is selected. </simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_size</methodname>() method returns the selected font size.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselection--get-size-entry">
      <title>gtk.FontSelection.get_size_entry</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size_entry</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A
	  <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
	  that is part of fontsel.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_preview_entry</methodname>() method returns the
	<link linkend="class-gtkentry"><classname>gtk.Entry</classname></link>
	used to allow the user to edit the font number manually instead of
	selecting it from the list of font sizes.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselection--get-size-list">
      <title>gtk.FontSelection.get_size_list</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size_list</methodname>
	  <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A
	  <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
	  that is part of fontsel.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_size_list</methodname>() method returns the
	<link linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
	used to list font sizes.
      </para>

    </refsect2>

  </refsect1>

</refentry>