Spice Display: Spice-GTK Reference Manual

Spice Display

Spice Display — a GTK display widget

Stability Level

Stable, unless otherwise indicated

Functions

SpiceDisplay *	spice_display_new ()
SpiceDisplay *	spice_display_new_with_monitor ()
void	spice_display_mouse_ungrab ()
void	spice_display_copy_to_guest ()
void	spice_display_paste_from_guest ()
void	spice_display_set_grab_keys ()
SpiceGrabSequence *	spice_display_get_grab_keys ()
void	spice_display_send_keys ()
GdkPixbuf *	spice_display_get_pixbuf ()
SpiceGrabSequence *	spice_grab_sequence_new ()
SpiceGrabSequence *	spice_grab_sequence_new_from_string ()
SpiceGrabSequence *	spice_grab_sequence_copy ()
void	spice_grab_sequence_free ()
gchar *	spice_grab_sequence_as_string ()

Properties

gboolean	auto-clipboard	Read / Write
gint	channel-id	Read / Write / Construct Only
gboolean	disable-inputs	Read / Write / Construct
gboolean	grab-keyboard	Read / Write / Construct
gboolean	grab-mouse	Read / Write / Construct
guint	keypress-delay	Read / Write / Construct
gint	monitor-id	Read / Write / Construct
gboolean	only-downscale	Read / Write / Construct
gboolean	ready	Read
gboolean	resize-guest	Read / Write / Construct
gboolean	scaling	Read / Write / Construct
SpiceSession *	session	Read / Write / Construct Only
gint	zoom-level	Read / Write / Construct

Signals

void	grab-keys-pressed	Run First
void	keyboard-grab	Run First
void	mouse-grab	Run First

Types and Values

struct	SpiceDisplay
struct	SpiceDisplayClass
enum	SpiceDisplayKeyEvent
struct	SpiceGrabSequence

Object Hierarchy

    GBoxed
    ╰── SpiceGrabSequence
    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkDrawingArea
                ╰── SpiceDisplay

Implemented Interfaces

SpiceDisplay implements AtkImplementorIface and GtkBuildable.

Includes

#include <spice-client-gtk.h>

Description

A GTK widget that displays a SPICE server. It sends keyboard/mouse events and can also share clipboard...

Arbitrary key events can be sent thanks to spice_display_send_keys().

The widget will optionally grab the keyboard and the mouse when focused if the properties “grab-keyboard” and “grab-mouse” are TRUE respectively. It can be ungrabbed with spice_display_mouse_ungrab(), and by setting a key combination with spice_display_set_grab_keys().

Finally, spice_display_get_pixbuf() will take a screenshot of the current display and return an GdkPixbuf (that you can then easily save to disk).

Functions

spice_display_new ()

SpiceDisplay *
spice_display_new (SpiceSession *session,
                   int channel_id);

Creates a new SpiceDisplay widget.

Parameters

session	a SpiceSession
channel_id	the display channel ID to associate with SpiceDisplay

Returns

a new SpiceDisplay widget.

spice_display_new_with_monitor ()

SpiceDisplay *
spice_display_new_with_monitor (SpiceSession *session,
                                gint channel_id,
                                gint monitor_id);

Creates a new SpiceDisplay widget associated with the monitor id.

Parameters

session	a SpiceSession
channel_id	the display channel ID to associate with SpiceDisplay
monitor_id	the monitor id within the display channel

Returns

a new SpiceDisplay widget.

Since: 0.13

spice_display_mouse_ungrab ()

void
spice_display_mouse_ungrab (SpiceDisplay *display);

Ungrab the mouse.

Parameters

display

a SpiceDisplay

spice_display_copy_to_guest ()

void
spice_display_copy_to_guest (SpiceDisplay *display);

spice_display_copy_to_guest has been deprecated since version 0.8 and should not be used in newly-written code.

Use spice_gtk_session_copy_to_guest() instead

Copy client-side clipboard to guest clipboard.

Parameters

display

a SpiceDisplay

spice_display_paste_from_guest ()

void
spice_display_paste_from_guest (SpiceDisplay *display);

spice_display_paste_from_guest has been deprecated since version 0.8 and should not be used in newly-written code.

Use spice_gtk_session_paste_from_guest() instead

Copy guest clipboard to client-side clipboard.

Parameters

display

a SpiceDisplay

spice_display_set_grab_keys ()

void
spice_display_set_grab_keys (SpiceDisplay *display,
                             SpiceGrabSequence *seq);

Set the key combination to grab/ungrab the keyboard. The default is "Control L + Alt L".

Parameters

display	the display widget
seq	key sequence.	[transfer none]

