source: x/lib/gtk+3.xml@ cfc1f98

<?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 gtk3-download-http "&gnome-download-http;/gtk+/&gnome-minor-24;/gtk+-&gtk3-version;.tar.xz">
  <!ENTITY gtk3-download-ftp  "&gnome-download-ftp;/gtk+/&gnome-minor-24;/gtk+-&gtk3-version;.tar.xz">
  <!ENTITY gtk3-md5sum        "fb383236280fb272ad5eb819f80ceb17">
  <!ENTITY gtk3-size          "20 MB">
  <!ENTITY gtk3-buildsize     "592 MB (add 9 MB for tests)">
  <!ENTITY gtk3-time          "1.8 SBU (using parallelism=4, add 1.7 SBU for tests)">
]>

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

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

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

  <indexterm zone="gtk3">
    <primary sortas="a-GTK+3">GTK+3</primary>
  </indexterm>

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

    <para>
      The <application>GTK+ 3</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="&gtk3-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&gtk3-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &gtk3-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &gtk3-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &gtk3-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &gtk3-time;
        </para>
      </listitem>
    </itemizedlist>

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

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

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="adwaita-icon-theme"/> (default for some gtk+3 settings
      keys, also needed for tests),
      <xref linkend="hicolor-icon-theme"/> (needed for tests),
      <xref linkend="iso-codes"/>,
      <xref linkend="libxkbcommon"/>,
      <xref linkend="sassc"/>,
      <xref linkend="wayland"/>, and
      <xref linkend="wayland-protocols"/>
    </para>

    <bridgehead renderas="sect4">Recommended (Required if building GNOME)</bridgehead>
    <para role="recommended">
      <xref linkend="gobject-introspection"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="colord"/>,
      <xref linkend="cups"/>, 
      <xref linkend="docbook-utils"/>,
      <xref linkend="gtk-doc"/>,
      <xref linkend="json-glib"/>,
      <xref linkend="pyatspi2"/> (for tests),
      <xref linkend="rest"/>, and
      <ulink url="http://icl.cs.utk.edu/papi/">PAPI</ulink>
    </para>

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

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

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

<!-- There is a meson port available, but upstream's official recommendation
     is to use autotools, and is the only offically supported build system.
     See ticket #13459 for more details.-->

<screen><userinput>./configure --prefix=/usr              \
            --sysconfdir=/etc          \
            --enable-broadway-backend  \
            --enable-x11-backend       \
            --enable-wayland-backend   &amp;&amp;
make</userinput></screen>

    <para>
      Some tests fail if
      <filename>/usr/share/glib-2.0/schemas/gschemas.compiled</filename> is not
      found. If you wish to run the test suite, create (or update) the file
      using the following command as the
      <systemitem class="username">root</systemitem> user:
      <command>glib-compile-schemas /usr/share/glib-2.0/schemas</command>.
    </para>

    <para>
      To test the results you need a graphical session, then issue
      <command>make check</command>. <!--There are several tests that 
      have subtests that are known to fail: scrolledwindow, treeview,
      accessibility-dump, test-css-nodes, and gtk-reftest.
      Additionally many tests will fail if the current 
      gtk theme (such as current XFCE themes) has deprecated elements.
      The accessibility portion of the test suite (7 tests) is known
      to fail.
      [pierre Sep 5th, 2020]: not for me for version 3.24.23, but I have
      other failures: display, and subtests in defaultvalue, objects-finalize,
      window, and gtk-reftest.-->
      Some tests or subtests 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-3.0 --update-cache</userinput></screen>
    </note>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/gsettings-destdir.xml"/>
  </sect2>

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

    <!-- MESON ONLY
    <para>
      <parameter>-Dbroadway_backend=true</parameter>: This switch enables the
      HTML5 GTK backend.
    </para>
    -->

    <para>
      <parameter>--enable-broadway-backend</parameter>: This switch enables the
      HTML5 GTK backend.
    </para>

    <para>
      <parameter>--enable-x11-backend</parameter>: This switch enables the X11 
      GDK backend.
    </para>
    
    <para>
      <parameter>--enable-wayland-backend</parameter>: This switch
      enables the Wayland GDK backend. Replace with
      <option>--disable-wayland-backend</option> if you do not have
      <xref linkend="wayland"/> and <xref linkend="wayland-protocols"/>
      or you do not wish to build <application>GNOME</application> with Wayland
      support.  Other changes may be needed to allow the build to complete
      without the wayland backend enabled.  Note that a previous installation
      of gtk+3 built with wayland will interfere with installation without
      wayland.  If this is desired, remove /usr/lib/libgtk-3* before
      installation.
    </para>
  
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/gtk-doc-rebuild.xml"/>

    <!-- MESON ONLY
    <para>
      <parameter>-Dcolord=yes</parameter>: This switch allows color support
      in the GTK+ printing backend.
    </para>

    <para>
      <parameter>-Dman=true</parameter>: This switch allows generating
      manual pages.
    </para>

    <para>
      <parameter>-Dgtk_doc=false</parameter>: This switch disables building
      documentation. Replace with -Dgtk_doc=true if you have
      <xref linkend="gtk-doc"/> installed and wish to generate documentation.
    </para>
    -->

  </sect2>

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

    <sect3 id="gtk3-config">
      <title>Config Files</title>
      <para>
        <filename>~/.config/gtk-3.0/settings.ini</filename> and
        <filename>/etc/gtk-3.0/settings.ini</filename>
      </para>

      <indexterm zone="gtk3 gtk3-config">
        <primary sortas="e-AA.home-settings.ini">~/.config/gtk-3.0/settings.ini</primary>
      </indexterm>

      <indexterm zone="gtk3 gtk3-config">
        <primary sortas="e-etc-path-settings.ini">/etc/gtk-3.0/settings.ini</primary>
      </indexterm>
    </sect3>

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

      <para>
        <application>GTK+ 3</application> themes change the way a
        <application>GTK+ 3</application> application looks. An icon theme can
        be used to change the icons that appear on the application's toolbar.
        If you have installed a <application>GTK+ 3</application> theme (e.g.
        the Adwaita theme built in <application>GTK+ 3</application>),
        an icon theme (such as <xref
        linkend="oxygen-icons5"/>) and/or a font (<xref linkend="dejavu-fonts"/>), 
        you can set your preferences in <filename>~/.config/gtk-3.0/settings.ini</filename>,
        or the default system wide configuration file (as the <systemitem
        class="username">root</systemitem> user), in
        <filename>/etc/gtk-3.0/settings.ini</filename>.  For the local user an
        example is:
      </para>

