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

[Christopher Davis <christopherdavis src gnome org>]

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

    preferences-group: Add support for a header suffix
    
    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              | 86 +++++++++++++++++++++++++++++++-
 src/adw-preferences-group.h              |  6 +++
 src/adw-preferences-group.ui             | 68 +++++++++++++++++--------
 src/stylesheet/widgets/_preferences.scss | 11 ++--
 5 files changed, 149 insertions(+), 30 deletions(-)
---
diff --git a/demo/adw-demo-preferences-window.ui b/demo/adw-demo-preferences-window.ui
index b2614ee7..5c302b20 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>
+            <property name="header-suffix">
+              <object class="GtkButton">
+                <property name="label" translatable="yes">Suffix</property>
+                <property name="valign">center</property>
+              </object>
+            </property>
             <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 2290e863..db51c632 100644
--- a/src/adw-preferences-group.c
+++ b/src/adw-preferences-group.c
@@ -8,6 +8,7 @@
 
 #include "adw-preferences-group-private.h"
 
+#include "adw-bin.h"
 #include "adw-macros-private.h"
 #include "adw-preferences-row.h"
 #include "adw-widget-utils-private.h"
@@ -29,6 +30,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`.
@@ -43,6 +54,7 @@ typedef struct
   GtkListBox *listbox;
   GtkBox *listbox_box;
   GtkLabel *title;
+  AdwBin *header_suffix_bin;
 
   GListModel *rows;
 } AdwPreferencesGroupPrivate;
@@ -60,6 +72,7 @@ enum {
   PROP_0,
   PROP_DESCRIPTION,
   PROP_TITLE,
+  PROP_HEADER_SUFFIX,
   LAST_PROP,
 };
 
@@ -130,6 +143,9 @@ adw_preferences_group_get_property (GObject    *object,
   case PROP_TITLE:
     g_value_set_string (value, adw_preferences_group_get_title (self));
     break;
+  case PROP_HEADER_SUFFIX:
+    g_value_set_object (value, adw_preferences_group_get_header_suffix (self));
+    break;
   default:
     G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
   }
@@ -150,6 +166,9 @@ adw_preferences_group_set_property (GObject      *object,
   case PROP_TITLE:
     adw_preferences_group_set_title (self, g_value_get_string (value));
     break;
+  case PROP_HEADER_SUFFIX:
+    adw_preferences_group_set_header_suffix (self, g_value_get_object (value));
+    break;
   default:
     G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
   }
@@ -206,6 +225,19 @@ adw_preferences_group_class_init (AdwPreferencesGroupClass *klass)
                          "The title for this group of preferences",
                          "",
                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+  /**
+   * AdwPreferencesGroup:header-suffix: (attributes 
org.gtk.Property.get=adw_preferences_group_get_header_suffix 
org.gtk.Property.set=adw_preferences_group_set_header_suffix)
+   *
+   * The suffix for this group's header
+   *
+   * Since: 1.1
+   */
+  props[PROP_HEADER_SUFFIX] =
+    g_param_spec_object ("header-suffix",
+                         "Header Suffix",
+                         "The suffix for this group's header",
+                         GTK_TYPE_WIDGET,
+                         G_PARAM_READWRITE);
 
   g_object_class_install_properties (object_class, LAST_PROP, props);
 
@@ -218,6 +250,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_bin);
   gtk_widget_class_bind_template_callback (widget_class, listbox_keynav_failed_cb);
 }
 
@@ -248,7 +281,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_set_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);
@@ -478,3 +513,52 @@ adw_preferences_group_remove (AdwPreferencesGroup *self,
   else
     ADW_CRITICAL_CANNOT_REMOVE_CHILD (self, child);
 }
+
+/**
+ * adw_preferences_group_get_header_suffix:
+ * @self: a `AdwPreferencesGroup`
+ *
+ * Gets the suffix for @self's header.
+ *
+ * Returns: (nullable) (transfer none): the suffix for @self's header.
+ *
+ * Since: 1.1
+ */
+GtkWidget *
+adw_preferences_group_get_header_suffix (AdwPreferencesGroup *self)
+{
+  AdwPreferencesGroupPrivate *priv;
+
+  g_return_val_if_fail (ADW_IS_PREFERENCES_GROUP (self), NULL);
+
+  priv = adw_preferences_group_get_instance_private (self);
+
+  return adw_bin_get_child (priv->header_suffix_bin);
+}
+
+/**
+ * adw_preferences_group_set_header_suffix:
+ * @self: a `AdwPreferencesGroup`
+ * @child: the suffix to set
+ *
+ * Sets the suffix for @self's header.
+ *
+ * Since: 1.1
+ */
+void
+adw_preferences_group_set_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);
+
+  if (child == adw_bin_get_child (priv->header_suffix_bin))
+    return;
+
+  adw_bin_set_child (priv->header_suffix_bin, child);
+  gtk_widget_set_visible (GTK_WIDGET (priv->header_suffix_bin), child != NULL);
+}
diff --git a/src/adw-preferences-group.h b/src/adw-preferences-group.h
index 0339ddbf..39d6f885 100644
--- a/src/adw-preferences-group.h
+++ b/src/adw-preferences-group.h
@@ -55,4 +55,10 @@ ADW_AVAILABLE_IN_ALL
 void adw_preferences_group_remove (AdwPreferencesGroup *self,
                                    GtkWidget           *child);
 
+ADW_AVAILABLE_IN_ALL
+GtkWidget *adw_preferences_group_get_header_suffix (AdwPreferencesGroup *self);
+ADW_AVAILABLE_IN_ALL
+void       adw_preferences_group_set_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..926edad6 100644
--- a/src/adw-preferences-group.ui
+++ b/src/adw-preferences-group.ui
@@ -5,30 +5,54 @@
     <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>
+          <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>
+                <style>
+                  <class name="labels"/>
+                </style>
+              </object>
+            </child>
+            <child>
+              <object class="AdwBin" id="header_suffix_bin">
+                <property name="visible">False</property>
+                <property name="halign">end</property>
+              </object>
+            </child>
             <style>
-              <class name="dim-label"/>
+              <class name="header"/>
             </style>
           </object>
         </child>
diff --git a/src/stylesheet/widgets/_preferences.scss b/src/stylesheet/widgets/_preferences.scss
index 15da2c22..46777747 100644
--- a/src/stylesheet/widgets/_preferences.scss
+++ b/src/stylesheet/widgets/_preferences.scss
@@ -4,13 +4,12 @@ preferencespage > scrolledwindow > viewport > clamp > box {
 }
 
 preferencesgroup > box {
-  // Add space between the description and the title.
-  > label:not(:first-child) {
-    margin-top: 6px;
+  &, .header {
+    border-spacing: 12px;
   }
 
-  // Add space between the box and the labels.
-  > box:not(:first-child) {
-    margin-top: 12px;
+  // Add space between the description and the title.
+  .labels {
+    border-spacing: 6px;
   }
 }