[PATCH RFC v3 0/1] the org.qemu.Display1.UIInfo interface design

[PATCH RFC v3 0/1] the org.qemu.Display1.UIInfo interface design

[Chengyang Zhu]

Currently, the `SetUIInfo` method cannot set a refresh rate.
Simply adding a refresh_rate argument would break the method signature.

This RFC adds the `UIInfo` interface containing
  * properties as staged display settings.
  * property `Supported` indicating whether console UI info is supported.
  * the method `Apply` applying staged settings.
  * the method `Reload` reloading settings from the console.

Changes since v2:
  * added a read-only bool property "Supported" on the interface.
  * switched to typesafe getter & setter.
  * documented each property/method individually.

Test results:
  * qemu:qtest-x86_64/dbus-display-test passed
  * qemu:qtest-x86_64/dbus-vmstate-test passed
  * qemu:qtest-x86_64/dbus-vnc-test SKIP
  * manually created a virtual machine
    and successfully set its refresh rate and resolution via `UIInfo`
  * sphinxdocs build passed

Chengyang Zhu (1):
  ui/dbus: add org.qemu.Display1.UIInfo interface

 ui/dbus-console.c    | 71 ++++++++++++++++++++++++++++++++++++++
 ui/dbus-display1.xml | 81 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 152 insertions(+)

-- 
2.55.0

[PATCH RFC v3 1/1] ui/dbus: add org.qemu.Display1.UIInfo interface

[Chengyang Zhu]

Currently, the SetUIInfo method cannot set a refresh rate.
Simply adding a refresh_rate argument would break the method signature.

This patch adds the UIInfo interface containing
  * properties as staged display settings.
  * property `Supported` indicating whether console UI info is supported.
  * the method `Apply` applying staged settings.
  * the method `Reload` reloading settings from the console.

Signed-off-by: Chengyang Zhu <colazcyg@gmail.com>
---
 ui/dbus-console.c    | 71 ++++++++++++++++++++++++++++++++++++++
 ui/dbus-display1.xml | 81 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 152 insertions(+)

diff --git a/ui/dbus-console.c b/ui/dbus-console.c
index e1ac06814b..2c71272a1c 100644
--- a/ui/dbus-console.c
+++ b/ui/dbus-console.c
@@ -55,6 +55,8 @@ struct _DBusDisplayConsole {
     guint last_x;
     guint last_y;
     Notifier mouse_mode_notifier;
+
+    QemuDBusDisplay1UIInfo *iface_ui_info;
 };
 
 G_DEFINE_TYPE(DBusDisplayConsole,
@@ -155,6 +157,7 @@ dbus_display_console_dispose(GObject *object)
     qemu_input_led_notifier_remove(&ddc->led_notifier);
     qemu_console_unregister_listener(&ddc->dcl);
     qemu_remove_mouse_mode_change_notifier(&ddc->mouse_mode_notifier);
+    g_clear_object(&ddc->iface_ui_info);
     g_clear_object(&ddc->iface_touch);
     g_clear_object(&ddc->iface_mouse);
     g_clear_object(&ddc->iface_kbd);
@@ -528,6 +531,63 @@ dbus_mouse_mode_change(Notifier *notify, void *data)
     dbus_mouse_update_is_absolute(ddc);
 }
 
