pango-version.xml

GTK+-2.0源码之pango-1.15.6.tar.gz

<refentry id="pango-Version-Checking">
<refmeta>
<refentrytitle id="top_of_page">Version Checking</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>PANGO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Version Checking</refname>
<refpurpose>Tools for checking Pango version at compile- and run-time.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="synopsis">
<title id="synopsis.title">Synopsis</title>

<synopsis>



#define     <link linkend="PANGO-VERSION-ENCODE:CAPS">PANGO_VERSION_ENCODE</link>            (major, minor, micro)
#define     <link linkend="PANGO-VERSION:CAPS">PANGO_VERSION</link>
#define     <link linkend="PANGO-VERSION-MAJOR:CAPS">PANGO_VERSION_MAJOR</link>
#define     <link linkend="PANGO-VERSION-MINOR:CAPS">PANGO_VERSION_MINOR</link>
#define     <link linkend="PANGO-VERSION-MICRO:CAPS">PANGO_VERSION_MICRO</link>
#define     <link linkend="PANGO-VERSION-STRING:CAPS">PANGO_VERSION_STRING</link>
#define     <link linkend="PANGO-VERSION-CHECK:CAPS">PANGO_VERSION_CHECK</link>             (major,minor,micro)
<link linkend="int">int</link>         <link linkend="pango-version">pango_version</link>                   (void);
const <link linkend="char">char</link>* <link linkend="pango-version-string">pango_version_string</link>            (void);
const <link linkend="char">char</link>* <link linkend="pango-version-check">pango_version_check</link>             (<link linkend="int">int</link> required_major,
                                             <link linkend="int">int</link> required_minor,
                                             <link linkend="int">int</link> required_micro);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>
The capital-letter macros defined here can be used to check the version of
Pango at compile-time, and to <firstterm>encode</firstterm> Pango versions into
integers.

The functions can be used to check the version of the linked Pango library
at run-time.
</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="PANGO-VERSION-ENCODE:CAPS" role="macro"/>PANGO_VERSION_ENCODE()</title>
<indexterm><primary>PANGO_VERSION_ENCODE</primary></indexterm><programlisting>#define     PANGO_VERSION_ENCODE(major, minor, micro)</programlisting>
<para>
This macro encodes the given Pango version into an integer.  The numbers
returned by <link linkend="PANGO-VERSION:CAPS"><literal>PANGO_VERSION</literal></link> and <link linkend="pango-version"><function>pango_version()</function></link> are encoded using this macro.
Two encoded version numbers can be compared as integers.
</para><variablelist role="params">
<varlistentry><term><parameter>major</parameter>&nbsp;:</term>
<listitem><simpara>the major component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>minor</parameter>&nbsp;:</term>
<listitem><simpara>the minor component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>micro</parameter>&nbsp;:</term>
<listitem><simpara>the micro component of the version number


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION:CAPS" role="macro"/>PANGO_VERSION</title>
<indexterm><primary>PANGO_VERSION</primary></indexterm><programlisting>#define     PANGO_VERSION</programlisting>
<para>
The version of Pango available at compile-time, encoded using
<link linkend="PANGO-VERSION-ENCODE:CAPS"><function>PANGO_VERSION_ENCODE()</function></link>.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-MAJOR:CAPS" role="macro"/>PANGO_VERSION_MAJOR</title>
<indexterm><primary>PANGO_VERSION_MAJOR</primary></indexterm><programlisting>#define PANGO_VERSION_MAJOR 1
</programlisting>
<para>
The major component of the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-MINOR:CAPS" role="macro"/>PANGO_VERSION_MINOR</title>
<indexterm><primary>PANGO_VERSION_MINOR</primary></indexterm><programlisting>#define PANGO_VERSION_MINOR 15
</programlisting>
<para>
The minor component of the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-MICRO:CAPS" role="macro"/>PANGO_VERSION_MICRO</title>
<indexterm><primary>PANGO_VERSION_MICRO</primary></indexterm><programlisting>#define PANGO_VERSION_MICRO 5
</programlisting>
<para>
The micro component of the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-STRING:CAPS" role="macro"/>PANGO_VERSION_STRING</title>
<indexterm><primary>PANGO_VERSION_STRING</primary></indexterm><programlisting>#define PANGO_VERSION_STRING "1.15.5"
</programlisting>
<para>
A string literal containing the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-CHECK:CAPS" role="macro"/>PANGO_VERSION_CHECK()</title>
<indexterm><primary>PANGO_VERSION_CHECK</primary></indexterm><programlisting>#define     PANGO_VERSION_CHECK(major,minor,micro)</programlisting>
<para>
Checks that the version of Pango available at compile-time is not older than
the provided version number.
</para><variablelist role="params">
<varlistentry><term><parameter>major</parameter>&nbsp;:</term>
<listitem><simpara>the major component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>minor</parameter>&nbsp;:</term>
<listitem><simpara>the minor component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>micro</parameter>&nbsp;:</term>
<listitem><simpara>the micro component of the version number


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-version" role="function" condition="since:1.16"/>pango_version ()</title>
<indexterm role="1.16"><primary>pango_version</primary></indexterm><programlisting><link linkend="int">int</link>         pango_version                   (void);</programlisting>
<para>
This is similar to the macro <link linkend="PANGO-VERSION:CAPS"><literal>PANGO_VERSION</literal></link> except that
it returns the encoded version of Pango available at run-time,
as opposed to the version available at compile-time.
</para>
<para>
A version number can be encoded into an integer using
<link linkend="PANGO-VERSION-ENCODE:CAPS"><function>PANGO_VERSION_ENCODE()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>value: The encoded version of Pango library
  available at run time.

