<?xml version="1.0"?>
<!DOCTYPE refentry 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'">
 <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
 %gtkdocentities;
]>

<part id="porting-guides">
<title>Porting Guides</title>

<chapter id="porting-guide-3-to-4">
  <title>GtkSourceView 3 -> 4 Porting Guide</title>

  <refsect1>
    <title>GTK dependency</title>
    <para>
      Both GtkSourceView 3 and GtkSourceView 4 depend on GTK 3.
    </para>
  </refsect1>

  <refsect1>
    <title>Preparation in GtkSourceView 3</title>
    <para>
      GtkSourceView 3.24 is the latest stable GtkSourceView 3 version. Before
      continuing this porting guide, you should use the 3.24 version without
      using any deprecated API.
    </para>
  </refsect1>

  <refsect1>
    <title>New pkg-config name</title>
    <para>
      For GtkSourceView 4, the pkg-config name is:
      <code>gtksourceview-4</code>
    </para>
    <para>
      To compile a program that uses GtkSourceView 4, you
      can for example use the following command:
    </para>
    <para>
      <code>$ gcc hello.c `pkg-config --cflags --libs gtksourceview-4` -o hello</code>
    </para>
  </refsect1>

  <refsect1>
    <title>GtkSourceView 3.99.1</title>
    <itemizedlist>
      <listitem>
        <para>
          All the deprecated APIs have been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          Only <code>&lt;gtksourceview/gtksource.h&gt;</code> can be included
          directly. There were already warnings about it in GtkSourceView 3. The
          warnings have been changed to errors.
        </para>
      </listitem>
      <listitem>
        <para>
          Only the version 2 of the <link linkend="lang-reference">GtkSourceView
          language definition file format</link> is supported (for *.lang files,
          used for syntax highlighting). The support for the version 1 has been
          dropped.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>GtkSourceView 3.99.2</title>
    <itemizedlist>
      <listitem>
        <para>
          <code>gtk_source_completion_item_new2()</code> has been renamed to
          <link linkend="gtk-source-completion-item-new">gtk_source_completion_item_new()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>gtk_source_search_context_forward2()</code> has been renamed to
          <link linkend="gtk-source-search-context-forward">gtk_source_search_context_forward()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>gtk_source_search_context_forward_finish2()</code> has been renamed to
          <link linkend="gtk-source-search-context-forward-finish">gtk_source_search_context_forward_finish()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>gtk_source_search_context_backward2()</code> has been renamed to
          <link linkend="gtk-source-search-context-backward">gtk_source_search_context_backward()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>gtk_source_search_context_backward_finish2()</code> has been renamed to
          <link linkend="gtk-source-search-context-backward-finish">gtk_source_search_context_backward_finish()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>gtk_source_search_context_replace2()</code> has been renamed to
          <link linkend="gtk-source-search-context-replace">gtk_source_search_context_replace()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <link linkend="GtkSourceSearchContext--settings">GtkSourceSearchContext:settings</link>
          property is now construct-only.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>GtkSourceView 3.99.3</title>
    <para>No API changes.</para>
  </refsect1>

  <refsect1>
    <title>GtkSourceView 3.99.4</title>
    <itemizedlist>
      <listitem>
        <para>
          The API of the
          <link linkend="GtkSourceView-move-lines">GtkSourceView::move-lines</link>
          keybinding signal has been simplified: the <code>copy</code> parameter
          was deprecated and has been removed; and the <code>count</code>
          parameter has been replaced by the <code>down</code> boolean.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>GtkSourceView 3.99.5 and 3.99.6</title>
    <para>No API changes.</para>
  </refsect1>

  <refsect1>
    <title>GtkSourceView 3.99.7</title>
    <para>
      In order to have a better *.gir file and have less metadata to generate
      the *.vapi for Vala, the following change has been made:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <code>gtk_source_completion_show()</code> has been renamed to
          <link linkend="gtk-source-completion-start">gtk_source_completion_start()</link>.
          The function conflicted with the
          <link linkend="GtkSourceCompletion-show">GtkSourceCompletion::show</link> signal.
          Note that in Vala this doesn't require code changes because the method
          was already renamed to <code>start()</code> in GtkSourceView&nbsp;3.
        </para>
      </listitem>
    </itemizedlist>

    <para>
      Other changes in 3.99.7:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          For i18n initialization, the
          <link linkend="gtk-source-init">gtk_source_init()</link> function
          now needs to be called. There is also the
          <link linkend="gtk-source-finalize">gtk_source_finalize()</link>
          function which is convenient when using memory debugging tools.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>
</chapter>

