source: x/lib/gtk+2.xml@ 193af65e

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY gtk2-download-http "&gnome-download-http;/gtk+/2.24/gtk+-&gtk2-version;.tar.xz">
  <!ENTITY gtk2-download-ftp  "&gnome-download-ftp;/gtk+/2.24/gtk+-&gtk2-version;.tar.xz">
  <!ENTITY gtk2-md5sum        "d5742aa42275203a499b59b4c382a784">
  <!ENTITY gtk2-size          "12 MB">
  <!ENTITY gtk2-buildsize     "275 MB">
  <!ENTITY gtk2-time          "1.0 SBU (using parallelism=4; add 0.1 SBU for tests)">
]>

<sect1 id="gtk2" xreflabel="GTK+-&gtk2-version;">
  <?dbhtml filename="gtk2.html" ?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>GTK+-&gtk2-version;</title>

  <indexterm zone="gtk2">
    <primary sortas="a-GTK+2">GTK+2</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to GTK+ 2</title>

    <para>
      The <application>GTK+ 2</application> package contains
      libraries used for creating graphical user interfaces
      for applications.
    </para>

    &lfs10_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&gtk2-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&gtk2-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &gtk2-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &gtk2-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &gtk2-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &gtk2-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">GTK+ 2 Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="atk"/>,
      <xref linkend="gdk-pixbuf"/> and
      <xref linkend="pango"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="hicolor-icon-theme"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="cups"/>,
      <xref linkend="docbook-utils"/>,
      <xref role="runtime" linkend="gnome-themes-extra"/> (runtime, for
      Adwaita and HighContrast themes),
      <xref linkend="gobject-introspection"/> and
      <xref linkend="gtk-doc"/>
    </para>

    <note>
      <para>
        If <xref linkend="gobject-introspection"/> was installed after
        <xref linkend="atk"/>, <xref linkend="gdk-pixbuf"/>, and/or <xref
        linkend="pango"/>, those packages will have to be rebuilt before this
        package can be built.
      </para>
    </note>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/gtk+2"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of GTK+ 2</title>

    <para>
      Install <application>GTK+ 2</application> by running the following
      commands:
    </para>

<screen><userinput>sed -e 's#l \(gtk-.*\).sgml#&amp; -o \1#' \
    -i docs/{faq,tutorial}/Makefile.in      &amp;&amp;

./configure --prefix=/usr --sysconfdir=/etc &amp;&amp;

make</userinput></screen>

    <para>
      To test the results, issue: <command>make check</command>. Note that you
      must run the tests from a session with X Window Display capability (i.e.,
      not a text-based terminal/console) as the tests attempt to open an X
      window, and the tests can take an excessively long time. Using an X
      Window, the tests should take less than 0.3 SBU. One test, 
      DefaultValues/GdkPixbuf, is known to fail.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

    <note>
      <para>
        If you installed the package on to your system using a
        <quote>DESTDIR</quote> method, an important file was not installed and
        must be copied and/or generated. Generate it using the following
        command as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>gtk-query-immodules-2.0 --update-cache</userinput></screen>
    </note>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed -i 's#l \(gtk-.*\).sgml#&amp; -o \1#'
      docs/{faq,tutorial}/Makefile.in</command>: If you have
      <xref linkend="docbook-utils"/> installed (specifically, if configure
      finds <command>db2html</command>) then it will try to use it to rebuild
      some of its HTML documentation and fail due to bugs in some of the
      <filename>Makefile</filename>s. This <command>sed</command> fixes the
      <filename>Makefile</filename>s.
    </para>
    <!-- This still seems to have problems with docbook-utils installed.
         However, since it's already been tagged, I'll leave it alone. -->
<!--
    <para>
      <command>sed -i -e 's#pltcheck.sh#$(NULL)#g' gtk/Makefile.in</command>:
      This <command>sed</command> disables one test known to fail.
      Not necessary, if not running the tests.
    </para>-->

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/gtk-doc-rebuild.xml"/>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring GTK+ 2</title>

    <sect3 id="gtk2-config">
      <title>Config Files</title>
      <para>
        <filename>~/.gtkrc-2.0</filename>,
        <filename>/etc/gtk-2.0/gtkrc</filename>, and
        <filename>/usr/share/gtk-2.0/gtkrc</filename>
      </para>

      <indexterm zone="gtk2 gtk2-config">
        <primary sortas="e-AA.gtkrc-2.0">~/.gtkrc-2.0</primary>
      </indexterm>

      <indexterm zone="gtk2 gtk2-config">
        <primary sortas="e-etc-gtk-2.0-gtkrc">/etc/gtk-2.0/gtkrc</primary>
      </indexterm>

      <indexterm zone="gtk2 gtk2-config">
        <primary sortas="e-usr-share-gtk-2.0-gtkrc">/usr/share/gtk-2.0/gtkrc</primary>
      </indexterm>
    </sect3>

    <sect3><title>Configuration Information</title>

      <para>
        <application>GTK+ 2</application> themes change the way a
        <application>GTK+ 2</application> application looks. A
        <application>GTK+ 2</application> icon theme can be used to change the
        icons that appear on the application's toolbar. If you have installed a
        <application>GTK+ 2</application> theme (such as
        <xref linkend="gnome-themes-extra"/> or
        <xref linkend="gtk-engines"/>), a
        <application>GTK+</application> icon theme (such as <xref
        linkend="adwaita-icon-theme"/>) you can set your preferences in
        <filename>~/.gtkrc-2.0</filename>:
      </para>