spice_display_get_grab_keys ()

SpiceGrabSequence *
spice_display_get_grab_keys (SpiceDisplay *display);

Finds the current grab key combination for the display .

Parameters

display

the display widget

Returns

the current grab key combination.

[transfer none]

spice_display_send_keys ()

void
spice_display_send_keys (SpiceDisplay *display,
                         const guint *keyvals,
                         int nkeyvals,
                         SpiceDisplayKeyEvent kind);

Send keyval press/release events to the display.

Parameters

display	The SpiceDisplay
keyvals	Keyval array.	[array length=nkeyvals]
nkeyvals	Length of keyvals
kind	SpiceDisplayKeyEvent action

spice_display_get_pixbuf ()

GdkPixbuf *
spice_display_get_pixbuf (SpiceDisplay *display);

Take a screenshot of the display.

Parameters

display

a SpiceDisplay

Returns

a GdkPixbuf with the screenshot image buffer.

[transfer full]

spice_grab_sequence_new ()

SpiceGrabSequence *
spice_grab_sequence_new (guint nkeysyms,
                         guint *keysyms);

Creates a new grab sequence from a list of keysym values

Parameters

nkeysyms	length of `keysyms`
keysyms	the keysym values.	[array length=nkeysyms]

Returns

a new grab sequence object.

[transfer full]

spice_grab_sequence_new_from_string ()

SpiceGrabSequence *
spice_grab_sequence_new_from_string (const gchar *str);

Creates a new SpiceGrabSequence from the string representation.

Parameters

str

a string of '+' separated key names (ex: "Control_L+Alt_L")

Returns

a new SpiceGrabSequence.

spice_grab_sequence_copy ()

SpiceGrabSequence *
spice_grab_sequence_copy (SpiceGrabSequence *sequence);

Creates a copy of the sequence .

Parameters

sequence

sequence to copy

Returns

a copy of sequence .

[transfer full]

spice_grab_sequence_free ()

void
spice_grab_sequence_free (SpiceGrabSequence *sequence);

Free sequence .

Parameters

sequence

a SpiceGrabSequence

spice_grab_sequence_as_string ()

gchar *
spice_grab_sequence_as_string (SpiceGrabSequence *sequence);

Creates a string representing the sequence .

Parameters

sequence

a SpiceGrabSequence

Returns

a newly allocated string representing the key sequence.

[transfer full]

Types and Values

struct SpiceDisplay

struct SpiceDisplay;

The SpiceDisplay struct is opaque and should not be accessed directly.

struct SpiceDisplayClass

struct SpiceDisplayClass {
    GtkDrawingAreaClass parent_class;

    /* signals */
    void (*mouse_grab)(SpiceChannel *channel, gint grabbed);
    void (*keyboard_grab)(SpiceChannel *channel, gint grabbed);
};

Class structure for SpiceDisplay.

Members

GtkDrawingAreaClass `parent_class`;	Parent class.
`mouse_grab` ()	Signal class handler for the “mouse_grab” signal.
`keyboard_grab` ()	Signal class handler for the “keyboard_grab” signal.

enum SpiceDisplayKeyEvent

Constants for key events.

Members

SPICE_DISPLAY_KEY_EVENT_PRESS	key press
SPICE_DISPLAY_KEY_EVENT_RELEASE	key release
SPICE_DISPLAY_KEY_EVENT_CLICK	key click (press and release)

struct SpiceGrabSequence

struct SpiceGrabSequence {
};

The SpiceGrabSequence struct is opaque and should not be accessed directly.

Property Details

The `“auto-clipboard”` property

  “auto-clipboard”           gboolean

When this is true the clipboard gets automatically shared between host and guest.

SpiceDisplay:auto-clipboard has been deprecated since version 0.8 and should not be used in newly-written code.

Use SpiceGtkSession:auto-clipboard property instead

Flags: Read / Write

Default value: TRUE

The `“channel-id”` property

  “channel-id”               gint

channel-id for this SpiceDisplay

Flags: Read / Write / Construct Only

Allowed values: [0,255]

Default value: 0

The `“disable-inputs”` property

  “disable-inputs”           gboolean

Disable all keyboard & mouse inputs.

Flags: Read / Write / Construct

Default value: FALSE

Since: 0.8

The `“grab-keyboard”` property

  “grab-keyboard”            gboolean

Whether we should grab the keyboard.

Flags: Read / Write / Construct

Default value: TRUE

The `“grab-mouse”` property

  “grab-mouse”               gboolean

Whether we should grab the mouse.

Flags: Read / Write / Construct

Default value: TRUE

