GdkSeat

GdkSeat — Object representing an user seat

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

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,
                           GdkSurface *surface,
                           gpointer user_data);

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

Parameters

seat

the GdkSeat being grabbed

 

surface

the GdkSurface being grabbed

 

user_data

user data passed in gdk_seat_grab()

 

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,
               GdkSurface *surface,
               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 surface 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 GdkSurface 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 surface 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

 

surface

the GdkSurface which will own the grab

 

capabilities

capabilities that will be grabbed

 

owner_events

if FALSE then all device events are reported with respect to surface 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 surface 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 surface and its descendants, and the cursor for surface 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 surface to be grabbed, it can be NULL if surface 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.


gdk_seat_ungrab ()

void
gdk_seat_ungrab (GdkSeat *seat);

Releases a grab added through gdk_seat_grab().

Parameters

seat

a GdkSeat

 

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


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]


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]


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]


gdk_seat_get_master_pointers ()

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

Returns all master pointers with the given capabilities driven by this seat . On most backends this function will return a list with a single element (meaning that all input devices drive the same onscreen cursor).

In other backends where there can possibly be multiple foci (eg. wayland), this function will return all master GdkDevices that represent these.

Parameters

seat

The GdkSeat

 

capabilities

Queried capabilities

 

Returns

A list of master pointing devices.

[transfer container][element-type GdkDevice]

Types and Values

GdkSeat

typedef struct _GdkSeat GdkSeat;

The GdkSeat struct contains only private fields and should not be accessed directly.


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_TABLET_PAD

The seat has drawing tablet pad(s) attached

 

GDK_SEAT_CAPABILITY_ALL_POINTING

The union of all pointing capabilities

 

GDK_SEAT_CAPABILITY_ALL

The union of all capabilities

 

enum GdkGrabStatus

Returned by gdk_device_grab() to indicate success or the reason for the failure of the grab attempt.

Members

GDK_GRAB_SUCCESS

the resource was successfully grabbed.

 

GDK_GRAB_ALREADY_GRABBED

the resource is actively grabbed by another client.

 

GDK_GRAB_INVALID_TIME

the resource was grabbed more recently than the specified time.

 

GDK_GRAB_NOT_VIEWABLE

the grab surface or the confine_to surface are not viewable.

 

GDK_GRAB_FROZEN

the resource is frozen by an active grab of another client.

 

GDK_GRAB_FAILED

the grab failed for some other reason

 

Property Details

The “display” property

  “display”                  GdkDisplay *

GdkDisplay of this seat.

Flags: Read / Write / Construct Only

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


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


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


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

See Also

GdkDisplay, GdkDevice