<?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'">
]>

<chapter id="porting-guide-4-to-5">
  <title>GtkSourceView 4 -> 5 Migration Guide</title>

  <refsect1>
    <title>GTK+ dependency</title>
    <para>
      GtkSourceView 5 depends on GTK 4.
    </para>
  </refsect1>

  <refsect1>
    <title>GtkSourceGutterRenderer is a GtkWidget</title>
    <para>
      In GtkSourceView 5, the GtkSourceGutterRenderer has become a widget.
      This allows more flexibility by implementations to handle input as well
      as cache snapshot information for faster rendering.
    </para>
  </refsect1>

  <refsect1>
    <title>GtkSourceGutterLines</title>
    <para>
      Previously, GtkSourceView would spend a lot of time while scrolling just
      for rendering the gutter. This was because it had to calculate much line
      information on every frame (roughly 60 frames per second) and multiple
      times within that frame.
    </para>
    <para>
      In GtkSourceView 5, a GtkSourceGutterLines structure has been added to the
      API which allows for collecting that information and re-using by each
      gutter renderer, thus reducing overhead greatly.
    </para>
    <para>
      GtkSourceGutterRenderer implementations should use this to store
      information about each line and then recall it when snapshotting the
      given line.
    </para>
  </refsect1>

  <refsect1>
    <title>GtkSourceSnippet</title>
    <para>
      GtkSourceView 5 added support for snippets. This functionality did not
      exist within previous versions of GtkSourceView.
    </para>
    <para>
      The implementation contains a snippet language embedded within XML files
      as well as a completion provider. You may also "push" snippets onto a
      GtkSourceView manually by creating GtkSourceSnippetChunks and associating
      them with a GtkSourceSnippet. Many completion providers may find this more
      convenient to allow users to move through focus positions.
    </para>
  </refsect1>

  <refsect1>
    <title>GtkSourceCompletion</title>
    <para>
      GtkSourceView 5 changed how completion providers are implemented. Doing so
      has allowed for much reduction in overhead when generating results and
      presenting them to the user. Additionally, it has improved Wayland support
      for placing completion results.
    </para>
    <para>
      GtkSourceCompletionProposal no longer requires any implementation except
      to implement the interface symbolically. That can be done using
      <code>G_IMPLEMENT_INTERFACE(GTK_SOURCE_TYPE_COMPLETION_PROPOSAL,NULL)</code>.
      This allowed all of the implementation details to be placed in
      <code>GtkSourceCompletionProvider</code>.
    </para>
    <para>
      <code>GtkSourceCompletionCell</code> is a new display widget that is used
      in multiple places as a generic container for information about completion
      proposals.
    </para>
    <para>
      <code>GtkSourceCompletionProvider</code>s are now expected to asynchronously
      provide a <code>GListModel</code> of <code>GtkSourceCompletionProposal</code>
      instead of a <code>GList</code>. Refiltering of results can be provided using
      the refilter method and should be updated while the user types further. If a
      new model must be generated, use
      <link linkend="gtk-source-completion-context-set-proposals-for-provider">gtk_source_completion_context_set_proposals_for_provider()</link>.
    </para>
  </refsect1>

</chapter>
