<?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;
]>

<refentry id="hdy-migrating-0-0-to-1">
  <refmeta>
    <refentrytitle>Migrating from Handy 0.0.x to Handy 1</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>Migrating from Handy 0.0.x to Handy 1</refname><refpurpose>Notes on migration to Handy 1.</refpurpose>
  </refnamediv>

  <para>
    Handy 1 is a major new version of Handy that breaks both API and ABI
    compared to Handy 0.0.x. 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
    Handy 0.0.x application for the switch to Handy 1. After that, there's a
    number of adjustments that you may have to do when you actually switch your
    application to build against Handy 1.
  </para>

  <refsect2>
    <title>Preparation in Handy 0.0.x</title>

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

    <refsect3>
      <title>Do not use the static build option</title>
      <para>
        Static linking support has been removed, and so did the static build
        option.
        You must adapt you program to link to the library dynamically, using
        the package_subdir build option if needed.
      </para>
    </refsect3>

    <refsect3>
      <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 3 also includes an
        <ulink url="https://developer.puri.sm/projects/libhandy/unstable/deprecated-api-index.html">index</ulink>
        of all deprecated symbols.
      </para>
    </refsect3>

  </refsect2>

  <refsect2>
    <title>Changes that need to be done at the time of the switch</title>

    <para>
      This section outlines porting tasks that you need to tackle when you get
      to the point that you actually build your application against Handy 1.
      Making it possible to prepare for these in Handy 0.0 would have been
      either impossible or impractical.
    </para>

    <refsect3>
      <title>hdy_init takes no parameters</title>
      <para>
        hdy_init() has been modified to take no parameters.
        It must be called just after initializing GTK, if you are using
        #GtkApplication it means it must be called when the
        #GApplication::startup signal is emitted.
      </para>
      <para>
        It initializes the localization, the types, the themes, and the icons.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to widget constructor changes</title>
      <para>
        All widget constructors now return the #GtkWidget type rather than the
        constructed widget's type, following the same convention as GTK 3.
      </para>
      <para>
        Affected widgets:
        #HdyActionRow, #HdyComboRow, #HdyExpanderRow,
        #HdyPreferencesGroup, #HdyPreferencesPage, #HdyPreferencesRow,
        #HdyPreferencesWindow, #HdySqueezer, #HdyTitleBar, #HdyViewSwitcherBar,
        #HdyViewSwitcher
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to derivability changes</title>
      <para>
        Some widgets are now final, if your code is deriving from them, use
        composition instead.
      </para>
      <para>
        Affected widgets:
        #HdySqueezer, #HdyViewSwitcher, #HdyViewSwitcherBar
      </para>
    </refsect3>

    <refsect3>
      <title>HdyFold has been removed</title>
      <para>
        #HdyFold has been removed. This affects the API of #HdyLeaflet, see the
        “Adapt to HdyLeaflet API changes” section to know how.
      </para>
    </refsect3>

    <refsect3>
      <title>Replace HdyColumn by HdyClamp</title>
      <para>
        HdyColumn has been renamed #HdyClamp as it now implements
        #GtkOrientable, so you should replace the former by the later.
        Its “maximum-width” and “linear-growth-width” properties have been
        renamed #HdyClamp:maximum-size and #HdyClamp:tightening-threshold
        respectively to better reflect their role.
        It won't set the .narrow, .medium and .wide style classes depending on
        its size, but the .small, .medium and .large ones instead.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyPaginator API changes</title>
      <para>
        HdyPaginator has been renamed HdyCarousel, so you should replace the
        former by the later.
      </para>
      <para>
        The “indicator-style”, “indicator-spacing” and “center-content”
        properties have been removed, instead use #HdyCarouselIndicatorDots
        or #HdyCarouselIndicatorLines widgets.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyHeaderGroup API changes</title>
      <para>
        The #HdyHeaderGroup object has been largely redesigned, most of its
        methods changed, see its documentation to know more.
      </para>
      <para>
        The child type is now #HdyHeaderGroupChild, which can represent either
        a #GtkHeaderBar, a #HdyHeaderBar, or a #HdyHeaderGroup.
      </para>
      <para>
        The “focus” property has been replaced by #HdyHeaderGroup:decorate-all,
        which works quite differently.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyLeaflet API changes</title>
      <para>
        The #HdyFold type has been removed in favor of using a boolean, and
        #HdyLeaflet adjusted to that as the #HdyLeaflet:fold property has been
        removed in favor of #HdyLeaflet:folded.
        Also, the hdy_leaflet_get_homogeneous() and
        hdy_leaflet_set_homogeneous() accessors take a boolean parameter instead
        of a #HdyFold.
      </para>
      <para>
        On touchscreens, swiping forward with the “over” transition and swiping
        back with the “under” transition can now only be done from the edge
        where the upper child is.
      </para>
      <para>
        The “over” and “under” transitions can draw their shadow on top of the
        window's transparent areas, like the rounded corners.
        This is a side-effect of allowing shadows to be drawn on top of OpenGL
        areas.
        It can be mitigated by using #HdyWindow or #HdyApplicationWindow as they
        will crop anything drawn beyond the rounded corners.
      </para>
      <para>
        The “allow-visible” child property has been renamed “navigatable”.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyLeaflet API changes</title>
      <para>
        The “none” transition type has been removed. The default value for the
        #HdyLeaflet:transition-type property has been changed to “over”.
        “over” is the recommended transition for typical #HdyLeaflet use-cases,
        if this isn't what you want to use, be sure to adapt your code. If
        transitions are undesired, set #HdyLeaflet:mode-transition-duration and
        #HdyLeaflet:child-transition-duration properties to 0.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyViewSwitcher API changes</title>
      <para>
        #HdyViewSwitcher doesn't subclass #GtkBox anymore. Instead, it
        subclasses #GtkBin and contains a box.
      </para>
      <para>
        The “icon-size” property has been dropped without replacement, you must
        stop using it.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyViewSwitcherBar API changes</title>
      <para>
        #HdyViewSwitcherBar won't be revealed if the #HdyViewSwitcherBar:stack
        property is %NULL or if it has less than two pages, even if you set
        #HdyViewSwitcherBar:reveal to %TRUE.
      </para>
      <para>
        The “icon-size” property has been dropped without replacement, you must
        stop using it.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to CSS node name changes</title>
      <para>
        Widgets with a customn CSS node name got their name changed to be the
        class' name in lowercase, with no separation between words, and with no
        namespace prefix. E.g. the CSS node name of HdyViewSwitcher is
        viewswitcher.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyActionRow API changes</title>
      <para>
        Action items were packed from the end toward the start of the row. It is
        now reversed, and widgets have to be packed from the start to the end.
      </para>
      <para>
        It isn't possible to add children at the bottom of a #HdyActionRow
        anymore, instead use other widgets like #HdyExpanderRow.
        Widgets added to a #HdyActionRow will now be added at the end of the
        row, and the hdy_action_row_add_action() method and the action child
        type have been removed.
      </para>
      <para>
        The main horizontal box of #HdyActionRow had the row-header CSS style
        class, it now has the header CSS style class and can hence be accessed
        as box.header subnode.
      </para>
      <para>
        #HdyActionRow is now unactivatable by default, giving it an activatable
        widget will automatically make it activatable.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyComboRow API changes</title>
      <para>
        #HdyComboRow is now unactivatable by default, binding and unbinding a
        model will toggle its activatability.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyExpanderRow API changes</title>
      <para>
        #HdyExpanderRow doesn't descend from #HdyActionRow anymore but from
        #HdyPreferencesRow.
        It reimplement some features from #HdyActionRow, like the
        #HdyExpanderRow:title, #HdyExpanderRow:subtitle,
        #HdyExpanderRow:use-underline and #HdyExpanderRow:icon-name, but it
        doesn't offer the “activate” signal nor the ability to add widgets in
        its header row.
      </para>
      <para>
        Widgets you add to it will be added to its inner #GtkListBox.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyPreferencesPage API changes</title>
      <para>
        #HdyPreferencesPage doesn't subclass #GtkScrolledWindow anymore.
        Instead, it subclasses #GtkBin and contains a scrolled window.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyPreferencesGroup API changes</title>
      <para>
        #HdyPreferencesGroup doesn't subclass #GtkBox anymore.
        Instead, it subclasses #GtkBin and contains a box.
      </para>
    </refsect3>

    <refsect3>
      <title>Adapt to HdyKeypad API changes</title>
      <para>
        #HdyKeypad doesn't subclass #Gtkgrid anymore. Instead, it subclasses
        #GtkBin and contains a grid.
      </para>
      <para>
        The “show-symbols” property has been replaced by
        #HdyHeaderGroup:letters-visible.
      </para>
      <para>
        The “only-digits” property has been replaced by
        #HdyHeaderGroup:symbols-visible, which has a inverse boolean meaning.
        This also affects the corresponding parameter of the constructor.
      </para>
      <para>
        The “left-action” property has been replaced by
        #HdyHeaderGroup:start-action, and the “right-action” property has been
        replaced by #HdyHeaderGroup:end-action.
      </para>
      <para>
        The “entry” property isn't a #GtkWidget anymore but a #GtkEntry.
      </para>
    </refsect3>

    <refsect3>
      <title>Stop using hdy_list_box_separator_header()</title>
      <para>
        Instead, either use CSS styling (the list.content style class may
        fit your need), or implement it yourself as it is trivial.
      </para>
    </refsect3>

    <refsect3>
      <title>Stop acknowledging the Instability</title>
      <para>
        When the library was young and changing a lot, we required you to
        acknowledge that your are using an unstable API. To do so, you had to
        define <literal>HANDY_USE_UNSTABLE_API</literal> for compilation to
        succeed.
      </para>
      <para>
        The API remained stable since many versions, despite this acknowlegment
        still being required. To reflect that proven stability, the
        acknowlegment isn't necessary and you can stop defining
        <literal>HANDY_USE_UNSTABLE_API</literal>, either before including the
        &package_string; header in C-compatible languages, or with the
        definition option of your compiler.
      </para>
    </refsect3>

  </refsect2>

</refentry>

