Improve handling of iconification of child frames (Bug#28611)

* src/frame.c (Ficonify_frame): Handle `iconify-child-frame' option.
(syms_of_frame): New symbols Qiconify_top_level and Qmake_invisible.
(iconify_child_frame): New option.
* lisp/cus-start.el (iconify-child-frame): Add customization
properties.
* doc/lispref/frames.texi (Child Frames): Describe new option
`iconify-child-frame'.  Don't index "top-level frame" twice.

doc/lispref/frames.texi

@@ -3076,15 +3076,14 @@ as long as the parameter is not changed or reset.  Technically, this
 makes the child frame's window-system window a child window of the
 parent frame's window-system window.
 
-@cindex top-level frame
 @cindex reparent frame
 @cindex nest frame
   The @code{parent-frame} parameter can be changed at any time.  Setting
 it to another frame @dfn{reparents} the child frame.  Setting it to
 another child frame makes the frame a @dfn{nested} child frame.  Setting
-it to @code{nil} restores the frame's status as a @dfn{top-level
+it to @code{nil} restores the frame's status as a top-level frame---a
-frame}---a frame whose window-system window is a child of its display's
+frame whose window-system window is a child of its display's root
-root window.
+window.
 
   Since child frames can be arbitrarily nested, a frame can be both a
 child and a parent frame.  Also, the relative roles of child and parent
@@ -3203,7 +3202,11 @@ a number of other ways as well.  Here we sketch a few of them:
 @item
 The semantics of maximizing and iconifying child frames is highly
 window-system dependent.  As a rule, applications should never invoke
-these operations for child frames.
+these operations for on frames.  By default, invoking
+@code{iconify-frame} on a child frame will try to iconify the top-level
+frame corresponding to that child frame instead.  To obtain a different
+behavior, users may customize the option @code{iconify-child-frame}
+described below.
 
 @item
 Raising, lowering and restacking child frames (@pxref{Raising and
@@ -3259,6 +3262,23 @@ frame in the largest empty area of an existing window.  This can be
 useful to avoid that a child frame obscures any text shown in that
 window.
 
+Customizing the following option can be useful to tweak the behavior of
+@code{iconify-frame} for child frames.
+
+@defvar iconify-child-frame
+This option tells Emacs how to proceed when it is asked to iconify a
+child frame.  If it is @code{nil}, @code{iconify-frame} will do nothing
+when invoked on a child frame.  If it is @code{iconify-top-level}, Emacs
+will try to iconify the top-level frame that is the ancestor of this
+child frame instead.  If it is @code{make-invisible}, Emacs will try to
+make this child frame invisible instead of iconifying it.
+
+Any other value means to try iconifying the child frame.  Since such an
+attempt may not be honored by all window managers and can even lead to
+making the child frame unresponsive to user actions, the default is to
+iconify the top level frame instead.
+@end defvar
+
 
 @node Mouse Tracking
 @section Mouse Tracking

lisp/cus-start.el

@@ -319,6 +319,13 @@ Leaving \"Default\" unchecked is equivalent with specifying a default of
 					    (const :tag "Always" t)
 					    (repeat (symbol :tag "Parameter")))
 					   "25.1")
+	     (iconify-child-frame frames
+				  (choice
+				   (const :tag "Do nothing" nil)
+                                   (const :tag "Iconify top level frame instead" iconify-top-level)
+                                   (const :tag "Make frame invisible instead" make-invisible)
+                                   (const :tag "Iconify" t))
+				  "26.1")
 	     (tooltip-reuse-hidden-frame tooltip boolean "26.1")
 	     ;; fringe.c
 	     (overflow-newline-into-fringe fringe boolean)

src/frame.c

@@ -2535,10 +2535,33 @@ displayed in the terminal.  */)
 DEFUN ("iconify-frame", Ficonify_frame, Siconify_frame,
        0, 1, "",
        doc: /* Make the frame FRAME into an icon.
-If omitted, FRAME defaults to the currently selected frame.  */)
+If omitted, FRAME defaults to the currently selected frame.
+
+If FRAME is a child frame, consult the variable `iconify-child-frame'
+for how to proceed.  */)
   (Lisp_Object frame)
 {
   struct frame *f = decode_live_frame (frame);
+  Lisp_Object parent = f->parent_frame;
+
+  if (!NILP (parent))
+    {
+      if (NILP (iconify_child_frame))
+	/* Do nothing.  */
+	return Qnil;
+      else if (EQ (iconify_child_frame, Qiconify_top_level))
+	{
+	  /* Iconify top level frame instead (the default).  */
+	  Ficonify_frame (parent);
+	  return Qnil;
+	}
+      else if (EQ (iconify_child_frame, Qmake_invisible))
+	{
+	  /* Make frame invisible instead.  */
+	  Fmake_frame_invisible (frame, Qnil);
+	  return Qnil;
+	}
+    }
 
   /* Don't allow minibuf_window to remain on an iconified frame.  */
   check_minibuf_window (frame, EQ (minibuf_window, selected_window));
@@ -5713,6 +5736,8 @@ syms_of_frame (void)
   DEFSYM (Qheight_only, "height-only");
   DEFSYM (Qleft_only, "left-only");
   DEFSYM (Qtop_only, "top-only");
+  DEFSYM (Qiconify_top_level, "iconify-top-level");
+  DEFSYM (Qmake_invisible, "make-invisible");
 
   {
     int i;
@@ -6016,6 +6041,21 @@ This variable is effective only with the X toolkit (and there only when
 Gtk+ tooltips are not used) and on Windows.  */);
   tooltip_reuse_hidden_frame = false;
 
+  DEFVAR_LISP ("iconify-child-frame", iconify_child_frame,
+	       doc: /* How to handle iconification of child frames.
+This variable tells Emacs how to proceed when it is asked to iconify a
+child frame.  If it is nil, `iconify-frame' will do nothing when invoked
+on a child frame.  If it is `iconify-top-level', Emacs will try to
+iconify the top level frame associated with this child frame instead.
+If it is `make-invisible', Emacs will try to make this child frame
+invisible instead.
+
+Any other value means to try iconifying the child frame.  Since such an
+attempt is not honored by all window managers and may even lead to
+making the child frame unresponsive to user actions, the default is to
+iconify the top level frame instead.  */);
+  iconify_child_frame = Qiconify_top_level;
+
   staticpro (&Vframe_list);
 
   defsubr (&Sframep);