[PATCH 0/4] Improvements for the -display option

[PATCH 0/4] Improvements for the -display option

[Thomas Huth]

Fix some oddities of the -display option, deprecate the -no-quit
option and improve the documentation.

Thomas Huth (4):
  softmmu/vl: Remove obsolete comment about the "frame" parameter
  ui: Fix the "-display sdl,window_close=..." parameter
  ui: Mark the '-no-quit' option as deprecated
  qemu-options: Improve the documentation of the -display options

 docs/system/deprecated.rst | 12 +++++++++
 qemu-options.hx            | 50 +++++++++++++++++++++++++++-----------
 softmmu/vl.c               | 11 ++++++---
 3 files changed, 56 insertions(+), 17 deletions(-)

-- 
2.27.0

[PATCH 1/4] softmmu/vl: Remove obsolete comment about the "frame" parameter

[Thomas Huth]

The frame parameter has been removed along with the support for
SDL 1.2.

Fixes: 09bd7ba9f5 ("Remove deprecated -no-frame option")
Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 softmmu/vl.c | 2 --
 1 file changed, 2 deletions(-)

diff --git a/softmmu/vl.c b/softmmu/vl.c
index d99e2cbdbf..cee6339580 100644
--- a/softmmu/vl.c
+++ b/softmmu/vl.c
@@ -1062,8 +1062,6 @@ static void parse_display(const char *p)
          * sdl DisplayType needs hand-crafted parser instead of
          * parse_display_qapi() due to some options not in
          * DisplayOptions, specifically:
-         *   - frame
-         *     Already deprecated.
          *   - ctrl_grab + alt_grab
          *     Not clear yet what happens to them long-term.  Should
          *     replaced by something better or deprecated and dropped.
-- 
2.27.0

[PATCH 2/4] ui: Fix the "-display sdl,window_close=..." parameter

[Thomas Huth]