+static gboolean
+dbus_ui_info_reload(DBusDisplayConsole *ddc,
+                    GDBusMethodInvocation *invocation)
+{
+    if (!qemu_console_ui_info_supported(ddc->dcl.con)) {
+        g_dbus_method_invocation_return_error(invocation,
+                                              DBUS_DISPLAY_ERROR,
+                                              DBUS_DISPLAY_ERROR_UNSUPPORTED,
+                                              "UIInfo is not supported");
+        return DBUS_METHOD_INVOCATION_HANDLED;
+    }
+
+    QemuUIInfo ui_info = *qemu_console_get_ui_info(ddc->dcl.con);
+
+    qemu_dbus_display1_uiinfo_set_width_mm(ddc->iface_ui_info,
+                                           ui_info.width_mm);
+    qemu_dbus_display1_uiinfo_set_height_mm(ddc->iface_ui_info,
+                                            ui_info.height_mm);
+    qemu_dbus_display1_uiinfo_set_xoff(ddc->iface_ui_info, ui_info.xoff);
+    qemu_dbus_display1_uiinfo_set_yoff(ddc->iface_ui_info, ui_info.yoff);
+    qemu_dbus_display1_uiinfo_set_width(ddc->iface_ui_info, ui_info.width);
+    qemu_dbus_display1_uiinfo_set_height(ddc->iface_ui_info, ui_info.height);
+    qemu_dbus_display1_uiinfo_set_refresh_rate(ddc->iface_ui_info,
+                                               ui_info.refresh_rate);
+
+    qemu_dbus_display1_uiinfo_complete_reload(ddc->iface_ui_info, invocation);
+    return DBUS_METHOD_INVOCATION_HANDLED;
+}
+
+static gboolean
+dbus_ui_info_apply(DBusDisplayConsole *ddc,
+                   GDBusMethodInvocation *invocation)
+{
+    if (!qemu_console_ui_info_supported(ddc->dcl.con)) {
+        g_dbus_method_invocation_return_error(invocation,
+                                              DBUS_DISPLAY_ERROR,
+                                              DBUS_DISPLAY_ERROR_UNSUPPORTED,
+                                              "UIInfo is not supported");
+        return DBUS_METHOD_INVOCATION_HANDLED;
+    }
+
+    QemuUIInfo ui_info = {
+        .width_mm = qemu_dbus_display1_uiinfo_get_width_mm(ddc->iface_ui_info),
+        .height_mm = qemu_dbus_display1_uiinfo_get_height_mm(ddc->iface_ui_info),
+        .xoff = qemu_dbus_display1_uiinfo_get_xoff(ddc->iface_ui_info),
+        .yoff = qemu_dbus_display1_uiinfo_get_yoff(ddc->iface_ui_info),
+        .width = qemu_dbus_display1_uiinfo_get_width(ddc->iface_ui_info),
+        .height = qemu_dbus_display1_uiinfo_get_height(ddc->iface_ui_info),
+        .refresh_rate = qemu_dbus_display1_uiinfo_get_refresh_rate(ddc->iface_ui_info)
+    };
+
+    qemu_console_set_ui_info(ddc->dcl.con, &ui_info, false);
+    qemu_dbus_display1_uiinfo_complete_apply(ddc->iface_ui_info, invocation);
+
+    return DBUS_METHOD_INVOCATION_HANDLED;
+}
+
 int dbus_display_console_get_index(DBusDisplayConsole *ddc)
 {
     return qemu_console_get_index(ddc->dcl.con);
@@ -550,6 +610,7 @@ dbus_display_console_new(DBusDisplay *display, QemuConsole *con)
         "org.qemu.Display1.Keyboard",
         "org.qemu.Display1.Mouse",
         "org.qemu.Display1.MultiTouch",
+        "org.qemu.Display1.UIInfo",
         NULL
     };
 
@@ -626,5 +687,15 @@ dbus_display_console_new(DBusDisplay *display, QemuConsole *con)
     qemu_add_mouse_mode_change_notifier(&ddc->mouse_mode_notifier);
     dbus_mouse_update_is_absolute(ddc);
 
+    ddc->iface_ui_info = qemu_dbus_display1_uiinfo_skeleton_new();
+    qemu_dbus_display1_uiinfo_set_supported(ddc->iface_ui_info,
+        qemu_console_ui_info_supported(ddc->dcl.con));
+    g_object_connect(ddc->iface_ui_info,
+        "swapped-signal::handle-reload", dbus_ui_info_reload, ddc,
+        "swapped-signal::handle-apply", dbus_ui_info_apply, ddc,
+        NULL);
+    g_dbus_object_skeleton_add_interface(G_DBUS_OBJECT_SKELETON(ddc),
+        G_DBUS_INTERFACE_SKELETON(ddc->iface_ui_info));
+
     return ddc;
 }
diff --git a/ui/dbus-display1.xml b/ui/dbus-display1.xml
index d96bae2ed6..2a8a8563ee 100644
--- a/ui/dbus-display1.xml
+++ b/ui/dbus-display1.xml
@@ -1159,4 +1159,85 @@
     -->
     <property name="Encoding" type="s" access="read"/>
   </interface>
