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

[Christopher Davis <christopherdavis src gnome org>]

commit 6c2652d3fc576ed0c11f6194d99ba42b0593b666
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/pages/lists/adw-demo-page-lists.ui  | 23 ++++++++
 src/adw-preferences-group.c              | 90 ++++++++++++++++++++++++++++++--
 src/adw-preferences-group.h              |  6 +++
 src/adw-preferences-group.ui             | 61 ++++++++++++++--------
 src/stylesheet/widgets/_preferences.scss | 11 ++--
 5 files changed, 160 insertions(+), 31 deletions(-)
---
diff --git a/demo/pages/lists/adw-demo-page-lists.ui b/demo/pages/lists/adw-demo-page-lists.ui
index 637f120e..e50faaf4 100644
--- a/demo/pages/lists/adw-demo-page-lists.ui
+++ b/demo/pages/lists/adw-demo-page-lists.ui
@@ -159,6 +159,29 @@
                     </child>
                   </object>
                 </child>
+                <child>
+                  <object class="AdwPreferencesGroup">
+                    <property name="title" translatable="yes">Groups with Suffix</property>
+                    <child type="header-suffix">
+                      <object class="GtkButton">
+                        <property name="child">
+                          <object class="AdwButtonContent">
+                            <property name="icon-name">list-add-symbolic</property>
+                            <property name="label" translatable="yes">Suffix</property>
+                          </object>
+                        </property>
+                        <style>
+                          <class name="flat"/>
+                        </style>
+                      </object>
+                    </child>
+                    <child>
+                      <object class="AdwActionRow">
+                        <property name="title" translatable="yes">Groups can have a header suffix.</property>
+                      </object>
+                    </child>
+                  </object>
+                </child>
               </object>
             </property>
           </object>
diff --git a/src/adw-preferences-group.c b/src/adw-preferences-group.c
index 23a2ffa6..59dda565 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"
@@ -32,8 +33,12 @@
  * ## AdwPreferencesGroup as GtkBuildable
  *
  * The `AdwPreferencesGroup` implementation of the [iface@Gtk.Buildable] interface
- * will add [class@PreferencesRow]s to the group's list. If a child is not a
- * [class@PreferencesRow] the child is added to a box below the list.
+ * 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`, the child
+ * is set as the suffix on the end of the title and subtitle.
  *
  * ## CSS nodes
  *
@@ -53,6 +58,8 @@ typedef struct
   GtkListBox *listbox;
   GtkBox *listbox_box;
   GtkLabel *title;
+  GtkBox *header_box;
+  GtkWidget *header_suffix;
 
   GListModel *rows;
 } AdwPreferencesGroupPrivate;
@@ -70,6 +77,7 @@ enum {
   PROP_0,
   PROP_DESCRIPTION,
   PROP_TITLE,
+  PROP_HEADER_SUFFIX,
   LAST_PROP,
 };
 
@@ -140,6 +148,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);
   }
@@ -160,6 +171,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);
   }
@@ -216,6 +230,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);
 
@@ -226,6 +253,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_box);
   gtk_widget_class_bind_template_callback (widget_class, listbox_keynav_failed_cb);
 
   gtk_widget_class_set_css_name (widget_class, "preferencesgroup");
@@ -260,7 +288,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);
@@ -490,3 +520,57 @@ 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 priv->header_suffix;
+}
+
+/**
+ * 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 == priv->header_suffix)
+    return;
+
+  if (priv->header_suffix)
+    gtk_box_remove (priv->header_box, priv->header_suffix);
+
+  if (child) {
+    gtk_box_append (priv->header_box, child);
+    priv->header_suffix = child;
+  }
+}
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..2714ba60 100644
--- a/src/adw-preferences-group.ui
+++ b/src/adw-preferences-group.ui
@@ -5,30 +5,47 @@
     <child>
       <object class="GtkBox" id="box">
         <property name="orientation">vertical</property>
+        <property name="hexpand">False</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" id="header_box">
+            <child>
+              <object class="GtkBox">
+                <property name="hexpand">True</property>
+                <property name="valign">center</property>
+                <property name="orientation">vertical</property>
+                <child>
+                  <object class="GtkLabel" id="title">
+                    <property name="visible">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="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>
             <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;
   }
 }