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

<part id="api-breaks">
  <title>API Breaks</title>

  <para>
    gedit is a quite old piece of software (created in 1998, at the beginnings
    of the GNOME project), and as every software, the code evolves during its
    lifetime. So there are sometimes API breaks for gedit plugins, there are no
    API stability guarantees.
  </para>

  <refsect1>
    <title>45 -> 46</title>
    <itemizedlist>
      <listitem>
        <para>
          The <link linkend="gedit-window-get-side-panel">gedit_window_get_side_panel()</link>
          function now returns a <link linkend="TeplPanel">TeplPanel</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_statusbar_new()</code> and
          <code>gedit_statusbar_set_window_state()</code> functions have been
          removed.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_utils_set_atk_name_description()</code> function has
          been removed.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>44 -> 45</title>
    <itemizedlist>
      <listitem>
        <para>
          Vala plugins need to rely on the GObject Introspection file instead of
          the vapi. The latter is no longer generated.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_window_create_tab_from_location()</code> and
          <code>gedit_window_create_tab_from_stream()</code> functions have been
          removed, use
          <link linkend="gedit-window-create-tab">gedit_window_create_tab()</link>
          followed by
          <link linkend="gedit-tab-load-file">gedit_tab_load_file()</link> or
          <link linkend="gedit-tab-load-stream">gedit_tab_load_stream()</link>
          instead.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>43 -> 44</title>
    <itemizedlist>
      <listitem>
        <para>
          When an URI is added to the
          <link linkend="GtkRecentManager">GtkRecentManager</link>,
          the <code>groups</code> field of
          <link linkend="GtkRecentData">GtkRecentData</link>
          is no longer set. You can rely on the application name instead.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_document_get_language()</code> function has been
          removed, use
          <link linkend="gtk-source-buffer-get-language">gtk_source_buffer_get_language()</link>
          instead.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_document_get_short_name_for_display()</code> function has been
          removed, use
          <link linkend="tepl-file-get-short-name">tepl_file_get_short_name()</link>
          instead.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_document_is_untitled()</code> function has been
          removed, use
          <link linkend="tepl-file-get-location">tepl_file_get_location()</link>
          instead.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_statusbar_set_overwrite()</code>
          and <code>gedit_statusbar_clear_overwrite()</code>
          functions have been removed.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>3.38 -> 40</title>
    <itemizedlist>
      <listitem>
        <para>
          All previously deprecated APIs have been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>GeditProgressInfoBar</code> class has been removed, you can
          use <link linkend="TeplProgressInfoBar">TeplProgressInfoBar</link>
          instead.
        </para>
      </listitem>
      <listitem>
        <para>
          <link linkend="GeditDocument">GeditDocument</link> is now a subclass
          of <link linkend="TeplBuffer">TeplBuffer</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>GeditDocument::cursor-moved</code> signal has been removed.
          You can use the <link linkend="TeplBuffer">TeplBuffer</link> API
          instead.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_document_get_uri_for_display()</code> function has
          been removed from the public API.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>GeditDocument:shortname</code> property has been removed.
          You can use the <link linkend="TeplFile">TeplFile</link> API instead.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_document_is_untouched()</code> function has been
          removed. You can use the <link linkend="TeplBuffer">TeplBuffer</link>
          API instead.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_view_set_font()</code> function has been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>DEBUG_METADATA</code> has been removed.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>3.36.0 -> 3.37.1</title>
    <itemizedlist>
      <listitem>
        <para>
          All previously deprecated APIs have been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          The lockdown support has been removed (for the
          org.gnome.desktop.lockdown GSettings). So the
          <code>gedit_app_get_lockdown()</code> function has been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>GBOOLEAN_TO_POINTER()</code> and
          <code>GPOINTER_TO_BOOLEAN()</code> macros have been removed from
          <code>gedit-utils.h</code>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>gedit_utils_get_current_workspace()</code>,
          <code>gedit_utils_get_window_workspace()</code> and
          <code>gedit_utils_get_current_viewport()</code> functions have been
          removed because workspaces information is not available on Wayland.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>3.34.0 -> 3.35.2</title>
    <itemizedlist>
      <listitem>
        <para>
          All previously deprecated APIs have been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>GeditDocument:use-gvfs-metadata</code> property has been
          removed. But there was anyway a warning for not using that property in
          a gedit plugin.
        </para>
      </listitem>
      <listitem>
        <para>
          For <link linkend="gedit-document-get-metadata">gedit_document_get_metadata()</link>
          and <link linkend="gedit-document-set-metadata">gedit_document_set_metadata()</link>,
          the key names should now have the prefix <code>"gedit-"</code> with
          possibly an additional namespace for the plugin name, for example
          <code>"gedit-spell-foobar"</code>. So the key names are now the same
          regardless of the operating system, and the key names should no longer
          start with <code>"metadata::"</code>.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>For previous gedit versions</title>
    <para>
      See the
      <ulink url="https://wiki.gnome.org/Apps/Gedit/Attic/Old_API_Changes">Old API Changes wiki page</ulink>.
    </para>
  </refsect1>
</part>
