## 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
             +----GtkObject
                   +----GtkWidget
                         +----GtkDrawingArea
                               +----SpiceDisplay

      GBoxed
       +----SpiceGrabSequence

## Implemented Interfaces

SpiceDisplay implements AtkImplementorIface and GtkBuildable.

## Properties

      "auto-clipboard"           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

## 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()`.

Client and guest clipboards will be shared automatically if "auto-clipboard" is set to TRUE. Alternatively, you can send clipboard data from client to guest with `spice_display_copy_to_guest()`.

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

Copy client-side clipboard to guest clipboard.

### spice_display_paste_from_guest ()

    void                spice_display_paste_from_guest      (SpiceDisplay *display);

### 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 / Construct

Automatically relay clipboard changes between host and guest.

Default value: TRUE

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

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