+
+  <!--
+      org.qemu.Display1.UIInfo:
+
+      This interface is implemented on
+      ``/org/qemu/Display1/Console_$id`` (see
+      :dbus:iface:`~org.qemu.Display1.Console`).
+  -->
+  <interface name="org.qemu.Display1.UIInfo">
+    <!--
+        Supported:
+
+        Whether console UI info is supported.
+    -->
+    <property name="Supported" type="b" access="read"/>
+
+    <!--
+        WidthMm:
+
+        The physical display width in millimeters.
+    -->
+    <property name="WidthMm" type="q" access="readwrite"/>
+
+    <!--
+        HeightMm:
+
+        The physical display height in millimeters.
+    -->
+    <property name="HeightMm" type="q" access="readwrite"/>
+
+    <!--
+        XOff:
+
+        The horizontal offset in pixels.
+    -->
+    <property name="XOff" type="i" access="readwrite"/>
+
+    <!--
+        YOff:
+
+        The vertical offset in pixels.
+    -->
+    <property name="YOff" type="i" access="readwrite"/>
+
+    <!--
+        Width:
+
+        The console width in pixels.
+    -->
+    <property name="Width" type="u" access="readwrite"/>
+
+    <!--
+        Height:
+
+        The console height in pixels.
+    -->
+    <property name="Height" type="u" access="readwrite"/>
+
+    <!--
+        RefreshRate:
+
+        The display refresh rate in millihertz.
+    -->
+    <property name="RefreshRate" type="u" access="readwrite"/>
+
+    <!--
+        Reload:
+
+        Set the staged properties to the state of the console display.
+    -->
+    <method name="Reload">
+    </method>
+
+    <!--
+        Apply:
+
+        Apply the staged properties to the console display.
+    -->
+    <method name="Apply">
+    </method>
+  </interface>
 </node>
-- 
2.55.0

Re: [PATCH RFC v3 1/1] ui/dbus: add org.qemu.Display1.UIInfo interface

[Marc-André Lureau]

Hi

On Tue, Aug 18, 2026 at 5:48 PM Chengyang Zhu <colazcyg@gmail.com> wrote:
>
> Currently, the SetUIInfo method cannot set a refresh rate.
> Simply adding a refresh_rate argument would break the method signature.
>
> This patch adds the UIInfo interface containing
>   * properties as staged display settings.
>   * property `Supported` indicating whether console UI info is supported.
>   * the method `Apply` applying staged settings.
>   * the method `Reload` reloading settings from the console.
>
> Signed-off-by: Chengyang Zhu <colazcyg@gmail.com>

