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

Generated by GTK-Doc V1.33.1