According to the QAPI schema, there is a "-" and not a "_" between
"window" and "close", and we're also talking about "window-close"
in the long parameter description in qemu-options.hx, so we should
make sure that we rather use the variant with the "-" by default
instead of only allowing the one with the "_" here. The old way
still stays enabled for compatibility, but we deprecate it, so that
we can switch to a QAPIfied parameter one day more easily.

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 docs/system/deprecated.rst | 6 ++++++
 qemu-options.hx            | 2 +-
 softmmu/vl.c               | 7 ++++++-
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
index e2e0090878..bb624d3170 100644
--- a/docs/system/deprecated.rst
+++ b/docs/system/deprecated.rst
@@ -126,6 +126,12 @@ other options have been processed.  This will either have no effect (if
 if they were not given.  The property is therefore useless and should not be
 specified.
 
+``-display sdl,window_close=...`` (since 6.1)
+'''''''''''''''''''''''''''''''''''''''''''''
+
+Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of
+an underscore between "window" and "close").
+
 
 QEMU Machine Protocol (QMP) commands
 ------------------------------------
diff --git a/qemu-options.hx b/qemu-options.hx
index ba3ca9da1d..ae56fa4f28 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1784,7 +1784,7 @@ DEF("display", HAS_ARG, QEMU_OPTION_display,
 #endif
 #if defined(CONFIG_SDL)
     "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
-    "            [,window_close=on|off][,gl=on|core|es|off]\n"
+    "            [,window-close=on|off][,gl=on|core|es|off]\n"
 #endif
 #if defined(CONFIG_GTK)
     "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
diff --git a/softmmu/vl.c b/softmmu/vl.c
index cee6339580..36b761677d 100644
--- a/softmmu/vl.c
+++ b/softmmu/vl.c
@@ -1089,7 +1089,12 @@ static void parse_display(const char *p)
                 } else {
                     goto invalid_sdl_args;
                 }
-            } else if (strstart(opts, ",window_close=", &nextopt)) {
+            } else if (strstart(opts, ",window_close=", &nextopt) ||
+                       strstart(opts, ",window-close=", &nextopt)) {
+                if (strstart(opts, ",window_close=", NULL)) {
+                    warn_report("window_close with an underscore is deprecated,"
+                                " please use window-close instead.");
+                }
                 opts = nextopt;
                 dpy.has_window_close = true;
                 if (strstart(opts, "on", &nextopt)) {
-- 
2.27.0

[PATCH 3/4] ui: Mark the '-no-quit' option as deprecated

[Thomas Huth]

It's just a wrapper around the -display ...,window-close=off parameter,
and the name "no-quit" is rather confusing compared to "window-close"
(since there are still other means to quit the emulator), so we should
rather tell our users to use the "window-close" parameter instead.

While we're at it, update the documentation to state that
"-no-quit" is available for GTK, too, not only for SDL.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 docs/system/deprecated.rst | 6 ++++++
 qemu-options.hx            | 5 +++--
 softmmu/vl.c               | 2 ++
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
index bb624d3170..70e08baff6 100644
--- a/docs/system/deprecated.rst
+++ b/docs/system/deprecated.rst
@@ -132,6 +132,12 @@ specified.
 Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of
 an underscore between "window" and "close").
 
+``-no-quit`` (since 6.1)
+''''''''''''''''''''''''
+
+The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which
+should be used instead.
+
 
 QEMU Machine Protocol (QMP) commands
 ------------------------------------
diff --git a/qemu-options.hx b/qemu-options.hx
index ae56fa4f28..c862f1fa57 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1910,10 +1910,11 @@ SRST
 ERST
 
 DEF("no-quit", 0, QEMU_OPTION_no_quit,
-    "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
+    "-no-quit        disable SDL/GTK window close capability (deprecated)\n", QEMU_ARCH_ALL)
 SRST
 ``-no-quit``
-    Disable SDL window close capability.
+    Disable window close capability (SDL and GTK only). This option is
+    deprecated, please use ``-display ...,window-close=off`` instead.
 ERST
 
 DEF("sdl", 0, QEMU_OPTION_sdl,
diff --git a/softmmu/vl.c b/softmmu/vl.c
index 36b761677d..7dd2d72d0b 100644
--- a/softmmu/vl.c
+++ b/softmmu/vl.c
@@ -3237,6 +3237,8 @@ void qemu_init(int argc, char **argv, char **envp)
             case QEMU_OPTION_no_quit:
                 dpy.has_window_close = true;
                 dpy.window_close = false;
+                warn_report("-no-quit is deprecated, please use "
+                            "-display ...,window-close=off instead.");
                 break;
             case QEMU_OPTION_sdl:
 #ifdef CONFIG_SDL
-- 
2.27.0

[PATCH 4/4] qemu-options: Improve the documentation of the -display options

[Thomas Huth]

The sdl and gtk display options support more parameters than currently
documented. Also the "vnc" option got lost during a recent commit,
add it again.

Fixes: ddc717581c ("Add display suboptions to man pages")
Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 qemu-options.hx | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index c862f1fa57..8965dabc83 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1783,11 +1783,12 @@ DEF("display", HAS_ARG, QEMU_OPTION_display,
     "-display spice-app[,gl=on|off]\n"
 #endif
 #if defined(CONFIG_SDL)
-    "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
-    "            [,window-close=on|off][,gl=on|core|es|off]\n"
+    "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off][,gl=on|core|es|off]\n"
+    "            [,show-cursor=on|off][,window-close=on|off]\n"
 #endif
 #if defined(CONFIG_GTK)
-    "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
+    "-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]\n"
+    "            [,show-cursor=on|off][,window-close=on|off]\n"
 #endif
 #if defined(CONFIG_VNC)
     "-display vnc=<display>[,<optargs>]\n"
@@ -1824,17 +1825,37 @@ SRST
         application. The Spice server will redirect the serial consoles
         and QEMU monitors. (Since 4.0)
 
-    ``sdl[,window-close=on|off][,gl=on|core|es|off]``
-
+    ``sdl``
         Display video output via SDL (usually in a separate graphics
         window; see the SDL documentation for other possibilities).
+        Valid parameters are:
+
+        ``alt_grab=on|off`` : Use Control+Alt+Shift-g to toggle mouse grabbing
+
+        ``ctrl_grab=on|off`` : Use Right-Control-g to toggle mouse grabbing
+
+        ``gl=on|off|core|es`` : Use OpenGL for displaying
 
-    ``gtk[,grab-on-hover=on|off][,gl=on|off]``
+        ``show-cursor=on|off`` :  Force showing the mouse cursor
+
+        ``window-close=on|off`` : Allow to quit qemu with window close button
+
+    ``gtk``
         Display video output in a GTK window. This interface provides
         drop-down menus and other UI elements to configure and control
-        the VM during runtime.
+        the VM during runtime. Valid parameters are:
+
+        ``full-screen=on|off`` : Start in fullscreen mode
+
+        ``gl=on|off`` : Use OpenGL for displaying
 
-    ``curses [,charset=<encoding>]``
+        ``grab-on-hover=on|off`` : Grab keyboard input on mouse hover
+
+        ``show-cursor=on|off`` :  Force showing the mouse cursor
+
+        ``window-close=on|off`` : Allow to quit qemu with window close button
+
+    ``curses[,charset=<encoding>]``
         Display video output via curses. For graphics device models
         which support a text mode, QEMU can display this output using a
         curses/ncurses interface. Nothing is displayed when the graphics
@@ -1845,11 +1866,14 @@ SRST
         ``charset=CP850`` for IBM CP850 encoding. The default is
         ``CP437``.
 
-    ``egl-headless[,rendernode<file>]``
+    ``egl-headless[,rendernode=<file>]``
         Offload all OpenGL operations to a local DRI device. For any
         graphical display, this display needs to be paired with either
         VNC or SPICE displays.
 
+    ``vnc=<display>``
+        Start a VNC server on display <display>
+
     ``none``
         Do not display video output. The guest will still see an
         emulated graphics card, but its output will not be displayed to
@@ -1857,9 +1881,6 @@ SRST
         that it only affects what is done with video output; -nographic
         also changes the destination of the serial and parallel port
         data.
-
-
-
 ERST
 
 DEF("nographic", 0, QEMU_OPTION_nographic,
-- 
2.27.0

Re: [PATCH 0/4] Improvements for the -display option

[Paolo Bonzini]

On 30/06/21 18:32, Thomas Huth wrote:
> Fix some oddities of the -display option, deprecate the -no-quit
> option and improve the documentation.
> 
> Thomas Huth (4):
>    softmmu/vl: Remove obsolete comment about the "frame" parameter
>    ui: Fix the "-display sdl,window_close=..." parameter
>    ui: Mark the '-no-quit' option as deprecated
>    qemu-options: Improve the documentation of the -display options
> 
>   docs/system/deprecated.rst | 12 +++++++++
>   qemu-options.hx            | 50 +++++++++++++++++++++++++++-----------
>   softmmu/vl.c               | 11 ++++++---
>   3 files changed, 56 insertions(+), 17 deletions(-)
> 

Gerd is already on vacation, so I queued this one.

Paolo