<chapter id="porting-guide-gtksourceview-4-to-libgedit-gtksourceview-299-0">
  <title>GtkSourceView 4 -> libgedit-gtksourceview 299.0 Porting Guide</title>

  <refsect1>
    <title>GTK dependency</title>
    <para>
      Both GtkSourceView 4 and libgedit-gtksourceview 299.x.y depend on GTK 3.
    </para>
  </refsect1>

  <refsect1>
    <title>pkg-config name</title>
    <para>
      The new pkg-config name is:
      <code>libgedit-gtksourceview-300</code>
    </para>
    <para>
      The “3” in “300” means that it targets GTK 3.
    </para>
  </refsect1>

  <refsect1>
    <title>For Vala</title>
    <para>
      For Vala code, use the GObject Introspection file, not the
      <code>*.vapi</code>, because the <code>*.vapi</code> file has been
      removed.
    </para>
  </refsect1>

  <refsect1>
    <title>For Glade</title>
    <para>
      The Glade catalog has been removed, so don't rely on it.
    </para>
  </refsect1>

  <refsect1>
    <title>Paths to lang and style files</title>
    <para>
      The paths to <code>*.lang</code> and style scheme files have changed. For
      example,
      <filename>/usr/share/libgedit-gtksourceview-300/language-specs/</filename>
      is the usual location where <code>*.lang</code> files are found.
    </para>
  </refsect1>

  <refsect1>
    <title>API breaks</title>
    <itemizedlist>
      <listitem>
        <para>
          <code>GtkSourceMap</code> has been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>GtkSourceStyleSchemeChooserButton</code> and
          <code>GtkSourceStyleSchemeChooserWidget</code> have been removed. See
          the Tepl library for a replacement.
        </para>
      </listitem>
      <listitem>
        <para>
          The macros and functions to check the library version have been
          removed: the <code>gtk_source_check_version()</code>,
          <code>gtk_source_get_major_version()</code>, etc functions; as well as
          all the macros such as <code>GTK_SOURCE_CHECK_VERSION()</code>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>GtkSourceStyleSchemeManager:scheme-ids</code> and
          <code>GtkSourceStyleSchemeManager:search-path</code> properties have
          been removed. Instead, you can connect to the
          <link linkend="GtkSourceStyleSchemeManager-changed">GtkSourceStyleSchemeManager::changed</link>
          signal to be notified.
        </para>
        <para>
          The <code>gtk_source_style_scheme_manager_get_scheme_ids()</code>
          function has been removed, use
          <link linkend="gtk-source-style-scheme-manager-get-schemes">gtk_source_style_scheme_manager_get_schemes()</link>
          instead.
        </para>
        <para>
          All the <link linkend="GtkSourceStyleScheme">GtkSourceStyleScheme</link>
          properties have been removed. Use the get functions instead.
        </para>
        <para>
          All the <link linkend="GtkSourceStyle">GtkSourceStyle</link>
          properties have been removed. Use the
          <code>gtk_source_style_get_data()</code> function instead.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>
</chapter>

<chapter id="porting-guide-299-0-to-299-2">
  <title>libgedit-gtksourceview 299.0 -> 299.2 Porting Guide</title>
  <refsect1>
    <title>API breaks</title>
    <itemizedlist>
      <listitem>
        <para>
          The <code>gtk_source_style_get_data()</code> function has been
          removed. <link linkend="GtkSourceStyle">GtkSourceStyle</link> is now a
          boxed type (a simple struct), no longer a GObject. Another important
          difference is to call the right ref/unref functions for memory
          management.
        </para>
        <para>
          The <link linkend="GtkSourceSearchContext--match-style">GtkSourceSearchContext:match-style</link>
          property is a <link linkend="GtkSourceStyle">GtkSourceStyle</link>, so
          it may require some code changes when using it.
        </para>
        <para>
          The <code>gtk_source_style_scheme_get_authors()</code> function has
          been removed.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>
</chapter>

<chapter id="porting-guide-299-2-to-299-3">
  <title>libgedit-gtksourceview 299.2 -> 299.3 Porting Guide</title>
  <refsect1>
    <title>API breaks</title>
    <itemizedlist>
      <listitem>
        <para>
          The <code>GtkSourceStyleSchemeChooser</code> interface has been
          removed because it is no longer used by libgedit-tepl.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>
</chapter>

<chapter id="porting-guide-299-3-to-299-4">
  <title>libgedit-gtksourceview 299.3 -> 299.4 Porting Guide</title>
  <refsect1>
    <title>API breaks</title>
    <itemizedlist>
      <listitem>
        <para>
          The background-pattern feature (with the grid pattern) has been
          removed from the <link linkend="GtkSourceView">GtkSourceView</link>
          class.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>
</chapter>

</part>