<screen><userinput>cat &gt; ~/.gtkrc-2.0 &lt;&lt; "EOF"
<literal>include "/usr/share/themes/<replaceable>Glider</replaceable>/gtk-2.0/gtkrc"
gtk-icon-theme-name = "<replaceable>hicolor</replaceable>"</literal>
EOF</userinput></screen>

      <para>
        There are many more themes available at
        <ulink url="http://gnome-look.org/">Gnome-Look.org</ulink> and other
        places.
      </para>

      <para>
        Once you've settled on themes you like, you can (as the
        <systemitem class="username">root</systemitem> user) make them the
        default system wide:
      </para>

<screen role="root"><userinput>cat &gt; /etc/gtk-2.0/gtkrc &lt;&lt; "EOF"
<literal>include "/usr/share/themes/<replaceable>Clearlooks</replaceable>/gtk-2.0/gtkrc"
gtk-icon-theme-name = "<replaceable>elementary</replaceable>"</literal>
EOF</userinput></screen>

      <para>
        <xref linkend="lxappearance"/> is a <application>GTK+ 2</application>
        application that can help you choose the themes you like.
      </para>
    </sect3>
  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          gtk-builder-convert, gtk-demo, gtk-query-immodules-2.0, and
          gtk-update-icon-cache
        </seg>
        <seg>
          libgailutil.so, libgdk-x11-2.0.so, and libgtk-x11-2.0.so
        </seg>
        <seg>
          /etc/gtk-2.0,
          /usr/include/{gail-1.0,gtk-2.0,gtk-unix-print-2.0},
          /usr/lib/gtk-2.0,
          /usr/share/doc/gtk+-&gtk2-version;,
          /usr/share/gtk-2.0,
          /usr/share/gtk-doc/html/{gail-libgail-util,gdk2,gtk2}, and
          /usr/share/themes/{Default,Emacs,Raleigh}
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="gtk-builder-convert">
        <term><command>gtk-builder-convert</command></term>
        <listitem>
          <para>
           converts glade files into XML files which can be loaded with
           GtkBuilder.
          </para>
          <indexterm zone="gtk2 gtk-builder-convert">
            <primary
            sortas="b-gtk-builder-convert">gtk-builder-convert</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-demo">
        <term><command>gtk-demo</command></term>
        <listitem>
          <para>
            demonstrates <application>GTK+ 2</application> functionality and
            provides code for the examples.
          </para>
          <indexterm zone="gtk2 gtk-demo">
            <primary
            sortas="b-gtk-demo">gtk-demo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-query-immodules-2.0">
        <term><command>gtk-query-immodules-2.0</command></term>
        <listitem>
          <para>
            collects information about loadable input method modules for
            <application>GTK+ 2</application> and writes it to standard output.
          </para>
          <indexterm zone="gtk2 gtk-query-immodules-2.0">
            <primary
            sortas="b-gtk-query-immodules-2.0">gtk-query-immodules-2.0</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-update-icon-cache">
        <term><command>gtk-update-icon-cache</command></term>
        <listitem>
          <para>
            creates mmap()able cache files for icon themes. Starting with
            <application>gtk+-2.24.24</application>, add the flag
            <quote>--include-image-data</quote> to this command, if you wish
            previous behavior, with image data in the cache.
          </para>
          <indexterm zone="gtk2 gtk-update-icon-cache">
            <primary sortas="b-gtk-update-icon-cache">gtk-update-icon-cache</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgdk-x11-2">
        <term><filename class="libraryfile">libgdk-x11-2.0.so</filename></term>
        <listitem>
          <para>
            contains functions that act as a wrapper around the low-level
            drawing and windowing functions provided by the underlying graphics
            system.
          </para>
          <indexterm zone="gtk2 libgdk-x11-2">
            <primary sortas="c-libgdk-x11-2">libgdk-x11-2.0.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgtk-x11-2">
        <term><filename class="libraryfile">libgtk-x11-2.0.so</filename></term>
        <listitem>
          <para>
            contains functions that provide an API to implement graphical user
            interfaces.
          </para>
          <indexterm zone="gtk2 libgtk-x11-2">
            <primary sortas="c-libgtk-x11-2">libgtk-x11-2.0.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>