path: root/docs/reference/pygtk-gtkfontselectiondialog.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-gtkfontselectiondialog">
  <refnamediv>
    <refname>gtk.FontSelectionDialog</refname>
    <refpurpose>a dialog for selecting fonts.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.FontSelectionDialog</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkdialog">gtk.Dialog</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkfontselectiondialog">gtk.FontSelectionDialog</link></methodname>
	<methodparam><parameter
		       role="keyword">title</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkfontselectiondialog--get-font-selection">get_font_selection</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfontselectiondialog--get-font-name">get_font_name</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfontselectiondialog--set-font-name">set_font_name</link></methodname>
	<methodparam><parameter
		       role="keyword">fontname</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfontselectiondialog--get-preview-text">get_preview_text</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkfontselectiondialog--set-preview-text">set_preview_text</link></methodname>
	<methodparam><parameter
		       role="keyword">text</parameter></methodparam>
      </methodsynopsis>
      
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselectiondialog--get-apply-button">get_apply_button</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselectiondialog--get-cancel-button">get_cancel_button</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkfontselectiondialog--get-ok-button">get_ok_button</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-gtkbin">gtk.Bin</link>
          +-- <link linkend="class-gtkwindow">gtk.Window</link>
            +-- <link linkend="class-gtkdialog">gtk.Dialog</link>
              +-- <link linkend="class-gtkfontselectiondialog">gtk.FontSelectionDialog</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkfontselectiondialog"><classname>gtk.FontSelectionDialog</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkfontselectiondialog">
    <title>gtk.FontSelectionDialog 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-gtkwindow">gtk.Window Properties</link></para>
    <para><link linkend="properties-gtkdialog">gtk.Dialog Properties</link></para>

  </refsect1>

  <refsect1 id="style-properties-gtkfontselectiondialog">
    <title>gtk.FontSelectionDialog Style Properties</title>

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

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	<?dbhtml cellpadding="5"?>
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"fontsel"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link> 
widget in the dialog.</entry>
	    </row>

	    <row valign="top">
	      <entry>"main_vbox"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkvbox"><classname>gtk.VBox</classname></link> that contains
all the dialog widgets</entry>
	    </row>

	    <row valign="top">
	      <entry>"action_area"</entry>
	      <entry>Read</entry>
	      <entry>The <link
linkend="class-gtkhbox"><classname>gtk.HBox</classname></link> containing
the action buttons</entry>
	    </row>

	    <row valign="top">
	      <entry>"ok_button"</entry>
	      <entry>Read</entry>
	      <entry>The <guibutton>OK</guibutton> button</entry>
	    </row>

	    <row valign="top">
	      <entry>"apply_button"</entry>
	      <entry>Read</entry>
	      <entry>The <guibutton>Apply</guibutton> button</entry>
	    </row>

	    <row valign="top">
	      <entry>"cancel_button"</entry>
	      <entry>Read</entry>
	      <entry>The <guibutton>Cancel</guibutton> button</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkfontselectiondialog">
    <title>gtk.FontSelectionDialog 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>
    <para><link linkend="signal-prototypes-gtkwindow">gtk.Window Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkdialog">gtk.Dialog Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkfontselectiondialog"><classname>gtk.FontSelectionDialog</classname></link> 
is a dialog box containing a <link
linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link> 
widget that the user can use to select a font according to the desired
family, style and size.</para>

    <para>The <link
linkend="method-gtkfontselectiondialog--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-gtkfontselectiondialog--get-font-name"><methodname>get_font_name</methodname>()</link> 
method. The font selection dialog 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-gtkfontselectiondialog--get-preview-text"><methodname>get_preview_text</methodname>()</link> 
method and set with the <link
linkend="method-gtkfontselectiondialog--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-gtkfontselectiondialog"><classname>gtk.FontSelectionDialog</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>

    <note>
      <para>In GTK+ 2.2 and above the <link
linkend="class-gtkfontselectiondialog"><classname>gtk.FontSelectionDialog</classname></link>
does not have filters, a <guibutton>Reset Filter</guibutton> button or a
<guilabel>Filter</guilabel> page.</para>
    </note>

  </refsect1>

  <refsect1 id="constructor-gtkfontselectiondialog">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.FontSelectionDialog</methodname>
	<methodparam><parameter
		       role="keyword">title</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">title</parameter>&nbsp;:</term>
	<listitem><simpara>a string to be used as the dialog
title</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new font selection dialog</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkfontselectiondialog"><classname>gtk.FontSelectionDialog</classname></link> 
with the title specified by <parameter>title</parameter>.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkfontselectiondialog--get-font-selection">
      <title>gtk.FontSelectionDialog.get_font_selection</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_font_selection</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the embedded <link linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link>.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_font_selection</methodname>() method retrieves the
      <link linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link>
      widget embedded in the dialog. </para>

    </refsect2>

    <refsect2 id="method-gtkfontselectiondialog--get-font-name">
      <title>gtk.FontSelectionDialog.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>the currently selected font name or None if no
font is selected.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_font_name</methodname>() method returns a
string containing the currently selected font name or None if no font name
is selected.</para>

    </refsect2>

    <refsect2 id="method-gtkfontselectiondialog--set-font-name">
      <title>gtk.FontSelectionDialog.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 font name to be
set</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the font is found
and can be selected</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_font_name</methodname>() method sets the
current font using the value of <parameter>fontname</parameter>. The method
returns <literal>True</literal> if the font exists and could be
selected.</para>

    </refsect2>

    <refsect2 id="method-gtkfontselectiondialog--get-preview-text">
      <title>gtk.FontSelectionDialog.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 text in the preview
area entry</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_preview_text</methodname>() method returns a
string containing the text in the preview area entry.</para>

    </refsect2>

    <refsect2 id="method-gtkfontselectiondialog--set-preview-text">
      <title>gtk.FontSelectionDialog.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>a string used to set the text in the preview
area entry</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_preview_text</methodname>() method sets the
text in the preview area entry using the string specified by
<parameter>text</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkfontselectiondialog--get-apply-button">
      <title>gtk.FontSelectionDialog.get_apply_button</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_apply_button</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>.
	  </simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.14 and above but it will be deprecated in 2.16
	don't use this method.</para>
      </note>

      <para>
	The <methodname>get_apply_button</methodname>() method obtains a button.
	The button doesn't have any function.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselectiondialog--get-cancel-button">
      <title>gtk.FontSelectionDialog.get_cancel_button</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_cancel_button</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>.
	  used in the dialog for the 'Cancel' button.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_cancel_button</methodname>() method gets the 'Cancel' button.
      </para>

    </refsect2>

    <refsect2 id="method-gtkfontselectiondialog--get-ok-button">
      <title>gtk.FontSelectionDialog.get_ok_button</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_ok_button</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>.
	  used in the dialog for the 'OK' button.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_ok_button</methodname>() method gets the 'OK' button.
      </para>

    </refsect2>

  </refsect1>

</refentry>