clutter/box-layout: Deprecate :pack-start

A property for reversing the visible order of children is a bit odd.

It has also been unused by actual gnome-shell code since 2010, and the
somewhat related pack_start()/pack_end() API in GtkBox(Layout) is gone
in GTK4.

With that in mind, turn the property into a no-op and deprecate it,
so that it can be dropped next cycle.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2206>

clutter/clutter/clutter-box-layout.c

@@ -34,7 +34,6 @@
  *
  *  - all children are arranged on a single line
  *  - the axis used is controlled by the #ClutterBoxLayout:orientation property
- *  - the order of the packing is determined by the #ClutterBoxLayout:pack-start boolean property
  *  - each child will be allocated to its natural size or, if #ClutterActor:x-expand or
  *  #ClutterActor:y-expand are set, the available size
  *  - honours the #ClutterActor's #ClutterActor:x-align and #ClutterActor:y-align properties
@@ -53,6 +52,7 @@
 #include <math.h>
 
 #define CLUTTER_DISABLE_DEPRECATION_WARNINGS
+#include "deprecated/clutter-box-layout.h"
 #include "deprecated/clutter-container.h"
 
 #include "clutter-box-layout.h"
@@ -75,7 +75,6 @@ struct _ClutterBoxLayoutPrivate
 
   ClutterOrientation orientation;
 
-  guint is_pack_start  : 1;
   guint is_homogeneous : 1;
 };
 
