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 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
         +----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
  "resize-guest"             gboolean              : Read / Write / Construct
  "scaling"                  gboolean              : Read / Write / Construct
  "session"                  SpiceSession*         : Read / Write / Construct Only

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

session :

a SpiceSession

id :

the display channel ID to associate with SpiceDisplay

Returns :

a new SpiceDisplay widget.

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

seq :

key sequence

spice_display_get_grab_keys ()

SpiceGrabSequence * spice_display_get_grab_keys         (SpiceDisplay *display);

Returns :

the current grab key combination.

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

nkeysyms :

GDK_ key values

keysyms :

number of key values in nkeysyms

Returns :

a new SpiceGrabSequence.

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

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 "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: FALSE


The "session" property

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

SpiceSession for this SpiceDisplay

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.