<?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-pangolanguage">
  <refnamediv>
    <refname>pango.Language</refname>
    <refpurpose>an object that represents a language tag.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>pango.Language</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-pangolanguage">pango.Language</link></methodname>
	<methodparam><parameter
		       role="keyword">language</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolanguage--matches">matches</link></methodname>
	<methodparam><parameter
		       role="keyword">range_list</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-pangolanguage--to-string">to_string</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis></classsynopsis>

    <programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
	<methodname><link linkend="function-pango--pango-language-from-string">pango.pango_language_from_string</link></methodname>
	<methodparam><parameter
		       role="keyword">language</parameter></methodparam>
      </methodsynopsis><methodsynopsis language="python">
	<methodname><link linkend="function-pango--pango-language-matches">pango.pango_language_matches</link></methodname>
	<methodparam><parameter role="keyword">language</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">range_list</parameter></methodparam>
      </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
object represents a language tag meeting the RFC-3066 standard. The <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
can be retrieved from a <link
linkend="class-pangocontext"><classname>pango.Context</classname></link> by
using the <link
linkend="method-pangocontext--get-language"><methodname>pango.Context.get_language</methodname>()</link> 
method or created using the <link
linkend="constructor-pangolanguage">pango.Language</link>() constructor.
Example RFC-3066 language tags include: "en-us", "fr", and
"sgn-us-ma".</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>pango.Language</methodname>
	<methodparam><parameter
		       role="keyword">language</parameter>></methodparam>
</constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">language</parameter>&nbsp;:</term>
	<listitem><simpara>a string representing a language
tag</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <note>
      <para>This constructor is available in PyGTK 2.4 and above.</para>
    </note>

    <para>Creates a new <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
object from the RFC-3066 language tag specified by
<parameter>language</parameter>. This constructor first canonicalizes the
string in <parameter>language</parameter> by converting it to lowercase,
mapping '_' to '-', and stripping all characters other than letters and
'-'.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-pangolanguage--matches">
      <title>pango.Language.matches</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>matches</methodname>
	  <methodparam><parameter
			 role="keyword">range_list</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">>range_list</parameter>&nbsp;:</term>
	  <listitem><simpara>a list of language ranges, separated by ';'
characters.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if a match was
found.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>matches</methodname>() method returns
<literal>True</literal> if the language matches one of the language ranges
in the list specified by <parameter>range_list</parameter>.A language tag is
considered to match a range in the list if</para>

      <itemizedlist>
	<listitem>
	  <simpara>the range is '*'</simpara>
	</listitem>
	<listitem>
	  <simpara>the range is exactly the same as the tag, or</simpara>
	</listitem>
	<listitem>
	  <simpara>the range is a prefix of the tag, and the character after
the matching portion of the tag is '-'</simpara>
	</listitem>
      </itemizedlist>

      <para>each range must either be '*', or a canonicalized RFC-3066
language range (see the <link
linkend="constructor-pangolanguage">pango.Language</link>() constructor for
more information).</para>

    </refsect2>

    <refsect2 id="method-pangolanguage--to-string">
      <title>pango.Language.matches</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>to_string</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the string representation of the language
tag</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>to_string</methodname>() method returns a string
representation of the canonicalized language tag. See the <link
linkend="constructor-pangolanguage">pango.Language</link>() constructor for
more information.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-pango--pango-language-from-string">
      <title>pango.pango_language_from_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>pango.pango_language_from_string</methodname>
	  <methodparam><parameter
			 role="keyword">language</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">language</parameter>&nbsp;:</term>
	  <listitem><simpara>a string representing a language
	  tag</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
	  linkend="class-pangolanguage"><classname>pango.Language</classname></link>
	  object</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This function is deprecated in PyGTK 2.4 and above. Use the
<link linkend="constructor-pangolanguage">pango.Language()</link>
constructor instead.</para>
      </note>

      <para>The <function>pango.pango_language_from_string</function>()
function takes a RFC-3066 format language tag as a string (specified by
<parameter>language</parameter>) and converts it to a <link
linkend="class-pangolanguage"><classname>pango.Language</classname></link>
object. This function first canonicalizes the string by converting it to
lowercase, mapping '_' to '-', and stripping all characters other than
letters and '-'.</para>

    </refsect2>

    <refsect2 id="function-pango--pango-language-matches">
      <title>pango.pango_language_matches</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>pango.pango_language_matches</methodname>
	  <methodparam><parameter
			 role="keyword"></parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">language</parameter>&nbsp;:</term>
	  <listitem><simpara> a language tag (see the <link
	  linkend="function-pango--pango-language-from-string"><function>pango.pango_language_from_string</function>()</link>
	  function), <literal>None</literal> is allowed and matches nothing
	  but '*'</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
	  role="keyword">range_list</parameter>&nbsp;:</term>
	  <listitem><simpara> a list of language ranges, separated by ';'
	  characters. each element must either be '*', or a RFC 3066
	  language range canonicalized as by the <link
	  linkend="function-pango--pango-language-from-string"><function>pango.pango_language_from_string</function>()</link>
	  function.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if a match was
	  found.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This function is deprecated in PyGTK 2.4 and above. Use the
<link
linkend="method-pangolanguage--matches"><methodname>matches</methodname>()</link>
method instead.</para>
      </note>

      <para>The <function>pango.pango_language_matches</function>() function
checks if a language tag matches one of the elements in a list of language
ranges. A language tag is considered to match a range in the list if the
range is '*', the range is exactly the tag, or the range is a prefix of the
tag, and the character after the tag is '-'.</para>

    </refsect2>

  </refsect1>

</refentry>