That looks good to me. I am aware of concerns about refresh_rate unit
(https://gitlab.gnome.org/GNOME/libmks/-/merge_requests/53#note_2834466),
but I guess we will address this in due course

Christian, does this new interface look right to you?

thanks

> ---
>  ui/dbus-console.c    | 71 ++++++++++++++++++++++++++++++++++++++
>  ui/dbus-display1.xml | 81 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 152 insertions(+)
>
> diff --git a/ui/dbus-console.c b/ui/dbus-console.c
> index e1ac06814b..2c71272a1c 100644
> --- a/ui/dbus-console.c
> +++ b/ui/dbus-console.c
> @@ -55,6 +55,8 @@ struct _DBusDisplayConsole {
>      guint last_x;
>      guint last_y;
>      Notifier mouse_mode_notifier;
> +
> +    QemuDBusDisplay1UIInfo *iface_ui_info;
>  };
>
>  G_DEFINE_TYPE(DBusDisplayConsole,
> @@ -155,6 +157,7 @@ dbus_display_console_dispose(GObject *object)
>      qemu_input_led_notifier_remove(&ddc->led_notifier);
>      qemu_console_unregister_listener(&ddc->dcl);
>      qemu_remove_mouse_mode_change_notifier(&ddc->mouse_mode_notifier);
> +    g_clear_object(&ddc->iface_ui_info);
>      g_clear_object(&ddc->iface_touch);
>      g_clear_object(&ddc->iface_mouse);
>      g_clear_object(&ddc->iface_kbd);
> @@ -528,6 +531,63 @@ dbus_mouse_mode_change(Notifier *notify, void *data)
>      dbus_mouse_update_is_absolute(ddc);
>  }
>
> +static gboolean
> +dbus_ui_info_reload(DBusDisplayConsole *ddc,
> +                    GDBusMethodInvocation *invocation)
> +{
> +    if (!qemu_console_ui_info_supported(ddc->dcl.con)) {
> +        g_dbus_method_invocation_return_error(invocation,
> +                                              DBUS_DISPLAY_ERROR,
> +                                              DBUS_DISPLAY_ERROR_UNSUPPORTED,
> +                                              "UIInfo is not supported");
> +        return DBUS_METHOD_INVOCATION_HANDLED;
> +    }
> +
> +    QemuUIInfo ui_info = *qemu_console_get_ui_info(ddc->dcl.con);
> +
> +    qemu_dbus_display1_uiinfo_set_width_mm(ddc->iface_ui_info,
> +                                           ui_info.width_mm);
> +    qemu_dbus_display1_uiinfo_set_height_mm(ddc->iface_ui_info,
> +                                            ui_info.height_mm);
> +    qemu_dbus_display1_uiinfo_set_xoff(ddc->iface_ui_info, ui_info.xoff);
> +    qemu_dbus_display1_uiinfo_set_yoff(ddc->iface_ui_info, ui_info.yoff);
> +    qemu_dbus_display1_uiinfo_set_width(ddc->iface_ui_info, ui_info.width);
> +    qemu_dbus_display1_uiinfo_set_height(ddc->iface_ui_info, ui_info.height);
> +    qemu_dbus_display1_uiinfo_set_refresh_rate(ddc->iface_ui_info,
> +                                               ui_info.refresh_rate);
> +
> +    qemu_dbus_display1_uiinfo_complete_reload(ddc->iface_ui_info, invocation);
> +    return DBUS_METHOD_INVOCATION_HANDLED;
> +}
> +
> +static gboolean
> +dbus_ui_info_apply(DBusDisplayConsole *ddc,
> +                   GDBusMethodInvocation *invocation)
> +{
> +    if (!qemu_console_ui_info_supported(ddc->dcl.con)) {
> +        g_dbus_method_invocation_return_error(invocation,
> +                                              DBUS_DISPLAY_ERROR,
> +                                              DBUS_DISPLAY_ERROR_UNSUPPORTED,
> +                                              "UIInfo is not supported");
> +        return DBUS_METHOD_INVOCATION_HANDLED;
> +    }
> +
> +    QemuUIInfo ui_info = {
> +        .width_mm = qemu_dbus_display1_uiinfo_get_width_mm(ddc->iface_ui_info),
> +        .height_mm = qemu_dbus_display1_uiinfo_get_height_mm(ddc->iface_ui_info),
> +        .xoff = qemu_dbus_display1_uiinfo_get_xoff(ddc->iface_ui_info),
> +        .yoff = qemu_dbus_display1_uiinfo_get_yoff(ddc->iface_ui_info),
> +        .width = qemu_dbus_display1_uiinfo_get_width(ddc->iface_ui_info),
> +        .height = qemu_dbus_display1_uiinfo_get_height(ddc->iface_ui_info),
> +        .refresh_rate = qemu_dbus_display1_uiinfo_get_refresh_rate(ddc->iface_ui_info)
> +    };
> +
> +    qemu_console_set_ui_info(ddc->dcl.con, &ui_info, false);
> +    qemu_dbus_display1_uiinfo_complete_apply(ddc->iface_ui_info, invocation);
> +
> +    return DBUS_METHOD_INVOCATION_HANDLED;
> +}
> +
>  int dbus_display_console_get_index(DBusDisplayConsole *ddc)
>  {
>      return qemu_console_get_index(ddc->dcl.con);
> @@ -550,6 +610,7 @@ dbus_display_console_new(DBusDisplay *display, QemuConsole *con)
>          "org.qemu.Display1.Keyboard",
>          "org.qemu.Display1.Mouse",
>          "org.qemu.Display1.MultiTouch",
> +        "org.qemu.Display1.UIInfo",
>          NULL
>      };
>
> @@ -626,5 +687,15 @@ dbus_display_console_new(DBusDisplay *display, QemuConsole *con)
>      qemu_add_mouse_mode_change_notifier(&ddc->mouse_mode_notifier);
>      dbus_mouse_update_is_absolute(ddc);
>
> +    ddc->iface_ui_info = qemu_dbus_display1_uiinfo_skeleton_new();
> +    qemu_dbus_display1_uiinfo_set_supported(ddc->iface_ui_info,
> +        qemu_console_ui_info_supported(ddc->dcl.con));
> +    g_object_connect(ddc->iface_ui_info,
> +        "swapped-signal::handle-reload", dbus_ui_info_reload, ddc,
> +        "swapped-signal::handle-apply", dbus_ui_info_apply, ddc,
> +        NULL);
> +    g_dbus_object_skeleton_add_interface(G_DBUS_OBJECT_SKELETON(ddc),
> +        G_DBUS_INTERFACE_SKELETON(ddc->iface_ui_info));
> +
>      return ddc;
>  }
> diff --git a/ui/dbus-display1.xml b/ui/dbus-display1.xml
> index d96bae2ed6..2a8a8563ee 100644
> --- a/ui/dbus-display1.xml
> +++ b/ui/dbus-display1.xml
> @@ -1159,4 +1159,85 @@
>      -->
>      <property name="Encoding" type="s" access="read"/>
>    </interface>
> +
> +  <!--
> +      org.qemu.Display1.UIInfo:
> +
> +      This interface is implemented on
> +      ``/org/qemu/Display1/Console_$id`` (see
> +      :dbus:iface:`~org.qemu.Display1.Console`).
> +  -->
> +  <interface name="org.qemu.Display1.UIInfo">
> +    <!--
> +        Supported:
> +
> +        Whether console UI info is supported.
> +    -->
> +    <property name="Supported" type="b" access="read"/>
> +
> +    <!--
> +        WidthMm:
> +
> +        The physical display width in millimeters.
> +    -->
> +    <property name="WidthMm" type="q" access="readwrite"/>
> +
> +    <!--
> +        HeightMm:
> +
> +        The physical display height in millimeters.
> +    -->
> +    <property name="HeightMm" type="q" access="readwrite"/>
> +
> +    <!--
> +        XOff:
> +
> +        The horizontal offset in pixels.
> +    -->
> +    <property name="XOff" type="i" access="readwrite"/>
> +
> +    <!--
> +        YOff:
> +
> +        The vertical offset in pixels.
> +    -->
> +    <property name="YOff" type="i" access="readwrite"/>
> +
> +    <!--
> +        Width:
> +
> +        The console width in pixels.
> +    -->
> +    <property name="Width" type="u" access="readwrite"/>
> +
> +    <!--
> +        Height:
> +
> +        The console height in pixels.
> +    -->
> +    <property name="Height" type="u" access="readwrite"/>
> +
> +    <!--
> +        RefreshRate:
> +
> +        The display refresh rate in millihertz.
> +    -->
> +    <property name="RefreshRate" type="u" access="readwrite"/>
> +
> +    <!--
> +        Reload:
> +
> +        Set the staged properties to the state of the console display.
> +    -->
> +    <method name="Reload">
> +    </method>
> +
> +    <!--
> +        Apply:
> +
> +        Apply the staged properties to the console display.
> +    -->
> +    <method name="Apply">
> +    </method>
> +  </interface>
>  </node>
> --
> 2.55.0
>
>

