Merge branch 'bilelmoussaoui/docs' into 'main'

docs: Document most of the public APIs

See merge request chergert/libmks!18
This commit is contained in:
Christian Hergert 2023-05-23 19:54:00 +00:00
commit e8d30c4f73
17 changed files with 337 additions and 66 deletions

View File

@ -1,7 +1,7 @@
# libmks # libmks
This library provides a "Mouse, Keyboard, and Screen" to Qemu using the This library provides a "Mouse, Keyboard, and Screen" to QEMU using the
D-Bus device support in Qemu and GTK 4. D-Bus device support in QEMU and GTK 4.
# Documentation # Documentation
@ -9,9 +9,9 @@ Nightly documentation can be found [here](https://chergert.pages.gitlab.gnome.or
# Testing # 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 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`. program `./tools/mks`.
```sh ```sh

View File

@ -6,7 +6,7 @@ website_url = "https://gitlab.gnome.org/chergert/libmks"
docs_url = "https://chergert.pages.gitlab.gnome.org/libmks/" docs_url = "https://chergert.pages.gitlab.gnome.org/libmks/"
authors = "Christian Hergert" authors = "Christian Hergert"
license = "LGPL-2.1-or-later" 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" ] dependencies = [ "GObject-2.0", "Gdk-4.0", "Gtk-4.0" ]
devhelp = true devhelp = true
search_index = true search_index = true

View File

@ -138,7 +138,7 @@ libmks_dep = declare_dependency(
install_headers(libmks_headers, subdir: 'libmks-@0@'.format(api_version)) install_headers(libmks_headers, subdir: 'libmks-@0@'.format(api_version))
pkg.generate( 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, libraries: libmks,
name: 'libmks', name: 'libmks',
filebase: 'libmks-' + api_version, filebase: 'libmks-' + api_version,

View File

@ -23,6 +23,12 @@
#include "mks-device-private.h" #include "mks-device-private.h"
/**
* MksDevice:
*
* An abstraction of a virtualized QEMU device.
*/
G_DEFINE_TYPE (MksDevice, mks_device, G_TYPE_OBJECT) G_DEFINE_TYPE (MksDevice, mks_device, G_TYPE_OBJECT)
enum { enum {
@ -84,6 +90,11 @@ mks_device_class_init (MksDeviceClass *klass)
klass->setup = mks_device_real_setup; klass->setup = mks_device_real_setup;
/**
* MksDevice:name:
*
* The device name.
*/
properties [PROP_NAME] = properties [PROP_NAME] =
g_param_spec_string ("name", NULL, NULL, g_param_spec_string ("name", NULL, 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 * const char *
mks_device_get_name (MksDevice *self) mks_device_get_name (MksDevice *self)
{ {

View File

@ -347,7 +347,7 @@ mks_display_picture_legacy_event_cb (MksDisplayPicture *self,
/* /*
* Currently there is no touchpad D-Bus interface to communicate * 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. * in the future so that we can do this properly.
* *
* For now, we just "emulate" scroll events by looking at direction * For now, we just "emulate" scroll events by looking at direction

View File

@ -41,7 +41,7 @@ mks_init_gtypes (void)
{ {
g_resources_register (mks_get_resource ()); 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);
g_type_ensure (MKS_QEMU_TYPE_AUDIO_IN_LISTENER); g_type_ensure (MKS_QEMU_TYPE_AUDIO_IN_LISTENER);
g_type_ensure (MKS_QEMU_TYPE_AUDIO_OUT_LISTENER); g_type_ensure (MKS_QEMU_TYPE_AUDIO_OUT_LISTENER);
@ -66,6 +66,13 @@ mks_init_gtypes (void)
g_type_ensure (MKS_TYPE_SESSION); g_type_ensure (MKS_TYPE_SESSION);
} }
/**
* mks_init:
*
* Initializes the library.
*
* The function must be called before using any of the library functions.
*/
void void
mks_init (void) mks_init (void)
{ {
@ -86,18 +93,33 @@ _mks_init (void)
mks_init (); mks_init ();
} }
/**
* mks_get_major_version:
*
* The major version the library.
*/
int int
mks_get_major_version (void) mks_get_major_version (void)
{ {
return MKS_MAJOR_VERSION; return MKS_MAJOR_VERSION;
} }
/**
* mks_get_minor_version:
*
* The minor version the library.
*/
int int
mks_get_minor_version (void) mks_get_minor_version (void)
{ {
return MKS_MINOR_VERSION; return MKS_MINOR_VERSION;
} }
/**
* mks_get_micro_version:
*
* The micro version the library.
*/
int int
mks_get_micro_version (void) mks_get_micro_version (void)
{ {

View File

@ -29,6 +29,12 @@
#include "mks-keymap-xorgevdev2qnum-private.h" #include "mks-keymap-xorgevdev2qnum-private.h"
/**
* MksKeyboard:
*
* A virtualized QEMU keyboard.
*/
struct _MksKeyboard struct _MksKeyboard
{ {
MksDevice parent_instance; MksDevice parent_instance;
@ -152,6 +158,11 @@ mks_keyboard_class_init (MksKeyboardClass *klass)
object_class->dispose = mks_keyboard_dispose; object_class->dispose = mks_keyboard_dispose;
object_class->get_property = mks_keyboard_get_property; object_class->get_property = mks_keyboard_get_property;
/**
* MksKeyboard:modifiers:
*
* Active keyboard modifiers.
*/
properties [PROP_MODIFIERS] = properties [PROP_MODIFIERS] =
g_param_spec_flags ("modifiers", NULL, NULL, g_param_spec_flags ("modifiers", NULL, NULL,
MKS_TYPE_KEYBOARD_MODIFIER, 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 MksKeyboardModifier
mks_keyboard_get_modifiers (MksKeyboard *self) mks_keyboard_get_modifiers (MksKeyboard *self)
{ {
@ -221,7 +238,7 @@ mks_keyboard_press_cb (GObject *object,
* @callback: a #GAsyncReadyCallback to execute upon completion * @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback * @user_data: closure data for @callback
* *
* Asynchronously presses @keycode. * Presses @keycode.
*/ */
void void
mks_keyboard_press (MksKeyboard *self, mks_keyboard_press (MksKeyboard *self,
@ -253,6 +270,17 @@ mks_keyboard_press (MksKeyboard *self,
MKS_EXIT; 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 gboolean
mks_keyboard_press_finish (MksKeyboard *self, mks_keyboard_press_finish (MksKeyboard *self,
GAsyncResult *result, GAsyncResult *result,
@ -270,6 +298,19 @@ mks_keyboard_press_finish (MksKeyboard *self,
MKS_RETURN (ret); 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 gboolean
mks_keyboard_press_sync (MksKeyboard *self, mks_keyboard_press_sync (MksKeyboard *self,
guint keycode, guint keycode,
@ -322,7 +363,7 @@ mks_keyboard_release_cb (GObject *object,
* @callback: a #GAsyncReadyCallback to execute upon completion * @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback * @user_data: closure data for @callback
* *
* Asynchronously releases @keycode. * Releases @keycode.
*/ */
void void
mks_keyboard_release (MksKeyboard *self, mks_keyboard_release (MksKeyboard *self,
@ -354,6 +395,17 @@ mks_keyboard_release (MksKeyboard *self,
MKS_EXIT; 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 gboolean
mks_keyboard_release_finish (MksKeyboard *self, mks_keyboard_release_finish (MksKeyboard *self,
GAsyncResult *result, GAsyncResult *result,
@ -371,6 +423,18 @@ mks_keyboard_release_finish (MksKeyboard *self,
MKS_RETURN (ret); 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 gboolean
mks_keyboard_release_sync (MksKeyboard *self, mks_keyboard_release_sync (MksKeyboard *self,
guint keycode, guint keycode,

View File

@ -42,6 +42,15 @@ G_BEGIN_DECLS
typedef struct _MksKeyboardClass MksKeyboardClass; 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 typedef enum _MksKeyboardModifier
{ {
MKS_KEYBOARD_MODIFIER_NONE = 0, MKS_KEYBOARD_MODIFIER_NONE = 0,

View File

@ -25,6 +25,12 @@
#include "mks-mouse.h" #include "mks-mouse.h"
#include "mks-util-private.h" #include "mks-util-private.h"
/**
* MksMouse:
*
* A virtualized QEMU mouse.
*/
struct _MksMouse struct _MksMouse
{ {
MksDevice parent_instance; MksDevice parent_instance;
@ -121,6 +127,11 @@ mks_mouse_class_init (MksMouseClass *klass)
device_class->setup = mks_mouse_setup; device_class->setup = mks_mouse_setup;
/**
* MksMouse:is-absolute:
*
* Whether the mouse is using absolute movements.
*/
properties [PROP_IS_ABSOLUTE] = properties [PROP_IS_ABSOLUTE] =
g_param_spec_boolean ("is-absolute", NULL, NULL, g_param_spec_boolean ("is-absolute", NULL, NULL,
FALSE, 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 gboolean
mks_mouse_get_is_absolute (MksMouse *self) mks_mouse_get_is_absolute (MksMouse *self)
{ {
@ -224,6 +241,17 @@ mks_mouse_press (MksMouse *self,
MKS_EXIT; 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 gboolean
mks_mouse_press_finish (MksMouse *self, mks_mouse_press_finish (MksMouse *self,
GAsyncResult *result, GAsyncResult *result,
@ -241,6 +269,18 @@ mks_mouse_press_finish (MksMouse *self,
MKS_RETURN (ret); 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 gboolean
mks_mouse_press_sync (MksMouse *self, mks_mouse_press_sync (MksMouse *self,
MksMouseButton button, MksMouseButton button,
@ -288,7 +328,7 @@ mks_mouse_release_cb (GObject *object,
/** /**
* mks_mouse_release: * mks_mouse_release:
* @self: an #MksMouse * @self: an #MksMouse
* @button: the #MksMouseButton that was releaseed * @button: the #MksMouseButton that was released
* @cancellable: (nullable): a #GCancellable * @cancellable: (nullable): a #GCancellable
* @callback: a #GAsyncReadyCallback to execute upon completion * @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback * @user_data: closure data for @callback
@ -325,6 +365,17 @@ mks_mouse_release (MksMouse *self,
MKS_EXIT; 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 gboolean
mks_mouse_release_finish (MksMouse *self, mks_mouse_release_finish (MksMouse *self,
GAsyncResult *result, GAsyncResult *result,
@ -342,6 +393,18 @@ mks_mouse_release_finish (MksMouse *self,
MKS_RETURN (ret); 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 gboolean
mks_mouse_release_sync (MksMouse *self, mks_mouse_release_sync (MksMouse *self,
MksMouseButton button, MksMouseButton button,
@ -431,6 +494,17 @@ mks_mouse_move_to (MksMouse *self,
MKS_EXIT; 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 gboolean
mks_mouse_move_to_finish (MksMouse *self, mks_mouse_move_to_finish (MksMouse *self,
GAsyncResult *result, GAsyncResult *result,
@ -456,9 +530,9 @@ mks_mouse_move_to_finish (MksMouse *self,
* @cancellable: (nullable): a #GCancellable * @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL * @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. * otherwise %FALSE and @error is set.
*/ */
gboolean gboolean
@ -554,6 +628,17 @@ mks_mouse_move_by (MksMouse *self,
MKS_EXIT; 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 gboolean
mks_mouse_move_by_finish (MksMouse *self, mks_mouse_move_by_finish (MksMouse *self,
GAsyncResult *result, GAsyncResult *result,
@ -579,9 +664,9 @@ mks_mouse_move_by_finish (MksMouse *self,
* @cancellable: (nullable): a #GCancellable * @cancellable: (nullable): a #GCancellable
* @error: a location for a #GError, or %NULL * @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. * otherwise %FALSE and @error is set.
*/ */
gboolean gboolean

View File

@ -42,6 +42,18 @@ G_BEGIN_DECLS
typedef struct _MksMouseClass MksMouseClass; 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 typedef enum _MksMouseButton
{ {
MKS_MOUSE_BUTTON_LEFT = 0, MKS_MOUSE_BUTTON_LEFT = 0,

View File

@ -820,7 +820,7 @@ _mks_paintable_new (GCancellable *cancellable,
* _mks_paintable_get_cursor: * _mks_paintable_get_cursor:
* @self: a #MksPaintable * @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 * Returns: (transfer none) (nullable): a #GdkCursor or %NULL
*/ */

View File

@ -23,6 +23,15 @@
#include "mks-screen-attributes-private.h" #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, G_DEFINE_BOXED_TYPE (MksScreenAttributes,
mks_screen_attributes, mks_screen_attributes,
mks_screen_attributes_copy, mks_screen_attributes_copy,
@ -63,8 +72,10 @@ mks_screen_attributes_copy (MksScreenAttributes *self)
* mks_screen_attributes_free: * mks_screen_attributes_free:
* @self: a #MksScreenAttributes * @self: a #MksScreenAttributes
* *
* Frees a #MksScreenAttributes allocated using mks_screen_attributes_new() * Frees a #MksScreenAttributes.
* or mks_screen_attributes_copy(). *
* Allocated using [ctor@Mks.ScreenAttributes.new]
* or [method@Mks.ScreenAttributes.copy].
*/ */
void void
mks_screen_attributes_free (MksScreenAttributes *self) mks_screen_attributes_free (MksScreenAttributes *self)
@ -94,6 +105,13 @@ mks_screen_attributes_equal (MksScreenAttributes *self,
self->height_mm == other->height_mm); 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 void
mks_screen_attributes_set_width_mm (MksScreenAttributes *self, mks_screen_attributes_set_width_mm (MksScreenAttributes *self,
guint16 width_mm) guint16 width_mm)
@ -101,6 +119,13 @@ mks_screen_attributes_set_width_mm (MksScreenAttributes *self,
self->width_mm = width_mm; 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 void
mks_screen_attributes_set_height_mm (MksScreenAttributes *self, mks_screen_attributes_set_height_mm (MksScreenAttributes *self,
guint16 height_mm) guint16 height_mm)
@ -108,6 +133,13 @@ mks_screen_attributes_set_height_mm (MksScreenAttributes *self,
self->height_mm = height_mm; 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 void
mks_screen_attributes_set_x_offset (MksScreenAttributes *self, mks_screen_attributes_set_x_offset (MksScreenAttributes *self,
int x_offset) int x_offset)
@ -115,6 +147,13 @@ mks_screen_attributes_set_x_offset (MksScreenAttributes *self,
self->x_offset = x_offset; 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 void
mks_screen_attributes_set_y_offset (MksScreenAttributes *self, mks_screen_attributes_set_y_offset (MksScreenAttributes *self,
int y_offset) int y_offset)
@ -122,6 +161,13 @@ mks_screen_attributes_set_y_offset (MksScreenAttributes *self,
self->y_offset = y_offset; self->y_offset = y_offset;
} }
/**
* mks_screen_attributes_set_width:
* @self: A MksScreenAttributes.
* @width: The screen width.
*
* Set the screen width in pixels.
*/
void void
mks_screen_attributes_set_width (MksScreenAttributes *self, mks_screen_attributes_set_width (MksScreenAttributes *self,
guint width) guint width)
@ -129,6 +175,13 @@ mks_screen_attributes_set_width (MksScreenAttributes *self,
self->width = width; self->width = width;
} }
/**
* mks_screen_attributes_set_height:
* @self: A MksScreenAttributes.
* @height: The screen height.
*
* Set the screen height in pixels.
*/
void void
mks_screen_attributes_set_height (MksScreenAttributes *self, mks_screen_attributes_set_height (MksScreenAttributes *self,
guint height) guint height)

View File

@ -478,11 +478,11 @@ mks_screen_configure_cb (GObject *object,
* @callback: a #GAsyncReadyCallback to execute upon completion * @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback * @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. * 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. * if the request timed out.
* *
* Call mks_screen_configure_finish() to get the result. * Call mks_screen_configure_finish() to get the result.
@ -550,7 +550,7 @@ mks_screen_configure_finish (MksScreen *self,
* @cancellable: a #GCancellable * @cancellable: a #GCancellable
* @error: a location for a #GError, or %NULL * @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. * This function takes ownership of @attributes.
* *
@ -613,7 +613,7 @@ mks_screen_attach_cb (GObject *object,
* contents of the screen. * contents of the screen.
* *
* This function registers a new `socketpair()` which is shared with * 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 * propagated to the resulting #GdkPainable which can be retrieved
* using mks_screen_attach_finish() from @callback. * using mks_screen_attach_finish() from @callback.
*/ */
@ -661,11 +661,11 @@ failure:
* @result: a #GAsyncResult provided to callback * @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL * @error: a location for a #GError, or %NULL
* *
* Completes an asynchronous request to create a #GdkPaintable containing * Completes an asynchronous request to create a [iface@Gdk.Paintable] containing
* the contents of #MksScreen in the Qemu instance. * the contents of #MksScreen in the QEMU instance.
* *
* The resulting #GdkPaintable will be updated as changes are delivered * The resulting [iface@Gdk.Paintable] will be updated as changes are delivered
* from Qemu over a private `socketpair()`. In the typical case, those * from QEMU over a private `socketpair()`. In the typical case, those
* changes are propagated using a DMA-BUF and damage notifications. * changes are propagated using a DMA-BUF and damage notifications.
* *
* Returns: (transfer full): a #GdkPainable if successful; otherwise %NULL * 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 * @error: (nullable): a location for a #GError, or %NULL
* *
* Synchronous request to attach to screen, creating a paintable that can * 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 * Returns: (transfer full): a #GdkPaintable if successful; otherwise %NULL
* and @error is set. * and @error is set.

View File

@ -43,6 +43,13 @@ G_BEGIN_DECLS
typedef struct _MksScreenClass MksScreenClass; 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 typedef enum _MksScreenKind
{ {
MKS_SCREEN_KIND_TEXT = 0, MKS_SCREEN_KIND_TEXT = 0,

View File

@ -28,32 +28,32 @@
#include "mks-session.h" #include "mks-session.h"
/** /**
* SECTION:mks-session * MksSession:
* @Title: MksSession *
* @Short_description: Session connected to a Qemu VM * 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. * 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. * 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 * 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 * Using the same [class@Gio.DBusConnection], create a `MksSession` with
* mks_session_new_for_connection(). The #MksSession instance will negotiate * [func@Mks.Session.new_for_connection]. The `MksSession` instance will negotiate
* with the peer to determine what devices are available and expose them * 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 * # Creating Widgets
* *
* You can create a new widget to embed in your application by waiting for * You can create a new widget to embed in your application by calling
* a #MksScreen to become available in the list model or connecting to the * [method@Mks.Session.ref_screen] and set the screen for the [class@Mks.Display]
* #GObject::notify signal for the #MksSession:screen property. * with [method@Mks.Display.set_screen].
*/ */
static gboolean mks_session_initable_init (GInitable *initable, static gboolean mks_session_initable_init (GInitable *initable,
@ -72,15 +72,15 @@ struct _MksSession
{ {
GObject parent_instance; 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(), * to be a private point-to-point connection over a Unix socket, socketpair(),
* or other channel capable of passing FDs between peers. * or other channel capable of passing FDs between peers.
*/ */
GDBusConnection *connection; 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 * 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. * the devices have been removed, we drop them from the listmodel.
*/ */
GListStore *devices; GListStore *devices;
@ -93,7 +93,7 @@ struct _MksSession
GListModel *devices_read_only; GListModel *devices_read_only;
/* An object manager client is used to monitor for new objects exported by /* 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. * as necessary and exported to consumers via @devices.
*/ */
GDBusObjectManager *object_manager; GDBusObjectManager *object_manager;
@ -365,8 +365,7 @@ mks_session_class_init (MksSessionClass *klass)
/** /**
* MksSession:connection: * MksSession:connection:
* *
* The "connection" property contains the #GDBusConnection that is used * The [class@Gio.DBusConnection] that is used to communicate with QEMU.
* to communicate with Qemu.
*/ */
properties [PROP_CONNECTION] = properties [PROP_CONNECTION] =
g_param_spec_object ("connection", NULL, NULL, g_param_spec_object ("connection", NULL, NULL,
@ -376,8 +375,8 @@ mks_session_class_init (MksSessionClass *klass)
/** /**
* MksSession:devices: * MksSession:devices:
* *
* The "devices" property contains a #GListModel of devices that have been * A [iface@Gio.ListModel] of devices that have been
* discovered on the #GDBusConnection to Qemu. * discovered on the [class@Gio.DBusConnection] to QEMU.
*/ */
properties [PROP_DEVICES] = properties [PROP_DEVICES] =
g_param_spec_object ("devices", NULL, NULL, g_param_spec_object ("devices", NULL, NULL,
@ -387,8 +386,7 @@ mks_session_class_init (MksSessionClass *klass)
/** /**
* MksSession:name: * MksSession:name:
* *
* The "name" property is the named of the VM as specified by the * The VM name as specified by the QEMU instance.
* Qemu instance.
*/ */
properties [PROP_NAME] = properties [PROP_NAME] =
g_param_spec_string ("name", NULL, NULL, g_param_spec_string ("name", NULL, NULL,
@ -398,8 +396,7 @@ mks_session_class_init (MksSessionClass *klass)
/** /**
* MksSession:uuid: * MksSession:uuid:
* *
* The "uuid" property is the unique identifier as specified by the * The VM unique identifier specified by the QEMU instance.
* Qemu instance for the VM.
*/ */
properties [PROP_UUID] = properties [PROP_UUID] =
g_param_spec_string ("uuid", NULL, NULL, 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. * 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. * instance which has devices created using the "dbus" backend.
* @callback will be executed when the session has been created or * @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. * 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. * this operation.
*/ */
void void
@ -610,7 +607,7 @@ mks_session_new_for_connection (GDBusConnection *connection,
* @result: a #GAsyncResult provided to callback * @result: a #GAsyncResult provided to callback
* @error: (nullable): a location for a #GError or %NULL * @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 * Returns: (transfer full): a #MksSession if successful; otherwise %NULL
* and @error is set. * and @error is set.
@ -626,13 +623,13 @@ mks_session_new_for_connection_finish (GAsyncResult *result,
/** /**
* mks_session_new_for_connection_sync: * 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 * @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a location for a #GError, or %NULL * @error: (nullable): a location for a #GError, or %NULL
* *
* Synchronously creates a new #MksSession instance. * 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. * initial devices and VM status.
* *
* Returns: (transfer full): a #MksSession if successful; otherwise %NULL * 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: * mks_session_get_connection:
* @self: a #MksSession * @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 * Returns: (transfer none) (nullable): a #GDBusConnection or %NULL if
* the connection has not been set, or was disposed. * the connection has not been set, or was disposed.
@ -678,7 +675,7 @@ mks_session_get_connection (MksSession *self)
* mks_session_get_uuid: * mks_session_get_uuid:
* @self: a #MksSession * @self: a #MksSession
* *
* Gets the "uuid" property. * Gets the unique identifier of the VM.
*/ */
const char * const char *
mks_session_get_uuid (MksSession *self) mks_session_get_uuid (MksSession *self)
@ -695,7 +692,7 @@ mks_session_get_uuid (MksSession *self)
* mks_session_get_name: * mks_session_get_name:
* @self: a #MksSession * @self: a #MksSession
* *
* Gets the "name" property. * Gets the name of the VM.
*/ */
const char * const char *
mks_session_get_name (MksSession *self) mks_session_get_name (MksSession *self)

View File

@ -28,6 +28,12 @@
#include "mks-speaker.h" #include "mks-speaker.h"
#include "mks-util-private.h" #include "mks-util-private.h"
/**
* MksSpeaker:
*
* A virtualized QEMU speaker.
*/
struct _MksSpeaker struct _MksSpeaker
{ {
MksDevice parent_instance; MksDevice parent_instance;
@ -310,9 +316,8 @@ mks_speaker_class_init (MksSpeakerClass *klass)
/** /**
* MksSpeaker:muted: * MksSpeaker:muted:
* *
* The "muted" property denotes if audio received from the * If audio received from the instance is dropped and
* instance is dropped and the remote sound device should * the remote sound device should attempt to be set as muted.
* attempt to be set as muted.
*/ */
properties [PROP_MUTED] = properties [PROP_MUTED] =
g_param_spec_boolean ("muted", NULL, NULL, g_param_spec_boolean ("muted", NULL, NULL,
@ -348,7 +353,7 @@ mks_speaker_get_muted (MksSpeaker *self)
* @self: a #MksSpeaker * @self: a #MksSpeaker
* @muted: if the speaker should be muted * @muted: if the speaker should be muted
* *
* Sets the #MksSpeaker:muted property. * Mute or un-mute the speaker.
*/ */
void void
mks_speaker_set_muted (MksSpeaker *self, mks_speaker_set_muted (MksSpeaker *self,

View File

@ -70,7 +70,7 @@ int
main (int argc, main (int argc,
char *argv[]) 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(GDBusConnection) connection = NULL;
g_autoptr(MksSession) session = NULL; g_autoptr(MksSession) session = NULL;
g_autoptr(GError) error = NULL; g_autoptr(GError) error = NULL;