diff options
Diffstat (limited to 'subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml')
| -rw-r--r-- | subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml b/subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml new file mode 100644 index 0000000..70b5e15 --- /dev/null +++ b/subprojects/libhandy/doc/hdy-migrating-0-0-to-1.xml @@ -0,0 +1,356 @@ +<?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> + |