Spice Display

Spice Display — a GTK display widget

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <spice-widget.h>

struct              SpiceDisplay;
struct              SpiceDisplayClass;
enum                SpiceDisplayKeyEvent;
SpiceDisplay *      spice_display_new                   (SpiceSession *session,
                                                         int channel_id);
SpiceDisplay *      spice_display_new_with_monitor      (SpiceSession *session,
                                                         gint channel_id,
                                                         gint monitor_id);
void                spice_display_mouse_ungrab          (SpiceDisplay *display);
void                spice_display_copy_to_guest         (SpiceDisplay *display);
void                spice_display_paste_from_guest      (SpiceDisplay *display);
void                spice_display_set_grab_keys         (SpiceDisplay *display,
                                                         SpiceGrabSequence *seq);
SpiceGrabSequence * spice_display_get_grab_keys         (SpiceDisplay *display);
void                spice_display_send_keys             (SpiceDisplay *display,
                                                         const guint *keyvals,
                                                         int nkeyvals,
                                                         SpiceDisplayKeyEvent kind);
GdkPixbuf *         spice_display_get_pixbuf            (SpiceDisplay *display);

struct              SpiceGrabSequence;
SpiceGrabSequence * spice_grab_sequence_new             (guint nkeysyms,
                                                         guint *keysyms);
SpiceGrabSequence * spice_grab_sequence_new_from_string (const gchar *str);
SpiceGrabSequence * spice_grab_sequence_copy            (SpiceGrabSequence *sequence);
void                spice_grab_sequence_free            (SpiceGrabSequence *sequence);
gchar *             spice_grab_sequence_as_string       (SpiceGrabSequence *sequence);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkDrawingArea
                           +----SpiceDisplay
  GBoxed
   +----SpiceGrabSequence

Implemented Interfaces

SpiceDisplay implements AtkImplementorIface and GtkBuildable.

Properties

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

Signals

  "grab-keys-pressed"                              : Run First
  "keyboard-grab"                                  : Run First
  "mouse-grab"                                     : Run First

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).

Details

struct SpiceDisplay

struct SpiceDisplay;

struct SpiceDisplayClass

struct SpiceDisplayClass {
    GtkDrawingAreaClass parent_class;

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

enum SpiceDisplayKeyEvent

typedef enum {
	SPICE_DISPLAY_KEY_EVENT_PRESS = 1,
	SPICE_DISPLAY_KEY_EVENT_RELEASE = 2,
	SPICE_DISPLAY_KEY_EVENT_CLICK = 3,
} SpiceDisplayKeyEvent;

spice_display_new ()

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

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);

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.


spice_display_copy_to_guest ()

void                spice_display_copy_to_guest         (SpiceDisplay *display);

Warning

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.


spice_display_paste_from_guest ()

void                spice_display_paste_from_guest      (SpiceDisplay *display);

Warning

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.


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".

display :

the display widget

seq :

key sequence. [transfer none]

spice_display_get_grab_keys ()

SpiceGrabSequence * spice_display_get_grab_keys         (SpiceDisplay *display);

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);

spice_display_get_pixbuf ()

GdkPixbuf *         spice_display_get_pixbuf            (SpiceDisplay *display);

Take a screenshot of the display.

Returns :

a GdkPixbuf with the screenshot image buffer. [transfer full]

struct SpiceGrabSequence

struct SpiceGrabSequence {
};

spice_grab_sequence_new ()

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

Creates a new grab sequence from a list of keysym values

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);

str :

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

Returns :

a new SpiceGrabSequence.

spice_grab_sequence_copy ()

SpiceGrabSequence * spice_grab_sequence_copy            (SpiceGrabSequence *sequence);

sequence :

sequence to copy

Returns :

a copy of sequence. [transfer full]

spice_grab_sequence_free ()

void                spice_grab_sequence_free            (SpiceGrabSequence *sequence);

Free sequence.


spice_grab_sequence_as_string ()

gchar *             spice_grab_sequence_as_string       (SpiceGrabSequence *sequence);

Returns :

a newly allocated string representing the key sequence. [transfer full]

Property Details

The "auto-clipboard" property

  "auto-clipboard"           gboolean              : Read / Write

Warning

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

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

Default value: TRUE


The "channel-id" property

  "channel-id"               gint                  : Read / Write / Construct Only

channel-id for this SpiceDisplay

Allowed values: [0,255]

Default value: 0


The "disable-inputs" property

  "disable-inputs"           gboolean              : Read / Write / Construct

Disable all keyboard & mouse inputs.

Default value: FALSE

Since 0.8


The "grab-keyboard" property

  "grab-keyboard"            gboolean              : Read / Write / Construct

Whether we should grab the keyboard.

Default value: TRUE


The "grab-mouse" property

  "grab-mouse"               gboolean              : Read / Write / Construct

Whether we should grab the mouse.

Default value: TRUE


The "keypress-delay" property

  "keypress-delay"           guint                 : Read / Write / Construct

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.

Default value: 100

Since 0.13


The "monitor-id" property

  "monitor-id"               gint                  : Read / Write / Construct

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

Allowed values: >= -1

Default value: 0

Since 0.13


The "only-downscale" property

  "only-downscale"           gboolean              : Read / Write / Construct

If scaling, only scale down, never up.

Default value: FALSE

Since 0.14


The "ready" property

  "ready"                    gboolean              : Read

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..

Default value: FALSE

Since 0.13


The "resize-guest" property

  "resize-guest"             gboolean              : Read / Write / Construct

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

Default value: FALSE


The "scaling" property

  "scaling"                  gboolean              : Read / Write / Construct

Whether we should use scaling.

Default value: TRUE


The "session" property

  "session"                  SpiceSession*         : Read / Write / Construct Only

SpiceSession for this SpiceDisplay


The "zoom-level" property

  "zoom-level"               gint                  : Read / Write / Construct

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

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)      : Run First

Notify when the grab keys have been pressed

display :

the SpiceDisplay that emitted the signal

user_data :

user data set when the signal handler was connected.

The "keyboard-grab" signal

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

Notify when the keyboard grab is active or not.

display :

the SpiceDisplay that emitted the signal

status :

1 if grabbed, 0 otherwise.

user_data :

user data set when the signal handler was connected.

The "mouse-grab" signal

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

Notify when the mouse grab is active or not.

display :

the SpiceDisplay that emitted the signal

status :

1 if grabbed, 0 otherwise.

user_data :

user data set when the signal handler was connected.