Method

GdkSeatgrab

since: 3.20

Declaration [src] 

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
)

Description [src]

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.

Available since: 3.20

Parameters

window

Type: GdkWindow

The GdkWindow which will own the grab.

The data is owned by the caller of the method.
capabilities

Type: GdkSeatCapabilities

Capabilities that will be grabbed.

owner_events

Type: gboolean

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

Type: GdkCursor

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.

The argument can be NULL.
The data is owned by the caller of the method.
event

Type: GdkEvent

The event that is triggering the grab, or NULL if none is available.

The argument can be NULL.
The data is owned by the caller of the method.
prepare_func

Type: GdkSeatGrabPrepareFunc

Function to prepare the window to be grabbed, it can be NULL if window is visible before this call.

The argument can be NULL.
prepare_func_data

Type: gpointer

User data to pass to prepare_func.

The argument can be NULL.
The data is owned by the caller of the method.

Return value

Type: GdkGrabStatus

GDK_GRAB_SUCCESS if the grab was successful.