<commit_before><?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<chapter id="gtk-migrating-2-to-3">
  <title>Migrating from GTK+ 2.x to GTK+ 3</title>

  <para>
    GTK+ 3 is a major new version of GTK+ that breaks both API and ABI
    compared to GTK+ 2.x, which has remained API- and ABI-stable for a
    long time. Thankfully, most of the changes are not hard to adapt to
    and there are a number of steps that you can take to prepare your
    GTK+ 2.x application for the switch to GTK+ 3. After that, there's
    a small number of adjustments that you may have to do when you actually
    switch your application to build against GTK+ 3.
  </para>

  <section>
    <title>Preparation in GTK+ 2.x</title>

    <para>
      The steps outlined in the following sections assume that your
      application is working with GTK+ 2.24, which is the final stable
      release of GTK+ 2.x. It includes all the necessary APIs and tools
      to help you port your application to GTK+ 3. If you are still using
      an older version of GTK+ 2.x, you should first get your application
      to build and work with 2.24.
    </para>

  <section>
  <title>Do not include individual headers</title>
  <para>
    With GTK+ 2.x it was common to include just the header files for
    a few widgets that your application was using, which could lead
    to problems with missing definitions, etc. GTK+ 3 tightens the
    rules about which header files you are allowed to include directly.
    The allowed header files are are
    <variablelist>
      <varlistentry>
        <term><filename>gtk/gtk.h</filename></term>
        <listitem>for GTK</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gtk/gtkx.h</filename></term>
        <listitem>for the X-specfic widgets #GtkSocket and #GtkPlug</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gtk/gtkunixprint.h</filename></term>
        <listitem>for low-level, UNIX-specific printing functions</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gdk/gdk.h</filename></term>
        <listitem>for GDK</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gdk/gdkx.h</filename></term>
        <listitem>for GDK functions that are X11-specific</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gdk/gdkwin32.h</filename></term>
        <listitem>for GDK functions that are Windows-specific</listitem>
      </varlistentry>
    </variablelist>
    (these relative paths are assuming that you are using the include
     paths that are specified in the gtk+-2.0.pc file, as returned by
     <literal>pkg-config --cflags gtk+-2.0.pc</literal>.)
  </para>
  <para>
    To check that your application only includes the allowed headers,
    you can use defines to disable inclusion of individual headers,
    as follows:
    <programlisting>
    make CFLAGS+="-DGTK_DISABLE_SINGLE_INCLUDES"
    </programlisting>
  </para>
  </section>

  <section>
  <title>Do not use deprecated symbols</title>
  <para>
    Over the years, a number of functions, and in some cases, entire
    widgets have been deprecated. These deprecations are clearly spelled
    out in the API reference, with hints about the recommended replacements.
    The API reference for GTK+ 2 also includes an
    <ulink url="http://developer.gnome.org/gtk/2.24/api-index-deprecated.html">index</ulink> of all deprecated symbols.
  </para>
  <para>
    To verify that your program does not use any deprecated symbols,
    you can use defines to remove deprecated symbols from the header files,
    as follows:
    <programlisting>
    make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
   </programlisting>
  </para>
  <para>
    Note that some parts of our API, such as enumeration values, are
    not well covered by the deprecation warnings. In most cases, using
    them will require you to also use deprecated functions, which will
    trigger warnings. But some things, like the %GTK_DIALOG_NO_SEPARATOR
    flag that has disappeared in GTK+ 3, may not.
  </para>
  </section>

  <section>
  <title>Use accessor functions instead of direct access</title>
  <para>
    GTK+ 3 removes many implementation details and struct members from
    its public headers.
  </para>
  <para>
    To ensure that your application does not have problems with this, you<commit_msg>docs: fix reference to GTK+ 2 index of deprecated symbols<commit_after><?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<chapter id="gtk-migrating-2-to-3">
  <title>Migrating from GTK+ 2.x to GTK+ 3</title>

  <para>
    GTK+ 3 is a major new version of GTK+ that breaks both API and ABI
    compared to GTK+ 2.x, which has remained API- and ABI-stable for a
    long time. Thankfully, most of the changes are not hard to adapt to
    and there are a number of steps that you can take to prepare your
    GTK+ 2.x application for the switch to GTK+ 3. After that, there's
    a small number of adjustments that you may have to do when you actually
    switch your application to build against GTK+ 3.
  </para>

  <section>
    <title>Preparation in GTK+ 2.x</title>

    <para>
      The steps outlined in the following sections assume that your
      application is working with GTK+ 2.24, which is the final stable
      release of GTK+ 2.x. It includes all the necessary APIs and tools
      to help you port your application to GTK+ 3. If you are still using
      an older version of GTK+ 2.x, you should first get your application
      to build and work with 2.24.
    </para>

  <section>
  <title>Do not include individual headers</title>
  <para>
    With GTK+ 2.x it was common to include just the header files for
    a few widgets that your application was using, which could lead
    to problems with missing definitions, etc. GTK+ 3 tightens the
    rules about which header files you are allowed to include directly.
    The allowed header files are are
    <variablelist>
      <varlistentry>
        <term><filename>gtk/gtk.h</filename></term>
        <listitem>for GTK</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gtk/gtkx.h</filename></term>
        <listitem>for the X-specfic widgets #GtkSocket and #GtkPlug</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gtk/gtkunixprint.h</filename></term>
        <listitem>for low-level, UNIX-specific printing functions</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gdk/gdk.h</filename></term>
        <listitem>for GDK</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gdk/gdkx.h</filename></term>
        <listitem>for GDK functions that are X11-specific</listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>gdk/gdkwin32.h</filename></term>
        <listitem>for GDK functions that are Windows-specific</listitem>
      </varlistentry>
    </variablelist>
    (these relative paths are assuming that you are using the include
     paths that are specified in the gtk+-2.0.pc file, as returned by
     <literal>pkg-config --cflags gtk+-2.0.pc</literal>.)
  </para>
  <para>
    To check that your application only includes the allowed headers,
    you can use defines to disable inclusion of individual headers,
    as follows:
    <programlisting>
    make CFLAGS+="-DGTK_DISABLE_SINGLE_INCLUDES"
    </programlisting>
  </para>
  </section>

  <section>
  <title>Do not use deprecated symbols</title>
  <para>
    Over the years, a number of functions, and in some cases, entire
    widgets have been deprecated. These deprecations are clearly spelled
    out in the API reference, with hints about the recommended replacements.
    The API reference for GTK+ 2 also includes an
    <ulink url="https://developer.gnome.org/gtk2/2.24/api-index-deprecated.html">index</ulink> of all deprecated symbols.
  </para>
  <para>
    To verify that your program does not use any deprecated symbols,
    you can use defines to remove deprecated symbols from the header files,
    as follows:
    <programlisting>
    make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
   </programlisting>
  </para>
  <para>
    Note that some parts of our API, such as enumeration values, are
    not well covered by the deprecation warnings. In most cases, using
    them will require you to also use deprecated functions, which will
    trigger warnings. But some things, like the %GTK_DIALOG_NO_SEPARATOR
    flag that has disappeared in GTK+ 3, may not.
  </para>
  </section>

  <section>
  <title>Use accessor functions instead of direct access</title>
  <para>
    GTK+ 3 removes many implementation details and struct members from
    its public headers.
  </para>
  <para>
    To ensure that your application does not have problems with this, you
{'fraction_non_alphanumeric': 0.09188955996548749, 'fraction_numerical': 0.010138050043140638, 'mean_word_length': 3.092233009708738, 'pattern_counts': {'":': 0, '<': 193, '<?xml version=': 2, '>': 193, 'https://': 1, 'lorem ipsum': 0, 'www.': 4, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4875966', 'n_tokens_mistral': 2892, 'n_tokens_neox': 2741, 'n_words': 1058}