<screen><userinput>mkdir -vp ~/.config/gtk-3.0
cat &gt; ~/.config/gtk-3.0/settings.ini &lt;&lt; "EOF"
<literal>[Settings]
gtk-theme-name = <replaceable>Adwaita</replaceable>
gtk-icon-theme-name = <replaceable>oxygen</replaceable>
gtk-font-name = <replaceable>DejaVu Sans 12</replaceable>
gtk-cursor-theme-size = <replaceable>18</replaceable>
gtk-toolbar-style = <replaceable>GTK_TOOLBAR_BOTH_HORIZ</replaceable>
gtk-xft-antialias = <replaceable>1</replaceable>
gtk-xft-hinting = <replaceable>1</replaceable>
gtk-xft-hintstyle = <replaceable>hintslight</replaceable>
gtk-xft-rgba = <replaceable>rgb</replaceable>
gtk-cursor-theme-name = <replaceable>Adwaita</replaceable></literal>
EOF</userinput></screen>

      <para>
        There are many settings keys, some with default values. You can find
        them at <ulink
        url="https://developer.gnome.org/gtk3/stable/GtkSettings.html">Settings:
        GTK+ 3 Reference Manual</ulink>. There are many more themes available at
        <ulink url="http://gnome-look.org/"/> and other places.
      </para>
   
      <para>
        As part of GTK+-3.0's redesign, the scroll bar buttons are no longer
        visible on the scrollbar in many applications. If this functionality
        is desired, modify the <filename>gtk.css</filename> file and restore
        them using the following command:
      </para>

