[libadwaita/wip/cdavis/header-suffix] preferences-group: Add support for header suffixes

[Christopher Davis <christopherdavis src gnome org>]

commit b34d1f9c17d87b44da1c064fce8ce9bc385551af
Author: Christopher Davis <christopherdavis gnome org>
Date:   Mon Dec 20 12:31:47 2021 -0800

    preferences-group: Add support for header suffixes
    
    This is a common pattern in gnome-control-center - we
    should probably support it here.

 demo/adw-demo-preferences-window.ui      |  8 +++-
 src/adw-preferences-group.c              | 73 +++++++++++++++++++++++++++++++-
 src/adw-preferences-group.h              |  7 +++
 src/adw-preferences-group.ui             | 67 ++++++++++++++++++-----------
 src/stylesheet/widgets/_preferences.scss |  7 ++-
 5 files changed, 135 insertions(+), 27 deletions(-)
---
diff --git a/demo/adw-demo-preferences-window.ui b/demo/adw-demo-preferences-window.ui
index b2614ee7..2a0e25a3 100644
--- a/demo/adw-demo-preferences-window.ui
+++ b/demo/adw-demo-preferences-window.ui
@@ -29,8 +29,14 @@
         </child>
         <child>
           <object class="AdwPreferencesGroup">
-            <property name="description" translatable="yes">Preferences are grouped together, a group can 
have a title and a description. Descriptions will be wrapped if they are too long. This page has the 
following groups:</property>
+            <property name="description" translatable="yes">Preferences are grouped together, a group can 
have a title, a description, and a suffix. Descriptions will be wrapped if they are too long. This page has 
the following groups:</property>
             <property name="title" translatable="yes">Groups</property>
+            <child type="header-suffix">
+              <object class="GtkButton">
+                <property name="label" translatable="yes">Suffix</property>
+                <property name="valign">center</property>
+              </object>
+            </child>
             <child>
               <object class="AdwActionRow">
                 <property name="title" translatable="yes">An Untitled Group</property>
diff --git a/src/adw-preferences-group.c b/src/adw-preferences-group.c
index a9986e8a..554b8a64 100644
--- a/src/adw-preferences-group.c
+++ b/src/adw-preferences-group.c
@@ -24,6 +24,16 @@
  * title and a description. The title will be used by
  * [class@Adw.PreferencesWindow] to let the user look for a preference.
  *
+ * ## AdwPreferencesGroup as GtkBuildable
+ *
+ * The `AdwPreferencesGroup` implementation of the [iface@Gtk.Buildable] interface
+ * supports adding [class@PreferencesRow]s to the list by omitting "type". If "type"
+ * is omitted and the widget isn't a [class@PreferencesRow] the child is added to
+ * a box below the list.
+ *
+ * When the "type" attribute of a child is `header-suffix` children are added
+ * to a box on the end of the title and subtitle.
+ *
  * ## CSS nodes
  *
  * `AdwPreferencesGroup` has a single CSS node with name `preferencesgroup`.
@@ -38,6 +48,7 @@ typedef struct
   GtkListBox *listbox;
   GtkBox *listbox_box;
   GtkLabel *title;
+  GtkBox *header_suffix_box;
 
   GListModel *rows;
 } AdwPreferencesGroupPrivate;
@@ -213,6 +224,7 @@ adw_preferences_group_class_init (AdwPreferencesGroupClass *klass)
   gtk_widget_class_bind_template_child_private (widget_class, AdwPreferencesGroup, listbox);
   gtk_widget_class_bind_template_child_private (widget_class, AdwPreferencesGroup, listbox_box);
   gtk_widget_class_bind_template_child_private (widget_class, AdwPreferencesGroup, title);
+  gtk_widget_class_bind_template_child_private (widget_class, AdwPreferencesGroup, header_suffix_box);
   gtk_widget_class_bind_template_callback (widget_class, listbox_keynav_failed_cb);
 }
 
