diff --git a/README.md b/README.md index c94e251..1bf2f07 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # libmks -This library provides a "Mouse, Keyboard, and Screen" to Qemu using the -D-Bus device support in Qemu and GTK 4. +This library provides a "Mouse, Keyboard, and Screen" to QEMU using the +D-Bus device support in QEMU and GTK 4. # Documentation @@ -9,9 +9,9 @@ Nightly documentation can be found [here](https://chergert.pages.gitlab.gnome.or # Testing -By default, Qemu will connect to your user session D-Bus if you do not +By default, QEMU will connect to your user session D-Bus if you do not provide an address for `-display dbus`. Therefore, it is pretty easy to -test things by running Qemu manually and then connecting with the test +test things by running QEMU manually and then connecting with the test program `./tools/mks`. ```sh diff --git a/docs/Mks.toml.in b/docs/Mks.toml.in index fbf67ab..93a7572 100644 --- a/docs/Mks.toml.in +++ b/docs/Mks.toml.in @@ -6,7 +6,7 @@ website_url = "https://gitlab.gnome.org/chergert/libmks" docs_url = "https://chergert.pages.gitlab.gnome.org/libmks/" authors = "Christian Hergert" license = "LGPL-2.1-or-later" -description = "Mouse, Keyboard, and Screen to Qemu" +description = "Mouse, Keyboard, and Screen to QEMU" dependencies = [ "GObject-2.0", "Gdk-4.0", "Gtk-4.0" ] devhelp = true search_index = true diff --git a/lib/meson.build b/lib/meson.build index f2194ce..6c0a2c5 100644 --- a/lib/meson.build +++ b/lib/meson.build @@ -138,7 +138,7 @@ libmks_dep = declare_dependency( install_headers(libmks_headers, subdir: 'libmks-@0@'.format(api_version)) pkg.generate( - description: 'A shared library for Mouse, Keyboard, and Screen to Qemu', + description: 'A shared library for Mouse, Keyboard, and Screen to QEMU', libraries: libmks, name: 'libmks', filebase: 'libmks-' + api_version, diff --git a/lib/mks-device.c b/lib/mks-device.c index 1025c44..0bc5c2c 100644 --- a/lib/mks-device.c +++ b/lib/mks-device.c @@ -23,6 +23,12 @@ #include "mks-device-private.h" +/** + * MksDevice: + * + * An abstraction of a virtualized QEMU device. + */ + G_DEFINE_TYPE (MksDevice, mks_device, G_TYPE_OBJECT) enum { @@ -84,6 +90,11 @@ mks_device_class_init (MksDeviceClass *klass) klass->setup = mks_device_real_setup; + /** + * MksDevice:name: + * + * The device name. + */ properties [PROP_NAME] = g_param_spec_string ("name", NULL, NULL, NULL, @@ -97,6 +108,12 @@ mks_device_init (MksDevice *self) { } +/** + * mks_device_get_name: + * @self: A `MksDevice` + * + * Gets the device name. + */ const char * mks_device_get_name (MksDevice *self) { diff --git a/lib/mks-display-picture.c b/lib/mks-display-picture.c index f4154f5..7e81427 100644 --- a/lib/mks-display-picture.c +++ b/lib/mks-display-picture.c @@ -347,7 +347,7 @@ mks_display_picture_legacy_event_cb (MksDisplayPicture *self, /* * Currently there is no touchpad D-Bus interface to communicate - * with Qemu. That is something we would very much want to have + * with QEMU. That is something we would very much want to have * in the future so that we can do this properly. * * For now, we just "emulate" scroll events by looking at direction diff --git a/lib/mks-init.c b/lib/mks-init.c index cabb3e4..07eaac6 100644 --- a/lib/mks-init.c +++ b/lib/mks-init.c @@ -41,7 +41,7 @@ mks_init_gtypes (void) { g_resources_register (mks_get_resource ()); - /* First register GTypes for Qemu IPC */ + /* First register GTypes for QEMU IPC */ g_type_ensure (MKS_QEMU_TYPE_AUDIO); g_type_ensure (MKS_QEMU_TYPE_AUDIO_IN_LISTENER); g_type_ensure (MKS_QEMU_TYPE_AUDIO_OUT_LISTENER); @@ -66,6 +66,13 @@ mks_init_gtypes (void) g_type_ensure (MKS_TYPE_SESSION); } +/** + * mks_init: + * + * Initializes the library. + * + * The function must be called before using any of the library functions. + */ void mks_init (void) { @@ -86,18 +93,33 @@ _mks_init (void) mks_init (); } +/** + * mks_get_major_version: + * + * The major version the library. + */ int mks_get_major_version (void) { return MKS_MAJOR_VERSION; } +/** + * mks_get_minor_version: + * + * The minor version the library. + */ int mks_get_minor_version (void) { return MKS_MINOR_VERSION; } +/** + * mks_get_micro_version: + * + * The micro version the library. + */ int mks_get_micro_version (void) { diff --git a/lib/mks-keyboard.c b/lib/mks-keyboard.c index 0b0362f..6b4272c 100644 --- a/lib/mks-keyboard.c +++ b/lib/mks-keyboard.c @@ -29,6 +29,12 @@ #include "mks-keymap-xorgevdev2qnum-private.h" +/** + * MksKeyboard: + * + * A virtualized QEMU keyboard. + */ + struct _MksKeyboard { MksDevice parent_instance; @@ -152,6 +158,11 @@ mks_keyboard_class_init (MksKeyboardClass *klass) object_class->dispose = mks_keyboard_dispose; object_class->get_property = mks_keyboard_get_property; + /** + * MksKeyboard:modifiers: + * + * Active keyboard modifiers. + */ properties [PROP_MODIFIERS] = g_param_spec_flags ("modifiers", NULL, NULL, MKS_TYPE_KEYBOARD_MODIFIER, @@ -166,6 +177,12 @@ mks_keyboard_init (MksKeyboard *self) { } +/** + * mks_keyboard_get_modifiers: + * @self: an #MksKeyboard + * + * Get the active keyboard modifiers. + */ MksKeyboardModifier mks_keyboard_get_modifiers (MksKeyboard *self) { @@ -221,7 +238,7 @@ mks_keyboard_press_cb (GObject *object, * @callback: a #GAsyncReadyCallback to execute upon completion * @user_data: closure data for @callback * - * Asynchronously presses @keycode. + * Presses @keycode. */ void mks_keyboard_press (MksKeyboard *self, @@ -253,6 +270,17 @@ mks_keyboard_press (MksKeyboard *self, MKS_EXIT; } +/** + * mks_keyboard_press_finish: + * @self: a `MksKeyboard` + * @result: a #GAsyncResult provided to callback + * @error: a location for a #GError, or %NULL + * + * Completes a call to [method@Mks.Keyboard.press]. + * + * Returns: %TRUE if the operation completed successfully; otherwise %FALSE + * and @error is set. + */ gboolean mks_keyboard_press_finish (MksKeyboard *self, GAsyncResult *result, @@ -270,6 +298,19 @@ mks_keyboard_press_finish (MksKeyboard *self, MKS_RETURN (ret); } + +/** + * mks_keyboard_press_sync: + * @self: an #MksKeyboard + * @keycode: the hardware keycode + * @cancellable: (nullable): a #GCancellable + * @error: a location for a #GError, or %NULL + * + * Synchronously press the `keycode`. + * + * Returns: %TRUE if the operation was acknowledged by the QEMU instance; + * otherwise %FALSE and @error is set. + */ gboolean mks_keyboard_press_sync (MksKeyboard *self, guint keycode, @@ -322,7 +363,7 @@ mks_keyboard_release_cb (GObject *object, * @callback: a #GAsyncReadyCallback to execute upon completion * @user_data: closure data for @callback * - * Asynchronously releases @keycode. + * Releases @keycode. */ void mks_keyboard_release (MksKeyboard *self, @@ -354,6 +395,17 @@ mks_keyboard_release (MksKeyboard *self, MKS_EXIT; } +/** + * mks_keyboard_release_finish: + * @self: a `MksKeyboard` + * @result: a #GAsyncResult provided to callback + * @error: a location for a #GError, or %NULL + * + * Completes a call to [method@Mks.Keyboard.release]. + * + * Returns: %TRUE if the operation completed successfully; otherwise %FALSE + * and @error is set. + */ gboolean mks_keyboard_release_finish (MksKeyboard *self, GAsyncResult *result, @@ -371,6 +423,18 @@ mks_keyboard_release_finish (MksKeyboard *self, MKS_RETURN (ret); } +/** + * mks_keyboard_release_sync: + * @self: an #MksKeyboard + * @keycode: the hardware keycode + * @cancellable: (nullable): a #GCancellable + * @error: a location for a #GError, or %NULL + * + * Synchronously release the `keycode`. + * + * Returns: %TRUE if the operation was acknowledged by the QEMU instance; + * otherwise %FALSE and @error is set. + */ gboolean mks_keyboard_release_sync (MksKeyboard *self, guint keycode, diff --git a/lib/mks-keyboard.h b/lib/mks-keyboard.h index 8f779db..08dfa6d 100644 --- a/lib/mks-keyboard.h +++ b/lib/mks-keyboard.h @@ -42,6 +42,15 @@ G_BEGIN_DECLS typedef struct _MksKeyboardClass MksKeyboardClass; +/** + * MksKeyboardModifier: + * @MKS_KEYBOARD_MODIFIER_NONE: No modifier. + * @MKS_KEYBOARD_MODIFIER_SCROLL_LOCK: Scroll lock. + * @MKS_KEYBOARD_MODIFIER_NUM_LOCK: Numeric lock. + * @MKS_KEYBOARD_MODIFIER_CAPS_LOCK: Caps lock. + * + * The active keyboard modifiers. + */ typedef enum _MksKeyboardModifier { MKS_KEYBOARD_MODIFIER_NONE = 0, diff --git a/lib/mks-mouse.c b/lib/mks-mouse.c index e7cb234..1c020c6 100644 --- a/lib/mks-mouse.c +++ b/lib/mks-mouse.c @@ -25,6 +25,12 @@ #include "mks-mouse.h" #include "mks-util-private.h" +/** + * MksMouse: + * + * A virtualized QEMU mouse. + */ + struct _MksMouse { MksDevice parent_instance; @@ -121,6 +127,11 @@ mks_mouse_class_init (MksMouseClass *klass) device_class->setup = mks_mouse_setup; + /** + * MksMouse:is-absolute: + * + * Whether the mouse is using absolute movements. + */ properties [PROP_IS_ABSOLUTE] = g_param_spec_boolean ("is-absolute", NULL, NULL, FALSE, @@ -134,6 +145,12 @@ mks_mouse_init (MksMouse *self) { } +/** + * mks_mouse_get_is_absolute: + * @self: A `MksMouse`. + * + * Whether the mouse is using absolute movements. + */ gboolean mks_mouse_get_is_absolute (MksMouse *self) { @@ -224,6 +241,17 @@ mks_mouse_press (MksMouse *self, MKS_EXIT; } +/** + * mks_mouse_press_finish: + * @self: a `MksMouse` + * @result: a #GAsyncResult provided to callback + * @error: a location for a #GError, or %NULL + * + * Completes a call to [method@Mks.Mouse.press]. + * + * Returns: %TRUE if the operation completed successfully; otherwise %FALSE + * and @error is set. + */ gboolean mks_mouse_press_finish (MksMouse *self, GAsyncResult *result, @@ -241,6 +269,18 @@ mks_mouse_press_finish (MksMouse *self, MKS_RETURN (ret); } +/** + * mks_mouse_press_sync: + * @self: an #MksMouse + * @button: the #MksMouseButton that was released + * @cancellable: (nullable): a #GCancellable + * @error: a location for a #GError, or %NULL + * + * Synchronously press a mouse button. + * + * Returns: %TRUE if the operation was acknowledged by the QEMU instance; + * otherwise %FALSE and @error is set. + */ gboolean mks_mouse_press_sync (MksMouse *self, MksMouseButton button, @@ -288,7 +328,7 @@ mks_mouse_release_cb (GObject *object, /** * mks_mouse_release: * @self: an #MksMouse - * @button: the #MksMouseButton that was releaseed + * @button: the #MksMouseButton that was released * @cancellable: (nullable): a #GCancellable * @callback: a #GAsyncReadyCallback to execute upon completion * @user_data: closure data for @callback @@ -325,6 +365,17 @@ mks_mouse_release (MksMouse *self, MKS_EXIT; } +/** + * mks_mouse_release_finish: + * @self: a `MksMouse` + * @result: a #GAsyncResult provided to callback + * @error: a location for a #GError, or %NULL + * + * Completes a call to [method@Mks.Mouse.release]. + * + * Returns: %TRUE if the operation completed successfully; otherwise %FALSE + * and @error is set. + */ gboolean mks_mouse_release_finish (MksMouse *self, GAsyncResult *result, @@ -342,6 +393,18 @@ mks_mouse_release_finish (MksMouse *self, MKS_RETURN (ret); } +/** + * mks_mouse_release_sync: + * @self: an #MksMouse + * @button: the #MksMouseButton that was released + * @cancellable: (nullable): a #GCancellable + * @error: a location for a #GError, or %NULL + * + * Synchronously releases a mouse button. + * + * Returns: %TRUE if the operation was acknowledged by the QEMU instance; + * otherwise %FALSE and @error is set. + */ gboolean mks_mouse_release_sync (MksMouse *self, MksMouseButton button, @@ -431,6 +494,17 @@ mks_mouse_move_to (MksMouse *self, MKS_EXIT; } +/** + * mks_mouse_move_to_finish: + * @self: a `MksMouse` + * @result: a #GAsyncResult provided to callback + * @error: a location for a #GError, or %NULL + * + * Completes a call to [method@Mks.Mouse.move_to]. + * + * Returns: %TRUE if the operation completed successfully; otherwise %FALSE + * and @error is set. + */ gboolean mks_mouse_move_to_finish (MksMouse *self, GAsyncResult *result, @@ -456,9 +530,9 @@ mks_mouse_move_to_finish (MksMouse *self, * @cancellable: (nullable): a #GCancellable * @error: a location for a #GError, or %NULL * - * Moves to the absolute position at coordinates (x,y). + * Synchronously moves to the absolute position at coordinates (x,y). * - * Returns: %TRUE if the operation was acknowledged by the Qemu instance; + * Returns: %TRUE if the operation was acknowledged by the QEMU instance; * otherwise %FALSE and @error is set. */ gboolean @@ -554,6 +628,17 @@ mks_mouse_move_by (MksMouse *self, MKS_EXIT; } +/** + * mks_mouse_move_by_finish: + * @self: a `MksMouse` + * @result: a #GAsyncResult provided to callback + * @error: a location for a #GError, or %NULL + * + * Completes a call to [method@Mks.Mouse.move_by]. + * + * Returns: %TRUE if the operation completed successfully; otherwise %FALSE + * and @error is set. + */ gboolean mks_mouse_move_by_finish (MksMouse *self, GAsyncResult *result, @@ -579,9 +664,9 @@ mks_mouse_move_by_finish (MksMouse *self, * @cancellable: (nullable): a #GCancellable * @error: a location for a #GError, or %NULL * - * Moves the mouse by delta_x and delta_y. + * Synchronously moves the mouse by delta_x and delta_y. * - * Returns: %TRUE if the operation was acknowledged by the Qemu instance; + * Returns: %TRUE if the operation was acknowledged by the QEMU instance; * otherwise %FALSE and @error is set. */ gboolean diff --git a/lib/mks-mouse.h b/lib/mks-mouse.h index 87129ce..963f2a0 100644 --- a/lib/mks-mouse.h +++ b/lib/mks-mouse.h @@ -42,6 +42,18 @@ G_BEGIN_DECLS typedef struct _MksMouseClass MksMouseClass; +/** + * MksMouseButton: + * @MKS_MOUSE_BUTTON_LEFT: Left button. + * @MKS_MOUSE_BUTTON_MIDDLE: Middle button. + * @MKS_MOUSE_BUTTON_RIGHT: Right button. + * @MKS_MOUSE_BUTTON_WHEEL_UP: Wheel-up button. + * @MKS_MOUSE_BUTTON_WHEEL_DOWN: Wheel-down button. + * @MKS_MOUSE_BUTTON_SIDE: Side button. + * @MKS_MOUSE_BUTTON_EXTRA: Extra button. + * + * A mouse button. + */ typedef enum _MksMouseButton { MKS_MOUSE_BUTTON_LEFT = 0, diff --git a/lib/mks-paintable.c b/lib/mks-paintable.c index fcd165a..614867d 100644 --- a/lib/mks-paintable.c +++ b/lib/mks-paintable.c @@ -820,7 +820,7 @@ _mks_paintable_new (GCancellable *cancellable, * _mks_paintable_get_cursor: * @self: a #MksPaintable * - * Gets the cursor as defined by the Qemu instance. + * Gets the cursor as defined by the QEMU instance. * * Returns: (transfer none) (nullable): a #GdkCursor or %NULL */ diff --git a/lib/mks-screen-attributes.c b/lib/mks-screen-attributes.c index c957ebb..0feacc7 100644 --- a/lib/mks-screen-attributes.c +++ b/lib/mks-screen-attributes.c @@ -23,6 +23,15 @@ #include "mks-screen-attributes-private.h" +/** + * MksScreenAttributes: + * + * Screen attributes. + * + * The attributes are used to reconfigure the QEMU instance with + * [method@Mks.Screen.configure] or [method@Mks.Screen.configure_sync]. + */ + G_DEFINE_BOXED_TYPE (MksScreenAttributes, mks_screen_attributes, mks_screen_attributes_copy, @@ -63,8 +72,10 @@ mks_screen_attributes_copy (MksScreenAttributes *self) * mks_screen_attributes_free: * @self: a #MksScreenAttributes * - * Frees a #MksScreenAttributes allocated using mks_screen_attributes_new() - * or mks_screen_attributes_copy(). + * Frees a #MksScreenAttributes. + * + * Allocated using [ctor@Mks.ScreenAttributes.new] + * or [method@Mks.ScreenAttributes.copy]. */ void mks_screen_attributes_free (MksScreenAttributes *self) @@ -94,6 +105,13 @@ mks_screen_attributes_equal (MksScreenAttributes *self, self->height_mm == other->height_mm); } +/** + * mks_screen_attributes_set_width_mm: + * @self: A MksScreenAttributes. + * @width_mm: The screen width. + * + * Set the screen width in millimeters. + */ void mks_screen_attributes_set_width_mm (MksScreenAttributes *self, guint16 width_mm) @@ -101,6 +119,13 @@ mks_screen_attributes_set_width_mm (MksScreenAttributes *self, self->width_mm = width_mm; } +/** + * mks_screen_attributes_set_height_mm: + * @self: A MksScreenAttributes. + * @height_mm: The screen height. + * + * Set the screen height in millimeters. + */ void mks_screen_attributes_set_height_mm (MksScreenAttributes *self, guint16 height_mm) @@ -108,6 +133,13 @@ mks_screen_attributes_set_height_mm (MksScreenAttributes *self, self->height_mm = height_mm; } +/** + * mks_screen_attributes_set_x_offset: + * @self: A MksScreenAttributes. + * @x_offset: The screen's horizontal offset. + * + * Set the screen's horizontal offset in pixels. + */ void mks_screen_attributes_set_x_offset (MksScreenAttributes *self, int x_offset) @@ -115,6 +147,13 @@ mks_screen_attributes_set_x_offset (MksScreenAttributes *self, self->x_offset = x_offset; } +/** + * mks_screen_attributes_set_y_offset: + * @self: A MksScreenAttributes. + * @y_offset: The screen's vertical offset. + * + * Set the screen's vertical offset in pixels. + */ void mks_screen_attributes_set_y_offset (MksScreenAttributes *self, int y_offset) @@ -122,6 +161,13 @@ mks_screen_attributes_set_y_offset (MksScreenAttributes *self, self->y_offset = y_offset; } +/** + * mks_screen_attributes_set_width: + * @self: A MksScreenAttributes. + * @width: The screen width. + * + * Set the screen width in pixels. + */ void mks_screen_attributes_set_width (MksScreenAttributes *self, guint width) @@ -129,6 +175,13 @@ mks_screen_attributes_set_width (MksScreenAttributes *self, self->width = width; } +/** + * mks_screen_attributes_set_height: + * @self: A MksScreenAttributes. + * @height: The screen height. + * + * Set the screen height in pixels. + */ void mks_screen_attributes_set_height (MksScreenAttributes *self, guint height) diff --git a/lib/mks-screen.c b/lib/mks-screen.c index 27d3a56..fbbf89e 100644 --- a/lib/mks-screen.c +++ b/lib/mks-screen.c @@ -478,11 +478,11 @@ mks_screen_configure_cb (GObject *object, * @callback: a #GAsyncReadyCallback to execute upon completion * @user_data: closure data for @callback * - * Requests the Qemu instance reconfigure the screen with @attributes. + * Requests the QEMU instance reconfigure the screen with @attributes. * * This function takes ownership of @attributes. * - * @callback is executed upon acknowledgment from the Qemu instance or + * @callback is executed upon acknowledgment from the QEMU instance or * if the request timed out. * * Call mks_screen_configure_finish() to get the result. @@ -550,7 +550,7 @@ mks_screen_configure_finish (MksScreen *self, * @cancellable: a #GCancellable * @error: a location for a #GError, or %NULL * - * Requests the Qemu instance reconfigure the screen using @attributes. + * Requests the QEMU instance reconfigure the screen using @attributes. * * This function takes ownership of @attributes. * @@ -613,7 +613,7 @@ mks_screen_attach_cb (GObject *object, * contents of the screen. * * This function registers a new `socketpair()` which is shared with - * the Qemu instance to receive rendering updates. Those updates are + * the QEMU instance to receive rendering updates. Those updates are * propagated to the resulting #GdkPainable which can be retrieved * using mks_screen_attach_finish() from @callback. */ @@ -661,11 +661,11 @@ failure: * @result: a #GAsyncResult provided to callback * @error: a location for a #GError, or %NULL * - * Completes an asynchronous request to create a #GdkPaintable containing - * the contents of #MksScreen in the Qemu instance. + * Completes an asynchronous request to create a [iface@Gdk.Paintable] containing + * the contents of #MksScreen in the QEMU instance. * - * The resulting #GdkPaintable will be updated as changes are delivered - * from Qemu over a private `socketpair()`. In the typical case, those + * The resulting [iface@Gdk.Paintable] will be updated as changes are delivered + * from QEMU over a private `socketpair()`. In the typical case, those * changes are propagated using a DMA-BUF and damage notifications. * * Returns: (transfer full): a #GdkPainable if successful; otherwise %NULL @@ -689,7 +689,7 @@ mks_screen_attach_finish (MksScreen *self, * @error: (nullable): a location for a #GError, or %NULL * * Synchronous request to attach to screen, creating a paintable that can - * be used to update display as the Qemu instance updates. + * be used to update display as the QEMU instance updates. * * Returns: (transfer full): a #GdkPaintable if successful; otherwise %NULL * and @error is set. diff --git a/lib/mks-screen.h b/lib/mks-screen.h index c6a1677..9f69854 100644 --- a/lib/mks-screen.h +++ b/lib/mks-screen.h @@ -43,6 +43,13 @@ G_BEGIN_DECLS typedef struct _MksScreenClass MksScreenClass; +/** + * MksScreenKind: + * @MKS_SCREEN_KIND_TEXT: A text only screen. + * @MKS_SCREEN_KIND_GRAPHIC: A graphical screen. + * + * A screen kind. + */ typedef enum _MksScreenKind { MKS_SCREEN_KIND_TEXT = 0, diff --git a/lib/mks-session.c b/lib/mks-session.c index 34e7d3d..83dd3f3 100644 --- a/lib/mks-session.c +++ b/lib/mks-session.c @@ -28,32 +28,32 @@ #include "mks-session.h" /** - * SECTION:mks-session - * @Title: MksSession - * @Short_description: Session connected to a Qemu VM + * MksSession: + * + * Session connected to a QEMU VM * - * The #MksSession represents a connection to a Qemu VM instance. It contains + * The `MksSession` represents a connection to a QEMU VM instance. It contains * devices such as the mouse, keyboard, and screen which can be used with GTK. * - * You may monitor #MksSession:devices using #GListModel:items-changed to be + * You may monitor [property@Mks.Session:devices] using [signal@Gio.ListModel::items-changed] to be * notified of changes to available devices in the session. * - * # Connecting To Qemu + * # Connecting To QEMU * - * To use #MksSession, you should create your Qemu instance using `dbus` for + * To use `MksSession`, you should create your QEMU instance using `dbus` for * the various devices that support it. You'll need to provide your P2P D-Bus - * address when connecting to Qemu. + * address when connecting to QEMU. * - * Using the same #GDBusConnection, create a #MksSession with - * mks_session_new_for_connection(). The #MksSession instance will negotiate + * Using the same [class@Gio.DBusConnection], create a `MksSession` with + * [func@Mks.Session.new_for_connection]. The `MksSession` instance will negotiate * with the peer to determine what devices are available and expose them - * via the #MksSession:devices #GListModel. + * via the [property@Mks.Session:devices] [iface@Gio.ListModel]. * * # Creating Widgets * - * You can create a new widget to embed in your application by waiting for - * a #MksScreen to become available in the list model or connecting to the - * #GObject::notify signal for the #MksSession:screen property. + * You can create a new widget to embed in your application by calling + * [method@Mks.Session.ref_screen] and set the screen for the [class@Mks.Display] + * with [method@Mks.Display.set_screen]. */ static gboolean mks_session_initable_init (GInitable *initable, @@ -72,15 +72,15 @@ struct _MksSession { GObject parent_instance; - /* @connection is used to communicate with the Qemu instance. It is expected + /* @connection is used to communicate with the QEMU instance. It is expected * to be a private point-to-point connection over a Unix socket, socketpair(), * or other channel capable of passing FDs between peers. */ GDBusConnection *connection; - /* As devices are discovered from the Qemu instance, MksDevice-based objects + /* As devices are discovered from the QEMU instance, MksDevice-based objects * are created for them and stored in @devices. Applications will work with - * these objects to perform operations on the Qemu instance. When we discover + * these objects to perform operations on the QEMU instance. When we discover * the devices have been removed, we drop them from the listmodel. */ GListStore *devices; @@ -93,7 +93,7 @@ struct _MksSession GListModel *devices_read_only; /* An object manager client is used to monitor for new objects exported by - * the Qemu instance. Those objects are then wrapped by MksDevice objects + * the QEMU instance. Those objects are then wrapped by MksDevice objects * as necessary and exported to consumers via @devices. */ GDBusObjectManager *object_manager; @@ -365,8 +365,7 @@ mks_session_class_init (MksSessionClass *klass) /** * MksSession:connection: * - * The "connection" property contains the #GDBusConnection that is used - * to communicate with Qemu. + * The [class@Gio.DBusConnection] that is used to communicate with QEMU. */ properties [PROP_CONNECTION] = g_param_spec_object ("connection", NULL, NULL, @@ -376,8 +375,8 @@ mks_session_class_init (MksSessionClass *klass) /** * MksSession:devices: * - * The "devices" property contains a #GListModel of devices that have been - * discovered on the #GDBusConnection to Qemu. + * A [iface@Gio.ListModel] of devices that have been + * discovered on the [class@Gio.DBusConnection] to QEMU. */ properties [PROP_DEVICES] = g_param_spec_object ("devices", NULL, NULL, @@ -387,8 +386,7 @@ mks_session_class_init (MksSessionClass *klass) /** * MksSession:name: * - * The "name" property is the named of the VM as specified by the - * Qemu instance. + * The VM name as specified by the QEMU instance. */ properties [PROP_NAME] = g_param_spec_string ("name", NULL, NULL, @@ -398,8 +396,7 @@ mks_session_class_init (MksSessionClass *klass) /** * MksSession:uuid: * - * The "uuid" property is the unique identifier as specified by the - * Qemu instance for the VM. + * The VM unique identifier specified by the QEMU instance. */ properties [PROP_UUID] = g_param_spec_string ("uuid", NULL, NULL, @@ -566,7 +563,7 @@ mks_session_new_for_connection_cb (GObject *object, * * Creates a #MksSession which communicates using @connection. * - * The #GDBusConnection should be a private D-Bus connection to a Qemu + * The [class@Gio.DBusConnection] should be a private D-Bus connection to a QEMU * instance which has devices created using the "dbus" backend. * @callback will be executed when the session has been created or @@ -574,7 +571,7 @@ mks_session_new_for_connection_cb (GObject *object, * * This function will not block the calling thread. * - * use mks_session_new_for_connection_finish() to get the result of + * use [ctor@Mks.Session.new_for_connection_finish] to get the result of * this operation. */ void @@ -610,7 +607,7 @@ mks_session_new_for_connection (GDBusConnection *connection, * @result: a #GAsyncResult provided to callback * @error: (nullable): a location for a #GError or %NULL * - * Completes a request to create a #MksSession for a #GDBusConnection. + * Completes a request to create a #MksSession for a [class@Gio.DBusConnection]. * * Returns: (transfer full): a #MksSession if successful; otherwise %NULL * and @error is set. @@ -626,13 +623,13 @@ mks_session_new_for_connection_finish (GAsyncResult *result, /** * mks_session_new_for_connection_sync: - * @connection: a private #GDBusConnetion to a Qemu instance + * @connection: a private #GDBusConnetion to a QEMU instance * @cancellable: (nullable): a #GCancellable, or %NULL * @error: (nullable): a location for a #GError, or %NULL * * Synchronously creates a new #MksSession instance. * - * This may block while the Qemu instance is contacted to query for + * This may block while the QEMU instance is contacted to query for * initial devices and VM status. * * Returns: (transfer full): a #MksSession if successful; otherwise %NULL @@ -661,7 +658,7 @@ mks_session_new_for_connection_sync (GDBusConnection *connection, * mks_session_get_connection: * @self: a #MksSession * - * Gets the #MksSession:connection property. + * Gets the DBus connection used for this session. * * Returns: (transfer none) (nullable): a #GDBusConnection or %NULL if * the connection has not been set, or was disposed. @@ -678,7 +675,7 @@ mks_session_get_connection (MksSession *self) * mks_session_get_uuid: * @self: a #MksSession * - * Gets the "uuid" property. + * Gets the unique identifier of the VM. */ const char * mks_session_get_uuid (MksSession *self) @@ -695,7 +692,7 @@ mks_session_get_uuid (MksSession *self) * mks_session_get_name: * @self: a #MksSession * - * Gets the "name" property. + * Gets the name of the VM. */ const char * mks_session_get_name (MksSession *self) diff --git a/lib/mks-speaker.c b/lib/mks-speaker.c index 3a1cac4..daf9910 100644 --- a/lib/mks-speaker.c +++ b/lib/mks-speaker.c @@ -28,6 +28,12 @@ #include "mks-speaker.h" #include "mks-util-private.h" +/** + * MksSpeaker: + * + * A virtualized QEMU speaker. + */ + struct _MksSpeaker { MksDevice parent_instance; @@ -310,9 +316,8 @@ mks_speaker_class_init (MksSpeakerClass *klass) /** * MksSpeaker:muted: * - * The "muted" property denotes if audio received from the - * instance is dropped and the remote sound device should - * attempt to be set as muted. + * If audio received from the instance is dropped and + * the remote sound device should attempt to be set as muted. */ properties [PROP_MUTED] = g_param_spec_boolean ("muted", NULL, NULL, @@ -348,7 +353,7 @@ mks_speaker_get_muted (MksSpeaker *self) * @self: a #MksSpeaker * @muted: if the speaker should be muted * - * Sets the #MksSpeaker:muted property. + * Mute or un-mute the speaker. */ void mks_speaker_set_muted (MksSpeaker *self, diff --git a/tools/mks-connect.c b/tools/mks-connect.c index 13b1f53..2995312 100644 --- a/tools/mks-connect.c +++ b/tools/mks-connect.c @@ -70,7 +70,7 @@ int main (int argc, char *argv[]) { - g_autoptr(GOptionContext) context = g_option_context_new ("DBUS_ADDRESS - Connect to Qemu at DBUS_ADDRESS"); + g_autoptr(GOptionContext) context = g_option_context_new ("DBUS_ADDRESS - Connect to QEMU at DBUS_ADDRESS"); g_autoptr(GDBusConnection) connection = NULL; g_autoptr(MksSession) session = NULL; g_autoptr(GError) error = NULL;