</simpara></listitem></varlistentry>
</variablelist><para>Since  1.16
</para></refsect2>
<refsect2>
<title><anchor id="pango-version-string" role="function" condition="since:1.16"/>pango_version_string ()</title>
<indexterm role="1.16"><primary>pango_version_string</primary></indexterm><programlisting>const <link linkend="char">char</link>* pango_version_string            (void);</programlisting>
<para>
This is similar to the macro <link linkend="PANGO-VERSION-STRING:CAPS"><literal>PANGO_VERSION_STRING</literal></link> except that
it returns the version of Pango available at run-time, as opposed to
the version available at compile-time.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>value: A string containing the version of Pango library
  available at run time.
  The returned string is owned by Pango and should not be modified
  or freed.

</simpara></listitem></varlistentry>
</variablelist><para>Since  1.16
</para></refsect2>
<refsect2>
<title><anchor id="pango-version-check" role="function" condition="since:1.16"/>pango_version_check ()</title>
<indexterm role="1.16"><primary>pango_version_check</primary></indexterm><programlisting>const <link linkend="char">char</link>* pango_version_check             (<link linkend="int">int</link> required_major,
                                             <link linkend="int">int</link> required_minor,
                                             <link linkend="int">int</link> required_micro);</programlisting>
<para>
Checks that the Pango library in use is compatible with the
given version. Generally you would pass in the constants
<link linkend="PANGO-VERSION-MAJOR:CAPS"><literal>PANGO_VERSION_MAJOR</literal></link>, <link linkend="PANGO-VERSION-MINOR:CAPS"><literal>PANGO_VERSION_MINOR</literal></link>, <link linkend="PANGO-VERSION-MICRO:CAPS"><literal>PANGO_VERSION_MICRO</literal></link>
as the three arguments to this function; that produces
a check that the library in use at run-time is compatible with
the version of Pango the application or module was compiled against.
</para>
<para>
Compatibility is defined by two things: first the version
of the running library is newer than the version
<parameter>required_major.required_minor</parameter>.<parameter>required_micro</parameter>. Second
the running library must be binary compatible with the
version <parameter>required_major.required_minor</parameter>.<parameter>required_micro</parameter>
(same major version.)
</para>
<para>
For compile-time version checking use <link linkend="PANGO-VERSION-CHECK:CAPS"><function>PANGO_VERSION_CHECK()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>required_major</parameter>&nbsp;:</term>
<listitem><simpara> the required major version.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>required_minor</parameter>&nbsp;:</term>
<listitem><simpara> the required minor version.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>required_micro</parameter>&nbsp;:</term>
<listitem><simpara> the required major version.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the Pango library is compatible with the
  given version, or a string describing the version mismatch.
  The returned string is owned by Pango and should not be modified
  or freed.

</simpara></listitem></varlistentry>
</variablelist><para>Since  1.16
</para></refsect2>

</refsect1>




</refentry>