@@ -243,7 +255,9 @@ adw_preferences_group_buildable_add_child (GtkBuildable *buildable,
   AdwPreferencesGroup *self = ADW_PREFERENCES_GROUP (buildable);
   AdwPreferencesGroupPrivate *priv = adw_preferences_group_get_instance_private (self);
 
-  if (priv->box && GTK_IS_WIDGET (child))
+  if (g_strcmp0 (type, "header-suffix") == 0)
+    adw_preferences_group_add_header_suffix (self, GTK_WIDGET (child));
+  else if (priv->box && GTK_IS_WIDGET (child))
     adw_preferences_group_add (self, GTK_WIDGET (child));
   else
     parent_buildable_iface->add_child (buildable, builder, child, type);
@@ -473,3 +487,60 @@ adw_preferences_group_remove (AdwPreferencesGroup *self,
   else
     ADW_CRITICAL_CANNOT_REMOVE_CHILD (self, child);
 }
+
+/**
+ * adw_preferences_group_add_header_suffix:
+ * @self: a `AdwPreferencesGroup`
+ * @child: the widget to add
+ *
+ * Adds a suffix to @self's header.
+ *
+ * Since: 1.0
+ */
+void
+adw_preferences_group_add_header_suffix (AdwPreferencesGroup *self,
+                                         GtkWidget           *child)
+{
+  AdwPreferencesGroupPrivate *priv;
+
+  g_return_if_fail (ADW_IS_PREFERENCES_GROUP (self));
+  g_return_if_fail (GTK_IS_WIDGET (child));
+
+  priv = adw_preferences_group_get_instance_private (self);
+
+  gtk_box_append (priv->header_suffix_box, child);
+  gtk_widget_set_visible (GTK_WIDGET (priv->header_suffix_box), TRUE);
+}
+
+/**
+ * adw_preferences_group_remove_header_suffix:
+ * @self: a `AdwPreferencesGroup`
+ * @child: the widget to remove
+ *
+ * Removes a suffix from @self's header.
+ *
+ * Since: 1.0
+ */
+void
+adw_preferences_group_remove_header_suffix (AdwPreferencesGroup *self,
+                                            GtkWidget           *child)
+{
+  AdwPreferencesGroupPrivate *priv;
+  GtkWidget *parent;
+
+  g_return_if_fail (ADW_IS_PREFERENCES_GROUP (self));
+  g_return_if_fail (GTK_IS_WIDGET (child));
+
+  priv = adw_preferences_group_get_instance_private (self);
+
+  parent = gtk_widget_get_parent (child);
+
+  if (parent == GTK_WIDGET (priv->header_suffix_box)) {
+    gtk_box_remove (priv->header_suffix_box, child);
+
+    gtk_widget_set_visible (GTK_WIDGET (priv->header_suffix_box),
+                            gtk_widget_get_first_child (GTK_WIDGET (priv->header_suffix_box)) != NULL);
+  } else {
+    ADW_CRITICAL_CANNOT_REMOVE_CHILD (self, child);
+  }
+}
diff --git a/src/adw-preferences-group.h b/src/adw-preferences-group.h
index 0339ddbf..5014551f 100644
--- a/src/adw-preferences-group.h
+++ b/src/adw-preferences-group.h
@@ -55,4 +55,11 @@ ADW_AVAILABLE_IN_ALL
 void adw_preferences_group_remove (AdwPreferencesGroup *self,
                                    GtkWidget           *child);
 
+ADW_AVAILABLE_IN_ALL
+void adw_preferences_group_add_header_suffix    (AdwPreferencesGroup *self,
+                                                 GtkWidget           *child);
+ADW_AVAILABLE_IN_ALL
+void adw_preferences_group_remove_header_suffix (AdwPreferencesGroup *self,
+                                                 GtkWidget           *child);
+
 G_END_DECLS
diff --git a/src/adw-preferences-group.ui b/src/adw-preferences-group.ui
index 78c9e66c..c4aeef1e 100644
--- a/src/adw-preferences-group.ui
+++ b/src/adw-preferences-group.ui
@@ -5,31 +5,50 @@
     <child>
       <object class="GtkBox" id="box">
         <property name="orientation">vertical</property>
+        <property name="vexpand">False</property>
         <child>
-          <object class="GtkLabel" id="title">
-            <property name="visible">False</property>
-            <property name="can_focus">False</property>
-            <property name="ellipsize">end</property>
-            <property name="use-markup">True</property>
-            <property name="xalign">0</property>
-            <style>
-              <class name="heading"/>
-              <!-- Matching elementary class. -->
-              <class name="h4"/>
-            </style>
-          </object>
-        </child>
-        <child>
-          <object class="GtkLabel" id="description">
-            <property name="visible">False</property>
-            <property name="can_focus">False</property>
-            <property name="use-markup">True</property>
-            <property name="wrap">True</property>
-            <property name="wrap-mode">word-char</property>
-            <property name="xalign">0</property>
-            <style>
-              <class name="dim-label"/>
-            </style>
+          <object class="GtkBox">
+            <child>
+              <object class="GtkBox">
+                <property name="hexpand">True</property>
+                <property name="orientation">vertical</property>
+                <child>
+                  <object class="GtkLabel" id="title">
+                    <property name="visible">False</property>
+                    <property name="can_focus">False</property>
+                    <property name="vexpand">True</property>
+                    <property name="ellipsize">end</property>
+                    <property name="use-markup">True</property>
+                    <property name="xalign">0</property>
+                    <style>
+                      <class name="heading"/>
+                      <!-- Matching elementary class. -->
+                      <class name="h4"/>
+                    </style>
+                  </object>
+                </child>
+                <child>
+                  <object class="GtkLabel" id="description">
+                    <property name="visible">False</property>
+                    <property name="can_focus">False</property>
+                    <property name="use-markup">True</property>
+                    <property name="wrap">True</property>
+                    <property name="wrap-mode">word-char</property>
+                    <property name="xalign">0</property>
+                    <style>
+                      <class name="dim-label"/>
+                    </style>
+                  </object>
+                </child>
+              </object>
+            </child>
+            <child>
+              <object class="GtkBox" id="header_suffix_box">
+                <property name="visible">False</property>
+                <property name="halign">end</property>
+                <property name="spacing">12</property>
+              </object>
+            </child>
           </object>
         </child>
         <child>
diff --git a/src/stylesheet/widgets/_preferences.scss b/src/stylesheet/widgets/_preferences.scss
index 15da2c22..08c6a480 100644
--- a/src/stylesheet/widgets/_preferences.scss
+++ b/src/stylesheet/widgets/_preferences.scss
@@ -4,8 +4,13 @@ preferencespage > scrolledwindow > viewport > clamp > box {
 }
 
 preferencesgroup > box {
+  // Add space between the title box and suffix box
+  > box:first-child {
+    border-spacing: 12px;
+  }
+
   // Add space between the description and the title.
-  > label:not(:first-child) {
+  > box > box > label:not(:first-child) {
     margin-top: 6px;
   }