stack: Add a function to get a sorted list of focus candidates

Use a static function if a window can be the default focus window, and use such
function to return a filtered list of the stack.

https://gitlab.gnome.org/GNOME/mutter/merge_requests/669

src/core/stack.h

@@ -308,6 +308,21 @@ MetaWindow* meta_stack_get_default_focus_window_at_point (MetaStack     *stack,
                                                           int            root_x,
                                                           int            root_y);
 
+/**
+ * meta_stack_get_default_focus_candidates:
+ * @stack: The stack to examine.
+ * @workspace: If not %NULL, only windows on this workspace will be
+ *             returned; otherwise all windows in the stack will be
+ *             returned.
+ *
+ * Returns all the focus candidate windows in the stack, in order.
+ *
+ * Returns: (transfer container) (element-type Meta.Window):
+ *     A #GList of #MetaWindow, in stacking order, honouring layers.
+ */
+GList *     meta_stack_get_default_focus_candidates (MetaStack     *stack,
+                                                     MetaWorkspace *workspace);
+
 /**
  * meta_stack_list_windows:
  * @stack: The stack to examine.