GdkSeat: GDK 3 Reference Manual

## GdkSeat GdkSeat — Object representing an user seat |

## Functions

void | (*GdkSeatGrabPrepareFunc) ()
GdkDisplay * | gdk_seat_get_display ()
GdkGrabStatus | gdk_seat_grab ()
void | gdk_seat_ungrab ()
GdkSeatCapabilities | gdk_seat_get_capabilities ()
GdkDevice * | gdk_seat_get_pointer ()
GdkDevice * | gdk_seat_get_keyboard ()
GList * | gdk_seat_get_slaves ()

## Properties

GdkDisplay * | display | Read / Write / Construct Only

## Signals

void | device-added | Run Last
void | device-removed | Run Last
void | tool-added | Run Last
void | tool-removed | Run Last

## Types and Values

| GdkSeat
enum | GdkSeatCapabilities

## Object Hierarchy

        GObject
        ╰── GdkSeat

## Includes

    #include <gdk/gdk.h>

## Description

The GdkSeat object represents a collection of input devices that belong to a user.

## Functions

### GdkSeatGrabPrepareFunc ()

    void
    (*GdkSeatGrabPrepareFunc) (GdkSeat *seat,
                               GdkWindow *window,
                               gpointer user_data);

Type of the callback used to set up `window` so it can be grabbed. A typical action would be ensuring the window is visible, although there's room for other initialization actions.

#### Parameters

seat | the GdkSeat being grabbed |
window | the GdkWindow being grabbed |
user_data | user data passed in `gdk_seat_grab()` |

Since: 3.20

### gdk_seat_get_display ()

    GdkDisplay *
    gdk_seat_get_display (GdkSeat *seat);

Returns the GdkDisplay this seat belongs to.

#### Parameters

seat | a GdkSeat |

#### Returns

a GdkDisplay. This object is owned by GTK+ and must not be freed.

[transfer none]

### gdk_seat_grab ()

    GdkGrabStatus
    gdk_seat_grab (GdkSeat *seat,
                   GdkWindow *window,
                   GdkSeatCapabilities capabilities,
                   gboolean owner_events,
                   GdkCursor *cursor,
                   const GdkEvent *event,
                   GdkSeatGrabPrepareFunc prepare_func,
                   gpointer prepare_func_data);

Grabs the seat so that all events corresponding to the given `capabilities` are passed to this application until the seat is ungrabbed with `gdk_seat_ungrab()`, or the window becomes hidden. This overrides any previous grab on the seat by this client.

As a rule of thumb, if a grab is desired over `GDK_SEAT_CAPABILITY_POINTER`, all other "pointing" capabilities (eg. `GDK_SEAT_CAPABILITY_TOUCH`) should be grabbed too, so the user is able to interact with all of those while the grab holds, you should thus use `GDK_SEAT_CAPABILITY_ALL_POINTING` most commonly.

Grabs are used for operations which need complete control over the events corresponding to the given capabilities. For example in GTK+ this is used for Drag and Drop operations, popup menus and such.

Note that if the event mask of a GdkWindow has selected both button press and button release events, or touch begin and touch end, then a press event will cause an automatic grab until the button is released, equivalent to a grab on the window with `owner_events` set to `TRUE`. This is done because most applications expect to receive paired press and release events.

If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the GdkEventGrabBroken events that are emitted when the grab ends unvoluntarily.

#### Parameters

seat | a GdkSeat |
window | the GdkWindow which will own the grab |
capabilities | capabilities that will be grabbed |
owner_events | if `FALSE` then all device events are reported with respect to `window` and are only reported if selected by `event_mask` . If `TRUE` then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to `window` and only if selected by `event_mask` . In either mode, unreported events are discarded. |
cursor | the cursor to display while the grab is active. If this is `NULL` then the normal cursors are used for `window` and its descendants, and the cursor for `window` is used elsewhere. | [nullable]
event | the event that is triggering the grab, or `NULL` if none is available. | [nullable]
prepare_func | function to prepare the window to be grabbed, it can be `NULL` if `window` is visible before this call. | [nullable][scope call][closure prepare_func_data]
prepare_func_data | user data to pass to `prepare_func` |

#### Returns

`GDK_GRAB_SUCCESS` if the grab was successful.

Since: 3.20