The `“keypress-delay”` property

  “keypress-delay”           guint

Delay in ms of non-modifiers key press events. If the key is released before this delay, a single press & release event is sent to the server. If the key is pressed longer than the keypress-delay, the server will receive the delayed press event, and a following release event when the key is released.

Flags: Read / Write / Construct

Default value: 100

Since: 0.13

The `“monitor-id”` property

  “monitor-id”               gint

Select monitor from SpiceDisplay to show. The value -1 means the whole display is shown. By default, the monitor 0 is selected.

Flags: Read / Write / Construct

Allowed values: >= -1

Default value: 0

Since: 0.13

The `“only-downscale”` property

  “only-downscale”           gboolean

If scaling, only scale down, never up.

Flags: Read / Write / Construct

Default value: FALSE

Since: 0.14

The `“ready”` property

  “ready”                    gboolean

Indicate whether the display is ready to be shown. It takes into account several conditions, such as the channel display "mark" state, whether the monitor area is visible..

Flags: Read

Default value: FALSE

Since: 0.13

The `“resize-guest”` property

  “resize-guest”             gboolean

Try to adapt guest display on window resize. Requires guest cooperation.

Flags: Read / Write / Construct

Default value: FALSE

The `“scaling”` property

  “scaling”                  gboolean

Whether we should use scaling.

Flags: Read / Write / Construct

Default value: TRUE

The `“session”` property

  “session”                  SpiceSession *

SpiceSession for this SpiceDisplay

Flags: Read / Write / Construct Only

The `“zoom-level”` property

  “zoom-level”               gint

Zoom level in percentage, from 10 to 400. Default to 100. (this option is only supported with cairo backend when scaling is enabled)

Flags: Read / Write / Construct

Allowed values: [10,400]

Default value: 100

Since: 0.10

Signal Details

The `“grab-keys-pressed”` signal

void
user_function (SpiceDisplay *display,
               gpointer      user_data)

Notify when the grab keys have been pressed

Parameters

display	the SpiceDisplay that emitted the signal
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“keyboard-grab”` signal

void
user_function (SpiceDisplay *display,
               gint          status,
               gpointer      user_data)

Notify when the keyboard grab is active or not.

Parameters

display	the SpiceDisplay that emitted the signal
status	1 if grabbed, 0 otherwise.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“mouse-grab”` signal

void
user_function (SpiceDisplay *display,
               gint          status,
               gpointer      user_data)

Notify when the mouse grab is active or not.

Parameters

display	the SpiceDisplay that emitted the signal
status	1 if grabbed, 0 otherwise.
user_data	user data set when the signal handler was connected.

Flags: Run First

Spice Display

Stability Level

Functions

Properties

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Includes

Description

Functions

spice_display_new ()

Parameters

Returns

spice_display_new_with_monitor ()

Parameters

Returns

spice_display_mouse_ungrab ()

Parameters

spice_display_copy_to_guest ()

Parameters

spice_display_paste_from_guest ()

Parameters

spice_display_set_grab_keys ()

Parameters

spice_display_get_grab_keys ()

Parameters

Returns

spice_display_send_keys ()

Parameters

spice_display_get_pixbuf ()

Parameters

Returns

spice_grab_sequence_new ()

Parameters

Returns

spice_grab_sequence_new_from_string ()

Parameters

Returns

spice_grab_sequence_copy ()

Parameters

Returns

spice_grab_sequence_free ()

Parameters

spice_grab_sequence_as_string ()

Parameters

Returns

Types and Values

struct SpiceDisplay

struct SpiceDisplayClass

Members

enum SpiceDisplayKeyEvent

Members

struct SpiceGrabSequence

Property Details

The “auto-clipboard” property

The “channel-id” property

The “disable-inputs” property

The “grab-keyboard” property

The “grab-mouse” property

The “keypress-delay” property

The “monitor-id” property

The “only-downscale” property

The “ready” property

The “resize-guest” property

The “scaling” property

The “session” property

The “zoom-level” property

Signal Details

The “grab-keys-pressed” signal

Parameters

The “keyboard-grab” signal

Parameters

The “mouse-grab” signal

Parameters

The `“auto-clipboard”` property

The `“channel-id”` property

The `“disable-inputs”` property

The `“grab-keyboard”` property

The `“grab-mouse”` property

The `“keypress-delay”` property

The `“monitor-id”` property

The `“only-downscale”` property

The `“ready”` property

The `“resize-guest”` property

The `“scaling”` property

The `“session”` property

The `“zoom-level”` property

The `“grab-keys-pressed”` signal

The `“keyboard-grab”` signal

The `“mouse-grab”` signal