Re: [PATCH RFC v3 1/1] ui/dbus: add org.qemu.Display1.UIInfo interface

[Christian Hergert]

I have concerns with any sort of stateful tracking and/or application of 
properties as they are prone to data races.

If we want something more extensible for the future, we can use `a{sv}` 
with well-known keys.

-- Christian


On 8/18/26 5:01 PM, Marc-André Lureau wrote:
> That looks good to me. I am aware of concerns about refresh_rate unit
> (https://gitlab.gnome.org/GNOME/libmks/-/merge_requests/53#note_2834466),
> but I guess we will address this in due course
> 
> Christian, does this new interface look right to you?

Re: [PATCH RFC v3 1/1] ui/dbus: add org.qemu.Display1.UIInfo interface

[Marc-André Lureau]

Hi

On Wed, Aug 19, 2026 at 6:40 PM Christian Hergert
<christian@sourceandstack.com> wrote:
>
> I have concerns with any sort of stateful tracking and/or application of
> properties as they are prone to data races.

Good point..

> If we want something more extensible for the future, we can use `a{sv}`
> with well-known keys.

That was his v1. But then we would need to have a way to introspect
the known keys, and this is not really binding/tools friendly.

Maybe we can have a lock on the interface? that would be per
connection, but it could be enough?

Re: [PATCH RFC v3 1/1] ui/dbus: add org.qemu.Display1.UIInfo interface

[Christian Hergert]

On 8/19/26 4:43 PM, Marc-André Lureau wrote:
> That was his v1. But then we would need to have a way to introspect
> the known keys, and this is not really binding/tools friendly.

I would think that getting the current values is essentially the answer 
to what keys are supported? If you use a `mv` with a nullable you can 
export all the known keys and their values.

But ...

> Maybe we can have a lock on the interface? that would be per
> connection, but it could be enough?

I'm okay with the idea of exporting properties for all the things. I'm 
also okay with them being read/write. I just think they should apply 
immediately if using that API.

And if you want to set all of them "atomically", use either an extended 
SetUIInfo variant (either more parameters or a vardict).

Anyway, just my 2 cents.

-- Christian