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

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

| SpiceDisplay
| SpiceDisplayClass
enum | SpiceDisplayKeyEvent
| SpiceGrabSequence

## Object Hierarchy

        GBoxed
        ╰── SpiceGrabSequence
        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkEventBox
                            ╰── 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_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

### SpiceDisplay

    typedef struct _SpiceDisplay SpiceDisplay;

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

### SpiceDisplayClass

    typedef struct _SpiceDisplayClass SpiceDisplayClass;

Class structure for SpiceDisplay. It is opaque and should not be accessed directly.

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

### SpiceGrabSequence

    typedef struct _SpiceGrabSequence SpiceGrabSequence;

An opaque type that represents a grab sequence.

## Property Details

### The `“channel-id”` property

      “channel-id”               int

channel-id for this SpiceDisplay

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

Owner: SpiceDisplay

Flags: Read / Write / Construct

Default value: FALSE

Since: 0.8

### The `“grab-keyboard”` property

      “grab-keyboard”            gboolean

Whether we should grab the keyboard.

Owner: SpiceDisplay

Flags: Read / Write / Construct

Default value: TRUE

### The `“grab-mouse”` property

      “grab-mouse”               gboolean

Whether we should grab the mouse.

Owner: SpiceDisplay

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.

Owner: SpiceDisplay

Flags: Read / Write / Construct

Default value: 100

Since: 0.13

### The `“monitor-id”` property

      “monitor-id”               int

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

Owner: SpiceDisplay

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.

Owner: SpiceDisplay

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

Owner: SpiceDisplay

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.

Owner: SpiceDisplay

Flags: Read / Write / Construct

Default value: FALSE

### The `“scaling”` property

      “scaling”                  gboolean

Whether we should use scaling.

Owner: SpiceDisplay

Flags: Read / Write / Construct

Default value: TRUE

### The `“session”` property

      “session”                  SpiceSession *

SpiceSession for this SpiceDisplay

Owner: SpiceDisplay

Flags: Read / Write / Construct Only

### The `“zoom-level”` property

      “zoom-level”               int

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

Owner: SpiceDisplay

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,
                   int           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,
                   int           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