<screen><userinput>cat &gt; ~/.config/gtk-3.0/gtk.css &lt;&lt; "EOF"
<literal>*  {
   -GtkScrollbar-has-backward-stepper: 1;
   -GtkScrollbar-has-forward-stepper: 1;
}</literal>
EOF</userinput></screen>

      <!-- This trick was discovered in the Seamonkey-2.53.2 release notes:
           http://www.seamonkey-project.org/releases/seamonkey2.53.2/ -->

    </sect3>
  </sect2>

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

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

      <seglistitem>
        <seg>
          broadwayd,
          gtk3-demo,
          gtk3-demo-application,
          gtk3-icon-browser,
          gtk3-widget-factory,
          gtk-builder-tool,
          gtk-encode-symbolic-svg,
          gtk-launch,
          gtk-query-immodules-3.0, 
          gtk-query-settings, and
          gtk-update-icon-cache
        </seg>
        <seg>
          libgailutil-3.so, libgdk-3.so, and libgtk-3.so
        </seg>
        <seg>
          /etc/gtk-3.0,
          /usr/include/{gail,gtk}-3.0,
          /usr/{lib,share}/gtk-3.0,
          /usr/share/gtk-doc/html/{gail-libgail-util,gdk,gtk}3, and
          /usr/share/themes/{Default,Emacs}/gtk-3.0
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="broadwayd">
        <term><command>broadwayd</command></term>
        <listitem>
          <para>
            provides support for displaying
            <application>GTK+ 3</application> applications in a web browser,
            using HTML5 and web sockets.
          </para>
          <indexterm zone="gtk3 broadwayd">
            <primary sortas="b-broadwayd">broadwayd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk3-demo">
        <term><command>gtk3-demo</command></term>
        <listitem>
          <para>
            is a simple program that demonstrates some of the tasks that can be
            done with <application>GTK+ 3</application>
          </para>
          <indexterm zone="gtk3 gtk3-demo">
            <primary sortas="b-gtk3-demo">gtk3-demo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk3-demo-application">
        <term><command>gtk3-demo-application</command></term>
        <listitem>
          <para>
            is a simple <application>GTK+ 3</application> application.
          </para>
          <indexterm zone="gtk3 gtk3-demo-application">
            <primary sortas="b-gtk3-demo-application">gtk3-demo-application</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk3-icon-browser">
        <term><command>gtk3-icon-browser</command></term>
        <listitem>
          <para>
            is a utility to explore the icons in the current icon theme. It
            shows icons in various sizes, their symbolic variants where
            available, as well as a description of the icon and its context.
          </para>
          <indexterm zone="gtk3 gtk3-icon-browser">
            <primary sortas="b-gtk3-icon-browser">gtk3-icon-browser</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk3-widget-factory">
        <term><command>gtk3-widget-factory</command></term>
        <listitem>
          <para>
            is a program to view <application>GTK+ 3</application> themes and widgets.
          </para>
          <indexterm zone="gtk3 gtk3-widget-factory">
            <primary sortas="b-gtk3-widget-factory">gtk3-widget-factory</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-builder-tool">
        <term><command>gtk-builder-tool</command></term>
        <listitem>
          <para>
            can perform various operations on GtkBuilder .ui files.
          </para>
          <indexterm zone="gtk3 gtk-builder-tool">
            <primary sortas="b-gtk-builder-tool">gtk-builder-tool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-encode-symbolic-svg">
        <term><command>gtk-encode-symbolic-svg</command></term>
        <listitem>
          <para>
            converts symbolic svg icons into specially prepared png files.
            <application>GTK+ 3</application> can load and recolor these pngs,
            just like original svgs, but loading them is much faster.
          </para>
          <indexterm zone="gtk3 gtk-encode-symbolic-svg">
            <primary sortas="b-gtk-encode-symbolic-svg">gtk-encode-symbolic-svg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-launch">
        <term><command>gtk-launch</command></term>
        <listitem>
          <para>
            launches an application using the given name. The name should match
            the application desktop file name, as residing in
            <filename class="directory">/usr/share/applications</filename>, with
            or without the '.desktop' suffix.
          </para>
          <indexterm zone="gtk3 gtk-launch">
            <primary sortas="b-gtk-launch">gtk-launch</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-query-immodules-3.0">
        <term><command>gtk-query-immodules-3.0</command></term>
        <listitem>
          <para>
            collects information about loadable input method modules for
            <application>GTK+ 3</application> and writes it to the default cache
            file location, or to standard output.
          </para>
          <indexterm zone="gtk3 gtk-query-immodules-3.0">
            <primary sortas="b-gtk-query-immodules-3.0">gtk-query-immodules-3.0</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-query-settings">
        <term><command>gtk-query-settings</command></term>
        <listitem>
          <para>
            provides a complete listing of all settings related to 
            <application>GTK+ 3</application>
          </para>
          <indexterm zone="gtk3 gtk-query-settings">
            <primary sortas="b-gtk-query-settings">gtk-query-settings</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gtk-update-icon-cache3">
        <term><command>gtk-update-icon-cache</command></term>
        <listitem>
          <para>
            is an icon theme caching utility that creates mmap()able cache files
            for icon themes.
          </para>
          <indexterm zone="gtk3 gtk-update-icon-cache3">
            <primary sortas="b-gtk-update-icon-cache3">gtk-update-icon-cache</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgailutil-3">
        <term><filename class="libraryfile">libgailutil-3.so</filename></term>
        <listitem>
          <para>
            contains functions that implement the accessibility interfaces
            defined by the <application>GNOME</application> Accessibility
            Toolkit.
          </para>
          <indexterm zone="gtk3 libgailutil-3">
            <primary sortas="c-libgailutil-3">libgailutil-3.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgdk-3">
        <term><filename class="libraryfile">libgdk-3.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="gtk3 libgdk-3">
            <primary sortas="c-libgdk-3">libgdk-3.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

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

    </variablelist>

  </sect2>

</sect1>