CdkSeat

CdkSeat — Object representing an user seat

Functions

void (*CdkSeatGrabPrepareFunc) ()
CdkDisplay * cdk_seat_get_display ()
CdkGrabStatus cdk_seat_grab ()
void cdk_seat_ungrab ()
CdkSeatCapabilities cdk_seat_get_capabilities ()
CdkDevice * cdk_seat_get_pointer ()
CdkDevice * cdk_seat_get_keyboard ()
GList * cdk_seat_get_slaves ()

Properties

CdkDisplay * 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

  CdkSeat
enum CdkSeatCapabilities

Object Hierarchy

    GObject
    ╰── CdkSeat

Includes

#include <cdk/cdk.h>

Description

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

Functions

CdkSeatGrabPrepareFunc ()

void
(*CdkSeatGrabPrepareFunc) (CdkSeat *seat,
                           CdkWindow *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 CdkSeat being grabbed

  

window

the CdkWindow being grabbed

  

user_data

user data passed in cdk_seat_grab()

  

Since: 3.20

cdk_seat_get_display ()

CdkDisplay *
cdk_seat_get_display (CdkSeat *seat);

Returns the CdkDisplay this seat belongs to.

Parameters

seat

a CdkSeat

  

Returns

a CdkDisplay. This object is owned by CTK+ and must not be freed.

[transfer none]

cdk_seat_grab ()

CdkGrabStatus
cdk_seat_grab (CdkSeat *seat,
               CdkWindow *window,
               CdkSeatCapabilities capabilities,
               gboolean owner_events,
               CdkCursor *cursor,
               const CdkEvent *event,
               CdkSeatGrabPrepareFunc 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 cdk_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 CDK_SEAT_CAPABILITY_POINTER, all other "pointing" capabilities (eg. CDK_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 CDK_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 CTK+ this is used for Drag and Drop operations, popup menus and such.

Note that if the event mask of a CdkWindow 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 CdkEventGrabBroken events that are emitted when the grab ends unvoluntarily.

Parameters

seat

a CdkSeat

  

window

the CdkWindow 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

CDK_GRAB_SUCCESS if the grab was successful.

Since: 3.20

cdk_seat_ungrab ()

void
cdk_seat_ungrab (CdkSeat *seat);

Releases a grab added through cdk_seat_grab().

Parameters

seat

a CdkSeat

  

Since: 3.20

cdk_seat_get_capabilities ()

CdkSeatCapabilities
cdk_seat_get_capabilities (CdkSeat *seat);

Returns the capabilities this CdkSeat currently has.

Parameters

seat

a CdkSeat

  

Returns

the seat capabilities

Since: 3.20

cdk_seat_get_pointer ()

CdkDevice *
cdk_seat_get_pointer (CdkSeat *seat);

Returns the master device that routes pointer events.

Parameters

seat

a CdkSeat

  

Returns

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

[transfer none][nullable]

Since: 3.20

cdk_seat_get_keyboard ()

CdkDevice *
cdk_seat_get_keyboard (CdkSeat *seat);

Returns the master device that routes keyboard events.

Parameters

seat

a CdkSeat

  

Returns

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

[transfer none][nullable]

Since: 3.20

cdk_seat_get_slaves ()

GList *
cdk_seat_get_slaves (CdkSeat *seat,
                     CdkSeatCapabilities capabilities);

Returns the slave devices that match the given capabilities.

Parameters

seat

a CdkSeat

  

capabilities

capabilities to get devices for

  

Returns

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

[transfer container][element-type CdkDevice]

Since: 3.20

Types and Values

CdkSeat

typedef struct _CdkSeat CdkSeat;

enum CdkSeatCapabilities

Flags describing the seat capabilities.

Members

CDK_SEAT_CAPABILITY_NONE

No input capabilities

  

CDK_SEAT_CAPABILITY_POINTER

The seat has a pointer (e.g. mouse)

  

CDK_SEAT_CAPABILITY_TOUCH

The seat has touchscreen(s) attached

  

CDK_SEAT_CAPABILITY_TABLET_STYLUS

The seat has drawing tablet(s) attached

  

CDK_SEAT_CAPABILITY_KEYBOARD

The seat has keyboard(s) attached

  

CDK_SEAT_CAPABILITY_ALL_POINTING

The union of all pointing capabilities

  

CDK_SEAT_CAPABILITY_ALL

The union of all capabilities

  

Since: 3.20

Property Details

The “display” property

  “display”                  CdkDisplay *

CdkDisplay of this seat.

Owner: CdkSeat

Flags: Read / Write / Construct Only

Since: 3.20

Signal Details

The “device-added” signal

void
user_function (CdkSeat   *seat,
               CdkDevice *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 CdkDevice.

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since: 3.20

The “device-removed” signal

void
user_function (CdkSeat   *seat,
               CdkDevice *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 CdkDevice.

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since: 3.20

The “tool-added” signal

void
user_function (CdkSeat       *seat,
               CdkDeviceTool *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 CdkDeviceTool 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 (CdkSeat       *seat,
               CdkDeviceTool *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 CdkDeviceTool

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since: 3.22

See Also

CdkDisplay, CdkDevice

Generated by GTK-Doc V1.36.1