source: x/lib/gtk+2.xml@ b04a049

<?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        "7fdcb407dd174010a695b555bf9b65e2">
  <!ENTITY gtk2-size          "12.6 MB">
  <!ENTITY gtk2-buildsize     "350 MB">
  <!ENTITY gtk2-time          "3.5 SBU">
]>

<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-gtk2">gtk2</primary>
  </indexterm>

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

    <para>
      The <application>Gtk+-2</application> package contains
      <application>|Gtk+-2</application> libraries. These are useful for
      creating graphical user interfaces for applications.
    </para>

    &lfs71_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="cairo"/> (compiled with libX11 support),
      <xref linkend="gdk-pixbuf"/>,
      the <xref linkend="x-window-system"/> (specifically, libX11, libXext and
      libXrender),
      <xref linkend="pango"/> and
      <xref linkend="atk"/>
    </para>

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

    <!-- hicolor-icon-theme is required for the test suite -->

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="cups"/>,
      <xref linkend="docbook-utils"/>,
      <!-- <ulink url="http://beagle-project.org/Main_Page">libbeagle</ulink>,
      This beagle page appears to be just adverts -->
      <!-- <ulink url="http://sourceforge.net/projects/openprinting/">papi</ulink>,
      I think papi is just for solaris. It was a bugger to compile... -->
      <!-- <ulink url="http://www.tracker-project.org/">Tracker</ulink>
      This tracker page is a dead link -->
      <xref linkend="gobject-introspection"/> and
      <xref linkend="gtk-doc"/>.
    </para>

    <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 -i 's#l \(gtk-.*\).sgml#&amp; -o \1#' docs/{faq,tutorial}/Makefile.in &amp;&amp;
sed -i 's#.*@man_#man_#' docs/reference/gtk/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 SBUs
    </para>

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

<screen role="root"><userinput>make install                                                     &amp;&amp;
mkdir -pv /usr/share/doc/gtk+-&gtk2-version;                            &amp;&amp;
cp -v -R docs/faq/html      /usr/share/doc/gtk+-&gtk2-version;/faq      &amp;&amp;
cp -v -R docs/tutorial/html /usr/share/doc/gtk+-&gtk2-version;/tutorial &amp;&amp;
install -v -m644 docs/*.txt /usr/share/doc/gtk+-&gtk2-version;</userinput></screen>

    <note>
      <para>
        If you installed the package on to your system using a
        <quote>DESTDIR</quote> method two important files were not installed and
        must be copied and/or generated. Generate them using the following
        commands as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>gdk-pixbuf-query-loaders > /etc/gtk-2.0/gdk-pixbuf.loaders &amp;&amp;
gtk-query-immodules-2.0  > /etc/gtk-2.0/gtk.immodules</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 db2html) then it will try to use it to rebuild some of it's html
      documentation and fail due to bugs in some of the Makefiles. This sed
      fixes the Makefiles.
    </para>

    <para>
      <command>sed -i 's#.*@man_#man_#'
      docs/reference/gtk/Makefile.in</command>: this sed fixes one of the
      <filename>Makefile</filename>s so it installs the man pages for
      gtk-builder-convert, gtk-query-immodules-2.0 and gtk-update-icon-cache.
    </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> and
        <filename>/etc/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-path-gtkrc">/etc/gtk-2.0/gtkrc</primary>
      </indexterm>
    </sect3>

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

      <para>
        Gtk themes change the way a gtk application looks. A Gtk icon theme can
        be used to change the icons that appear on the application's toolbar.
        If you have installed a Gtk theme (such as
        <ulink
        url="http://ftp.gnome.org/pub/gnome/sources/gnome-themes/2.32/">gnome-themes</ulink>
        (requires <xref linkend="gtk-engines"/>)) or a Gtk icon theme (such as
        <xref linkend="gnome-icon-theme"/>) you can set your preferences in
        <filename>~/.gtkrc-2.0</filename>:
      </para>

<screen><userinput>cat &gt; ~/.gtkrc-2.0 &lt;&lt; "EOF"
include "/usr/share/themes/<replaceable>Glider</replaceable>/gtk-2.0/gtkrc"
gtk-icon-theme-name = "<replaceable>hicolor</replaceable>"
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"
include "/usr/share/themes/<replaceable>Clearlooks</replaceable>/gtk-2.0/gtkrc"
gtk-icon-theme-name = "<replaceable>elementary</replaceable>"
EOF</userinput></screen>

      <para>
        <ulink url="http://sourceforge.net/projects/lxde/files/LXAppearance/">
        LXAppearance</ulink> 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>
          libpixmap.so, im-am-et.so, im-cedilla.so, im-cyrillic-translit.so,
          im-inuktitut.so, im-ipa.so, im-multipress.so, im-thai.so, im-ti-er.so,
          im-ti-et.so, im-viqr.so, im-xim.so, libprintbackend-cups.so
          libprintbackend-file.so, libprintbackend-lpr.so,
          libferret.so, libgail.so, libgailutil.so, libgdk-x11-2.0.so and
          libgtk-x11-2.0.so
        </seg>
        <seg>
          /etc/gtk-2.0, /usr/include/gail-1.0, /usr/include/gtk-2.0,
          /usr/include/gtk-unix-print-2.0, /usr/lib/gtk-2.0,
          /usr/share/doc/gtk+-&gtk2-version;,
          /usr/share/gtk-doc/html/gail-libgail-util,
          /usr/share/gtk-doc/html/gdk-pixbuf, /usr/share/gtk-doc/html/gtk,
          /usr/share/themes/Default, /usr/share/themes/Emacs and
          /usr/share/themes/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.
          </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="gtk2libs">
        <term>Gtk+-2 Libraries</term>
        <listitem>
          <para>
            provide an API to implement graphical user interfaces.
          </para>
          <indexterm zone="gtk2 gtk2libs">
            <primary sortas="c-gtk2libs">Gtk+-2 Libraries</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>
</sect1>