@@ -764,18 +763,12 @@ clutter_box_layout_allocate (ClutterLayoutManager   *layout,
     {
       child_allocation.x1 = box->x1;
       child_allocation.x2 = MAX (1.0, box->x2);
-      if (priv->is_pack_start)
-        y = box->y2 - box->y1;
-      else
       y = box->y1;
     }
   else
     {
       child_allocation.y1 = box->y1;
       child_allocation.y2 = MAX (1.0, box->y2);
-      if (priv->is_pack_start)
-        x = box->x2 - box->x1;
-      else
       x = box->x1;
     }
 
@@ -828,18 +821,8 @@ clutter_box_layout_allocate (ClutterLayoutManager   *layout,
               child_allocation.y2 = child_allocation.y1 + sizes[i].minimum_size;
             }
 
-          if (priv->is_pack_start)
-            {
-              y -= child_size + priv->spacing;
-
-              child_allocation.y1 -= child_size;
-              child_allocation.y2 -= child_size;
-            }
-          else
-            {
           y += child_size + priv->spacing;
         }
-        }
       else /* CLUTTER_ORIENTATION_HORIZONTAL */
         {
           if (clutter_actor_needs_expand (child, priv->orientation))
@@ -853,17 +836,7 @@ clutter_box_layout_allocate (ClutterLayoutManager   *layout,
               child_allocation.x2 = child_allocation.x1 + sizes[i].minimum_size;
             }
 
-          if (priv->is_pack_start)
-            {
-              x -= child_size + priv->spacing;
-
-              child_allocation.x1 -= child_size;
-              child_allocation.x2 -= child_size;
-            }
-          else
-            {
           x += child_size + priv->spacing;
-            }
 
           if (is_rtl)
             {
@@ -939,7 +912,7 @@ clutter_box_layout_get_property (GObject    *gobject,
       break;
 
     case PROP_PACK_START:
-      g_value_set_boolean (value, priv->is_pack_start);
+      g_value_set_boolean (value, FALSE);
       break;
 
     default:
@@ -997,17 +970,14 @@ clutter_box_layout_class_init (ClutterBoxLayoutClass *klass)
   /**
    * ClutterBoxLayout:pack-start:
    *
-   * Whether the #ClutterBoxLayout should pack items at the start
+   * Deprecated: No longer has any effect
-   * or append them at the end
-   *
-   * Since: 1.2
    */
   obj_props[PROP_PACK_START] =
     g_param_spec_boolean ("pack-start",
                           P_("Pack Start"),
                           P_("Whether to pack items at the start of the box"),
                           FALSE,
-                          CLUTTER_PARAM_READWRITE);
+                          CLUTTER_PARAM_READWRITE | G_PARAM_DEPRECATED);
 
   /**
    * ClutterBoxLayout:spacing:
@@ -1035,7 +1005,6 @@ clutter_box_layout_init (ClutterBoxLayout *self)
 
   self->priv->orientation = CLUTTER_ORIENTATION_HORIZONTAL;
   self->priv->is_homogeneous = FALSE;
-  self->priv->is_pack_start = FALSE;
   self->priv->spacing = 0;
 
   self->priv->easing_mode = CLUTTER_EASE_OUT_CUBIC;
@@ -1218,50 +1187,25 @@ clutter_box_layout_get_homogeneous (ClutterBoxLayout *layout)
  * @pack_start: %TRUE if the @layout should pack children at the
  *   beginning of the layout
  *
- * Sets whether children of @layout should be laid out by appending
+ * Deprecated: No longer has any effect
- * them or by prepending them
- *
- * Since: 1.2
  */
 void
 clutter_box_layout_set_pack_start (ClutterBoxLayout *layout,
                                    gboolean          pack_start)
 {
-  ClutterBoxLayoutPrivate *priv;
-
-  g_return_if_fail (CLUTTER_IS_BOX_LAYOUT (layout));
-
-  priv = layout->priv;
-
-  if (priv->is_pack_start != pack_start)
-    {
-      ClutterLayoutManager *manager;
-
-      priv->is_pack_start = pack_start ? TRUE : FALSE;
-
-      manager = CLUTTER_LAYOUT_MANAGER (layout);
-
-      clutter_layout_manager_layout_changed (manager);
-
-      g_object_notify (G_OBJECT (layout), "pack-start");
-    }
 }
 
 /**
  * clutter_box_layout_get_pack_start:
  * @layout: a #ClutterBoxLayout
  *
- * Retrieves the value set using clutter_box_layout_set_pack_start()
+ * Return value: The value of the :pack-start property,
+ *   always %FALSE
  *
- * Return value: %TRUE if the #ClutterBoxLayout should pack children
+ * Deprecated: No longer has any effect
- *  at the beginning of the layout, and %FALSE otherwise
- *
- * Since: 1.2
  */
 gboolean
 clutter_box_layout_get_pack_start (ClutterBoxLayout *layout)
 {
-  g_return_val_if_fail (CLUTTER_IS_BOX_LAYOUT (layout), FALSE);
+  return FALSE;
-
-  return layout->priv->is_pack_start;
 }

clutter/clutter/clutter-box-layout.h

@@ -99,11 +99,6 @@ void                    clutter_box_layout_set_homogeneous      (ClutterBoxLayou
                                                                  gboolean             homogeneous);
 CLUTTER_EXPORT
 gboolean                clutter_box_layout_get_homogeneous      (ClutterBoxLayout    *layout);
-CLUTTER_EXPORT
-void                    clutter_box_layout_set_pack_start       (ClutterBoxLayout    *layout,
-                                                                 gboolean             pack_start);
-CLUTTER_EXPORT
-gboolean                clutter_box_layout_get_pack_start       (ClutterBoxLayout    *layout);
 
 G_END_DECLS
 

clutter/clutter/clutter-deprecated.h

@@ -3,6 +3,7 @@
 
 #define __CLUTTER_DEPRECATED_H_INSIDE__
 
+#include "deprecated/clutter-box-layout.h"
 #include "deprecated/clutter-container.h"
 
 #undef __CLUTTER_DEPRECATED_H_INSIDE__

clutter/clutter/deprecated/clutter-box-layout.h

@@ -0,0 +1,48 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2009  Intel Corporation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author:
+ *   Emmanuele Bassi <ebassi@linux.intel.com>
+ *
+ * Based on the NBTK NbtkBoxLayout actor by:
+ *   Thomas Wood <thomas.wood@intel.com>
+ */
+
+#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
+#error "Only <clutter/clutter.h> can be included directly."
+#endif
+
+#ifndef __CLUTTER_BOX_LAYOUT_DEPRECATED_H__
+#define __CLUTTER_BOX_LAYOUT_DEPRECATED_H__
+
+#include <clutter/clutter-box-layout.h>
+
+G_BEGIN_DECLS
+
+CLUTTER_DEPRECATED
+void             clutter_box_layout_set_pack_start       (ClutterBoxLayout    *layout,
+                                                          gboolean             pack_start);
+CLUTTER_DEPRECATED
+gboolean         clutter_box_layout_get_pack_start       (ClutterBoxLayout    *layout);
+
+G_END_DECLS
+
+#endif /* __CLUTTER_BOX_LAYOUT_DEPRECATED_H__ */
+

clutter/clutter/meson.build

@@ -227,6 +227,7 @@ clutter_nonintrospected_sources = [
 ]
 
 clutter_deprecated_headers = [
+  'deprecated/clutter-box-layout.h',
   'deprecated/clutter-container.h',
   'deprecated/clutter-timeline.h',
 ]