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

[Christopher Davis <christopherdavis src gnome org>]

commit e7d8acf63fae1b84f72b47249b6ba6669816800f
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              | 139 ++++++++++++++++++++++++++++++-
 src/adw-preferences-group.h              |   6 ++
 src/adw-preferences-group.ui             |  61 +++++++++-----
 src/stylesheet/widgets/_preferences.scss |  14 ++--
 5 files changed, 212 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..181329ea 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>
+                    <property name="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>
+                    </property>
+                    <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..a4187513 100644
--- a/src/adw-preferences-group.c
+++ b/src/adw-preferences-group.c
@@ -32,8 +32,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 description.
  *
  * ## CSS nodes
  *
@@ -53,6 +57,8 @@ typedef struct
   GtkListBox *listbox;
   GtkBox *listbox_box;
   GtkLabel *title;
+  GtkBox *header_box;
+  GtkWidget *header_suffix;
 
   GListModel *rows;
 } AdwPreferencesGroupPrivate;
@@ -70,6 +76,7 @@ enum {
   PROP_0,
   PROP_DESCRIPTION,
   PROP_TITLE,
+  PROP_HEADER_SUFFIX,
   LAST_PROP,
 };
 
@@ -109,6 +116,45 @@ update_listbox_visibility (AdwPreferencesGroup *self)
                           g_list_model_get_n_items (priv->rows) > 0);
 }
 
+static void
+update_header_visibility (AdwPreferencesGroup *self)
+{
+  AdwPreferencesGroupPrivate *priv = adw_preferences_group_get_instance_private (self);
+
+  gtk_widget_set_visible (GTK_WIDGET (priv->header_box),
+                          gtk_widget_get_visible (GTK_WIDGET (priv->title)) ||
+                          gtk_widget_get_visible (GTK_WIDGET (priv->description)) ||
+                          priv->header_suffix != NULL);
+}
+
+static gboolean
+is_single_line (AdwPreferencesGroup *self)
+{
+  AdwPreferencesGroupPrivate *priv = adw_preferences_group_get_instance_private (self);
+
+  if (gtk_widget_get_visible (GTK_WIDGET (priv->description)))
+    return FALSE;
+
+  if (priv->header_suffix)
+    return TRUE;
+
+  if (gtk_widget_get_visible (GTK_WIDGET (priv->title)))
+    return TRUE;
+
+  return FALSE;
+}
+
+static void
+update_style (AdwPreferencesGroup *self)
+{
+  AdwPreferencesGroupPrivate *priv = adw_preferences_group_get_instance_private (self);
+
+  if (is_single_line (self))
+    gtk_widget_add_css_class (GTK_WIDGET (priv->header_box), "single-line");
+  else
+    gtk_widget_remove_css_class (GTK_WIDGET (priv->header_box), "single-line");
+}
+
 static gboolean
 listbox_keynav_failed_cb (AdwPreferencesGroup *self,
                           GtkDirectionType     direction)
@@ -140,6 +186,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 +209,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 +268,21 @@ 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 header suffix widget.
+   *
+   * Displayed above the list, next to the title and description. Suffixes are commonly used to show a 
button or a spinner for the whole group.
+   *
+   * 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 +293,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");
@@ -243,6 +311,8 @@ adw_preferences_group_init (AdwPreferencesGroup *self)
   update_description_visibility (self);
   update_title_visibility (self);
   update_listbox_visibility (self);
+  update_header_visibility (self);
+  update_style (self);
 
   priv->rows = gtk_widget_observe_children (GTK_WIDGET (priv->listbox));
 
@@ -260,7 +330,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 && GTK_IS_WIDGET (child))
+    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);
@@ -334,6 +406,8 @@ adw_preferences_group_set_title (AdwPreferencesGroup *self,
 
   gtk_label_set_label (priv->title, title);
   update_title_visibility (self);
+  update_header_visibility (self);
+  update_style (self);
 
   g_object_notify_by_pspec (G_OBJECT (self), props[PROP_TITLE]);
 }
@@ -384,6 +458,8 @@ adw_preferences_group_set_description (AdwPreferencesGroup *self,
 
   gtk_label_set_label (priv->description, description);
   update_description_visibility (self);
+  update_header_visibility (self);
+  update_style (self);
 
   g_object_notify_by_pspec (G_OBJECT (self), props[PROP_DESCRIPTION]);
 }
@@ -490,3 +566,60 @@ 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`
+ * @suffix (nullable): the suffix to set
+ *
+ * Sets the suffix for @self's header.
+ *
+ * Since: 1.1
+ */
+void
+adw_preferences_group_set_header_suffix (AdwPreferencesGroup *self,
+                                         GtkWidget           *suffix)
+{
+  AdwPreferencesGroupPrivate *priv;
+
+  g_return_if_fail (ADW_IS_PREFERENCES_GROUP (self));
+  g_return_if_fail (suffix == NULL || GTK_IS_WIDGET (suffix));
+
+  priv = adw_preferences_group_get_instance_private (self);
+
+  if (suffix == priv->header_suffix)
+    return;
+
+  if (priv->header_suffix)
+    gtk_box_remove (priv->header_box, priv->header_suffix);
+
+  priv->header_suffix = suffix;
+
+  if (priv->header_suffix)
+    gtk_box_append (priv->header_box, priv->header_suffix);
+
+  update_header_visibility (self);
+  update_style (self);
+}
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..7996d584 100644
--- a/src/stylesheet/widgets/_preferences.scss
+++ b/src/stylesheet/widgets/_preferences.scss
@@ -4,13 +4,15 @@ preferencespage > scrolledwindow > viewport > clamp > box {
 }
 
 preferencesgroup > box {
-  // Add space between the description and the title.
-  > label:not(:first-child) {
-    margin-top: 6px;
+  &, .labels {
+    border-spacing: 6px;
   }
 
-  // Add space between the box and the labels.
-  > box:not(:first-child) {
-    margin-top: 12px;
+  > box.header:not(.single-line) {
+    margin-bottom: 6px;
+  }
+
+  > box.single-line {
+    min-height: 34px;
   }
 }