[libadwaita/wip/exalm/migration-guide] doc: Add a migration guide from libhandy 1.4
- From: Alexander Mikhaylenko <alexm src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libadwaita/wip/exalm/migration-guide] doc: Add a migration guide from libhandy 1.4
- Date: Thu, 6 May 2021 15:34:34 +0000 (UTC)
commit 010de7cca45fc6119472439eb958029f0c603bc6
Author: Adrien Plazas <kekun plazas laposte net>
Date: Thu Apr 8 13:07:51 2021 +0200
doc: Add a migration guide from libhandy 1.4
Fixes https://gitlab.gnome.org/GNOME/libadwaita/-/issues/36
doc/adwaita-docs.xml | 4 +-
doc/hdy-migrating-0-0-to-1.xml | 356 ---------------------------
doc/meson.build | 2 +-
doc/migrating-libhandy-1-4-to-libadwaita.xml | 308 +++++++++++++++++++++++
4 files changed, 311 insertions(+), 359 deletions(-)
---
diff --git a/doc/adwaita-docs.xml b/doc/adwaita-docs.xml
index 8740ca5..1d3bb43 100644
--- a/doc/adwaita-docs.xml
+++ b/doc/adwaita-docs.xml
@@ -78,9 +78,9 @@
</chapter>
<chapter id="migrating">
- <title>Migrating from Previous Versions of Adwaita</title>
+ <title>Migrating from Libhandy 1.4 to Libadwaita</title>
- <xi:include href="hdy-migrating-0-0-to-1.xml"/>
+ <xi:include href="migrating-libhandy-1-4-to-libadwaita.xml"/>
</chapter>
<chapter id="object-tree">
diff --git a/doc/meson.build b/doc/meson.build
index b4e4ff9..572cf38 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -34,7 +34,7 @@ images = [
content_files = [
'build-howto.xml',
- 'hdy-migrating-0-0-to-1.xml',
+ 'migrating-libhandy-1-4-to-libadwaita.xml',
'visual-index.xml',
]
diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.xml b/doc/migrating-libhandy-1-4-to-libadwaita.xml
new file mode 100644
index 0000000..84c5ae9
--- /dev/null
+++ b/doc/migrating-libhandy-1-4-to-libadwaita.xml
@@ -0,0 +1,308 @@
+<?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="migrating-libhandy-1-4-to-libadwaita">
+ <refmeta>
+ <refentrytitle>Migrating from Libhandy 1.4 to Libadwaita</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>Migrating from Libhandy 1.4 to Libadwaita</refname><refpurpose>Notes on migration to
Libadwaita.</refpurpose>
+ </refnamediv>
+
+ <para>
+ Libadwaita is being developed as a successor to Libhandy 1.4. As such, it
+ offers to GTK 4 many features Libhandy was offering to GTK 3.
+ </para>
+
+ <para>
+ Migrating from Libhandy 1.4 to Libadwaita implies migrating from GTK 3 to 4.
+ This guide only focuses on on Libhandy and Libadwaita, and is designed to be
+ used together with the
+ <ulink url="https://docs.gtk.org/gtk4/migrating-3to4.html";>GTK 3 to 4 migration guide</ulink>.
+ </para>
+
+ <para>
+ You may notice some differences between Libhandy and Libadwaita missing in
+ this guide, in such a case
+ <ulink url="https://gitlab.gnome.org/GNOME/libadwaita/-/issues/new";>please report them here</ulink>.
+ </para>
+
+ <refsect2>
+ <title>Preparation in Libhandy 1.4</title>
+
+ <para>
+ The steps outlined in the following sections assume that your software is
+ working with Libhandy 1.4, which is the latest stable release of Libhandy
+ 1.x.
+ It includes all the necessary APIs and tools to help you port your
+ software to Libadwaita.
+ If you are using an older version of Libhandy, you should first get your
+ software to build and work with Libhandy 1.3.
+ </para>
+
+ <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 Libhandy 1.4 also includes an
+ <ulink
url="https://gnome.pages.gitlab.gnome.org/libhandy/doc/1-latest/deprecated-api-index.html";>index</ulink>
+ of all deprecated symbols.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Subclassing</title>
+ <para>
+ Following GTK4 emphasis on composition and delegation over subclassing,
+ #AdwLeaflet and #AdwHeaderBar are no longer derivable. As a replacement,
+ you can subclass GtkBin or GtkBox and include a leaflet or a header bar
+ as a child widget.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Stop using HdyKeypad</title>
+ <para>
+ HdyKeypad has been removed from Libadwaita. Applications that had used
+ it can copy it in tree instead.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Stop using named WM colors</title>
+ <para>
+ The following named colors have been removed from the stylesheet in
+ Libadwaita: @wm_title, @wm_unfocused_title, @wm_highlight,
+ @wm_borders_edge, @wm_bg_a, @wm_bg_b, @wm_shadow, @wm_border,
+ @wm_button_hover_color_a, @wm_button_hover_color_b,
+ @wm_button_active_color_a, @wm_button_active_color_b,
+ @wm_button_active_color_c. Applications should not use them.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Bundle the icons you're using</title>
+ <para>
+ The preferred way to use icons in applications is to copy them into the
+ application and include via #GResource. Referencing system icons won't
+ work in Libadwaita other than for icons GTK itself ships, so make sure
+ to bundle the icons.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Use HdyFlap properties for adding widgets</title>
+ <para>
+ HdyFlap provides the "content", "flap" and "separator" properties that
+ can be used for managing children instead of GtkContainer API. In
+ Libadwaita they are the only way to manage #AdwFlap children.
+ </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 Libadwaita
+ 1. Making it possible to prepare for these in GTK 3 would have been
+ either impossible or impractical.
+ </para>
+
+ <refsect3>
+ <title>Adapt to HdySearchBar and HdyWindowHandle removal</title>
+ <para>
+ HdySearchBar and HdyWindowHandle have been removed, use #GtkSearchBar
+ and #GtkWindowHandle instead.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to GtkContainer removal</title>
+ <para>
+ Same as GTK itself, all widgets that have children have a new API to
+ replace gtk_container_add() and gtk_container_remove().
+ </para>
+
+ <para>
+ The following widgets that formerly subclassed GtkBin have a "child"
+ property now:
+
+ <itemizedlist>
+ <listitem>#AdwApplicationWindow</listitem>
+ <listitem>#AdwClamp</listitem>
+ <listitem>#AdwStatusPage</listitem>
+ <listitem>#AdwWindow</listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For other widgets use the following replacements:
+
+ <table>
+ <tgroup cols="2">
+ <title>Replacement API for GtkContainer</title>
+ <thead>
+ <row><entry>Widget</entry><entry>Replacement</entry></row>
+ </thead>
+ <tbody>
+ <row><entry>#AdwActionRow</entry><entry>adw_action_row_add_suffix(),
adw_action_row_remove()</entry></row>
+ <row><entry>#AdwCarousel</entry><entry>adw_carousel_append(),
adw_carousel_remove()</entry></row>
+ <row><entry>#AdwExpanderRow</entry><entry>adw_expander_row_add(),
adw_expander_row_remove()</entry></row>
+ <row><entry>#AdwLeaflet</entry><entry>adw_leaflet_append(), adw_leaflet_remove()</entry></row>
+ <row><entry>#AdwPreferencesGroup</entry><entry>adw_preferences_group_add(),
adw_preferences_group_remove()</entry></row>
+ <row><entry>#AdwPreferencesPage</entry><entry>adw_preferences_page_add(),
adw_preferences_page_remove()</entry></row>
+ <row><entry>#AdwPreferencesWindow</entry><entry>adw_preferences_window_add(),
adw_preferences_window_remove()</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>
+ Adding children in a ui file still works.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to HdySearchBar and HdyWindowHandle removal</title>
+ <para>
+ HdySearchBar and HdyWindowHandle have been removed, use #GtkSearchBar
+ and #GtkWindowHandle instead.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to #AdwClamp API changes</title>
+ <para>
+ HdyClamp previously had .small, .medium or .large style classes
+ depending on the current size of its child. These style classes are now
+ added to the child instead of the clamp itself.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to #AdwComboRow API changes</title>
+ <para>
+ #AdwComboRow API has been completely overhauled compared to HdyComboRow
+ and closely mirrors #GtkDropDown. Refer to #GtkDropDown documentation
+ for details.
+ </para>
+ <para>
+ hdy_combo_row_bind_name_model() can be replaced with using the
+ #AdwComboRow:model property in conjunction with #AdwComboRow:expression.
+ </para>
+ <para>
+ hdy_combo_row_bind_model() can be replaced with using the
+ #AdwComboRow:model property in conjunction with #AdwComboRow:factory
+ and/or #AdwComboRow:list-factory.
+ </para>
+ <para>
+ hdy_combo_row_set_for_enum() can be replaced with an #AdwEnumListModel
+ in conjunction with the #AdwComboRow:expression property, for example:
+
+ <informalexample><programlisting>
+ expr = gtk_property_expression_new (HDY_TYPE_ENUM_VALUE_OBJECT, NULL, "nick");
+ model = G_LIST_MODEL (hdy_enum_list_model_new (GTK_TYPE_ORIENTATION));
+
+ hdy_combo_row_set_expression (row, expr);
+ hdy_combo_row_set_model (row, model);
+ </programlisting></informalexample>
+ </para>
+ <para>
+ As with #GtkDropDown, if the model is a #GtkStringList, the model items
+ can be converted into human-readable strings automatically without
+ requiring an expression.
+ </para>
+ <para>
+ The HdyComboRow:selected-index property has been renamed to
+ #AdwComboRow:selected, matching #GtkDropDown.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Stop creating HdyEnumValueObject instances</title>
+ <para>
+ #AdwEnumValueObject can no longer be manually created and is only
+ intended to be used with #AdwEnumListModel.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to #AdwHeaderBar API changes</title>
+ <para>
+ #AdwHeaderBar API mostly mirrors #GtkHeaderBar, refer to the
+ <ulink
url="https://docs.gtk.org/gtk4/migrating-3to4.html#adapt-to-gtkheaderbar-and-gtkactionbar-api-changes";>GTK 3
to 4 migration guide</ulink>
+ for details.
+ </para>
+ <para>
+ The adw_header_bar_set_show_title_buttons() function has been split into
+ adw_header_bar_set_show_start_title_buttons() and
+ adw_header_bar_set_show_end_title_buttons() to simplify creating
+ multi-pane layouts. The corresponding getter and the property have been
+ split as well.
+ </para>
+ <para>
+ The #AdwWindowTitle widget may be useful for replacing the title and
+ subtitle.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to HdyHeaderGroup removal</title>
+ <para>
+ HdyHeaderGroup has been removed. Its behavior can be replicated by
+ changing the #AdwHeaderBar:show-start-title-buttons and
+ #AdwHeaderBar:show-end-title-buttons properties depending on the layout,
+ for example binding them to the #AdwLeaflet:folded property.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to HdyDeck removal</title>
+ <para>
+ HdyDeck has been removed. Instead, an #AdwLeaflet can be used the same
+ way by setting the #AdwLeaflet:can-unfold property to %FALSE.
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to #AdwLeaflet and #AdwSqueezer API changes</title>
+ <para>
+ The child properties of HdyLeaflet and HdySqueezer have been converted
+ into page objects, similarly to #GtkStack. For example,
+ adw_squeezer_page_set_enabled() should be used to replace
+ hdy_squeezer_set_child_enabled().
+ </para>
+ </refsect3>
+
+ <refsect3>
+ <title>Adapt to stylesheet changes</title>
+
+ <para>
+ Most widgets don't have a backdrop state anymore, and the public colors
+ @theme_unfocused_fg_color, @theme_unfocused_text_color,
+ @theme_unfocused_bg_color, @theme_unfocused_base_color,
+ @theme_unfocused_selected_bg_color, @theme_unfocused_selected_fg_color,
+ @unfocused_insensitive_color and @unfocused_borders have been removed.
+ </para>
+
+ <para>
+ The .list-button style class has been renamed to the more accurate name
+ .outline.
+ </para>
+ </refsect3>
+
+ </refsect2>
+
+</refentry>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
