clutter: Add stage method to iterate over active input

The stage has the knowledge about input that is ongoing over it
(incl. things like styli and touchpoints). Add an iterator API
for these devices/touchpoints, so they can be used for calculations
and heuristics in other places of the code.

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

clutter/clutter/clutter-stage.c

@@ -4567,3 +4567,42 @@ clutter_stage_notify_action_implicit_grab (ClutterStage         *self,
 
   remove_all_actors_from_chain (entry);
 }
+
+/**
+ * clutter_stage_pointing_input_foreach:
+ * @self: The stage
+ * @func: (scope call): Iterator function
+ * @user_data: user data
+ *
+ * Iterates over active input.
+ *
+ * Returns: %TRUE if the foreach function did not stop.
+ **/
+gboolean
+clutter_stage_pointing_input_foreach (ClutterStage                 *self,
+                                      ClutterStageInputForeachFunc  func,
+                                      gpointer                      user_data)
+{
+  ClutterStagePrivate *priv = self->priv;
+  GHashTableIter iter;
+  PointerDeviceEntry *entry;
+
+  g_return_val_if_fail (CLUTTER_IS_STAGE (self), FALSE);
+  g_return_val_if_fail (func != NULL, FALSE);
+
+  g_hash_table_iter_init (&iter, priv->pointer_devices);
+  while (g_hash_table_iter_next (&iter, NULL, (gpointer*) &entry))
+    {
+      if (!func (self, entry->device, entry->sequence, user_data))
+        return FALSE;
+    }
+
+  g_hash_table_iter_init (&iter, priv->touch_sequences);
+  while (g_hash_table_iter_next (&iter, NULL, (gpointer*) &entry))
+    {
+      if (!func (self, entry->device, entry->sequence, user_data))
+        return FALSE;
+    }
+
+  return TRUE;
+}

clutter/clutter/clutter-stage.h

@@ -243,4 +243,27 @@ ClutterGrab * clutter_stage_grab (ClutterStage *stage,
 CLUTTER_EXPORT
 ClutterActor * clutter_stage_get_grab_actor (ClutterStage *stage);
 
+/**
+ * ClutterStageInputForeachFunc:
+ * @stage: the stage
+ * @device: Active input device
+ * @sequence: Active sequence in @device, or %NULL
+ * @user_data: Data passed to clutter_stage_active_input_foreach()
+ *
+ * Iterator function for active input. Active input counts as any pointing
+ * device currently known to have some form of activity on the stage: Pointers
+ * leaning on a widget, tablet styli in proximity, active touchpoints...
+ *
+ * Returns: %TRUE to keep iterating. %FALSE to stop.
+ */
+typedef gboolean (*ClutterStageInputForeachFunc) (ClutterStage         *stage,
+                                                  ClutterInputDevice   *device,
+                                                  ClutterEventSequence *sequence,
+                                                  gpointer              user_data);
+
+CLUTTER_EXPORT
+gboolean clutter_stage_pointing_input_foreach (ClutterStage                 *self,
+                                               ClutterStageInputForeachFunc  func,
+                                               gpointer                      user_data);
+
 G_END_DECLS