### gdk_seat_ungrab ()

    void
    gdk_seat_ungrab (GdkSeat *seat);

Releases a grab added through `gdk_seat_grab()`.

#### Parameters

seat | a GdkSeat |

Since: 3.20

### gdk_seat_get_capabilities ()

    GdkSeatCapabilities
    gdk_seat_get_capabilities (GdkSeat *seat);

Returns the capabilities this GdkSeat currently has.

#### Parameters

seat | a GdkSeat |

#### Returns

the seat capabilities

Since: 3.20

### gdk_seat_get_pointer ()

    GdkDevice *
    gdk_seat_get_pointer (GdkSeat *seat);

Returns the master device that routes pointer events.

#### Parameters

seat | a GdkSeat |

#### Returns

a master GdkDevice with pointer capabilities. This object is owned by GTK+ and must not be freed.

[transfer none][nullable]

Since: 3.20

### gdk_seat_get_keyboard ()

    GdkDevice *
    gdk_seat_get_keyboard (GdkSeat *seat);

Returns the master device that routes keyboard events.

#### Parameters

seat | a GdkSeat |

#### Returns

a master GdkDevice with keyboard capabilities. This object is owned by GTK+ and must not be freed.

[transfer none][nullable]

Since: 3.20

### gdk_seat_get_slaves ()

    GList *
    gdk_seat_get_slaves (GdkSeat *seat,
                         GdkSeatCapabilities capabilities);

Returns the slave devices that match the given capabilities.

#### Parameters

seat | a GdkSeat |
capabilities | capabilities to get devices for |

#### Returns

A list of GdkDevices. The list must be freed with `g_list_free()`, the elements are owned by GDK and must not be freed.

[transfer container][element-type GdkDevice]

Since: 3.20

## Types and Values

### GdkSeat

    typedef struct _GdkSeat GdkSeat;

### enum GdkSeatCapabilities

Flags describing the seat capabilities.

#### Members

GDK_SEAT_CAPABILITY_NONE | No input capabilities |
GDK_SEAT_CAPABILITY_POINTER | The seat has a pointer (e.g. mouse) |
GDK_SEAT_CAPABILITY_TOUCH | The seat has touchscreen(s) attached |
GDK_SEAT_CAPABILITY_TABLET_STYLUS | The seat has drawing tablet(s) attached |
GDK_SEAT_CAPABILITY_KEYBOARD | The seat has keyboard(s) attached |
GDK_SEAT_CAPABILITY_ALL_POINTING | The union of all pointing capabilities |
GDK_SEAT_CAPABILITY_ALL | The union of all capabilities |

Since: 3.20

## Property Details

### The `“display”` property

      “display”                  GdkDisplay *

GdkDisplay of this seat.

Owner: GdkSeat

Flags: Read / Write / Construct Only

Since: 3.20

## Signal Details

### The `“device-added”` signal

    void
    user_function (GdkSeat   *seat,
                   GdkDevice *device,
                   gpointer   user_data)

The ::device-added signal is emitted when a new input device is related to this seat.

#### Parameters

seat | the object on which the signal is emitted |
device | the newly added GdkDevice. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.20

### The `“device-removed”` signal

    void
    user_function (GdkSeat   *seat,
                   GdkDevice *device,
                   gpointer   user_data)

The ::device-removed signal is emitted when an input device is removed (e.g. unplugged).

#### Parameters

seat | the object on which the signal is emitted |
device | the just removed GdkDevice. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.20

### The `“tool-added”` signal

    void
    user_function (GdkSeat       *seat,
                   GdkDeviceTool *tool,
                   gpointer       user_data)

The ::tool-added signal is emitted whenever a new tool is made known to the seat. The tool may later be assigned to a device (i.e. on proximity with a tablet). The device will emit the “tool-changed” signal accordingly.

A same tool may be used by several devices.

#### Parameters

seat | the object on which the signal is emitted |
tool | the new GdkDeviceTool known to the seat |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.22

### The `“tool-removed”` signal

    void
    user_function (GdkSeat       *seat,
                   GdkDeviceTool *tool,
                   gpointer       user_data)

This signal is emitted whenever a tool is no longer known to this `seat` .

#### Parameters

seat | the object on which the signal is emitted |
tool | the just removed GdkDeviceTool |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.22

## See Also

GdkDisplay, GdkDevice