gtkmm  3.93.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gdk::Seat Class Reference

A Gdk::Seat object represents a collection of input devices that belong to a user. More...

#include <gdkmm/seat.h>

Inheritance diagram for Gdk::Seat:
Inheritance graph
[legend]

Public Types

enum  Capabilities {
  Capabilities::NONE = 0x0,
  Capabilities::POINTER = 1 << 0,
  Capabilities::TOUCH = 1 << 1,
  Capabilities::TABLET_STYLUS = 1 << 2,
  Capabilities::KEYBOARD = 1 << 3,
  Capabilities::TABLET_PAD = 1 << 4,
  Capabilities::ALL_POINTING = 0x7,
  Capabilities::ALL = 0xF
}
 Flags describing the seat capabilities. More...
 
typedef sigc::slot< void(const Glib::RefPtr< Window >&)> SlotGrabPrepare
 For instance,
void on_grab_prepare(const Glib::RefPtr<Gdk::Window>& window);. More...
 
- Public Types inherited from Glib::Object
typedef void(*)(gpointer data DestroyNotify)
 
- Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify func_destroy_notify
 

Public Member Functions

 Seat (Seat&& src) noexcept
 
Seatoperator= (Seat&& src) noexcept
 
 ~Seat () noexcept override
 
GdkSeat* gobj ()
 Provides access to the underlying C GObject. More...
 
const GdkSeat* gobj () const
 Provides access to the underlying C GObject. More...
 
GdkSeat* gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
 
GrabStatus grab (const Glib::RefPtr< Window >& window, Capabilities capabilities, bool owner_events, const Glib::RefPtr< Cursor >& cursor=Glib::RefPtr< Cursor >(), const Glib::RefPtr< const Event >& event={}, const SlotGrabPrepare& slot=SlotGrabPrepare())
 Grabs the seat so that all events corresponding to the given capabilities are passed to this application until the seat is ungrabbed with ungrab(), or the window becomes hidden. More...
 
void ungrab ()
 Releases a grab added through grab(). More...
 
Glib::RefPtr< Displayget_display ()
 Returns the Gdk::Display this seat belongs to. More...
 
Glib::RefPtr< const Displayget_display () const
 Returns the Gdk::Display this seat belongs to. More...
 
Capabilities get_capabilities () const
 Returns the capabilities this Gdk::Seat currently has. More...
 
std::vector< Glib::RefPtr< Device > > get_slaves (Capabilities capabilities)
 Returns the slave devices that match the given capabilities. More...
 
std::vector< Glib::RefPtr< const Device > > get_slaves (Capabilities capabilities) const
 Returns the slave devices that match the given capabilities. More...
 
Glib::RefPtr< Deviceget_pointer ()
 Returns the master device that routes pointer events. More...
 
Glib::RefPtr< const Deviceget_pointer () const
 Returns the master device that routes pointer events. More...
 
Glib::RefPtr< Deviceget_keyboard ()
 Returns the master device that routes keyboard events. More...
 
Glib::RefPtr< const Deviceget_keyboard () const
 Returns the master device that routes keyboard events. More...
 
std::vector< Glib::RefPtr< Device > > get_master_pointers (Capabilities capabilities)
 Returns all master pointers with the given capabilities driven by this seat. More...
 
std::vector< Glib::RefPtr< const Device > > get_master_pointers (Capabilities capabilities) const
 Returns all master pointers with the given capabilities driven by this seat. More...
 
Glib::SignalProxy< void(const Glib::RefPtr< Device >&)> signal_device_added ()
 
Glib::SignalProxy< void(const Glib::RefPtr< Device >&)> signal_device_removed ()
 
Glib::SignalProxy< void(const Glib::RefPtr< DeviceTool >&)> signal_tool_added ()
 
Glib::SignalProxy< void(const Glib::RefPtr< DeviceTool >&)> signal_tool_removed ()
 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Display > > property_display () const
 Gdk::Display of this seat. More...
 
- Public Member Functions inherited from Glib::Object
 Object (const Object &)=delete
 
Objectoperator= (const Object &)=delete
 
 Object (Object &&src) noexcept
 
Objectoperator= (Object &&src) noexcept
 
void * get_data (const QueryQuark &key)
 
void set_data (const Quark &key, void *data)
 
void set_data (const Quark &key, void *data, DestroyNotify notify)
 
void remove_data (const QueryQuark &quark)
 
void * steal_data (const QueryQuark &quark)
 
Glib::RefPtr< Glib::Objectwrap (GObject *object, bool take_copy=false)
 
- Public Member Functions inherited from Glib::ObjectBase
 ObjectBase (const ObjectBase &)=delete
 
ObjectBaseoperator= (const ObjectBase &)=delete
 
void set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
 
void get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
 
void set_property (const Glib::ustring &property_name, const PropertyType &value)
 
void get_property (const Glib::ustring &property_name, PropertyType &value) const
 
PropertyType get_property (const Glib::ustring &property_name) const
 
sigc::connection connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
 
sigc::connection connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
 
void freeze_notify ()
 
void thaw_notify ()
 
virtual void reference () const
 
virtual void unreference () const
 
GObject * gobj ()
 
const GObject * gobj () const
 
GObject * gobj_copy () const
 
- Public Member Functions inherited from sigc::trackable
 trackable () noexcept
 
 trackable (const trackable &src) noexcept
 
 trackable (trackable &&src)
 
 ~trackable ()
 
void add_destroy_notify_callback (void *data, func_destroy_notify func) const
 
void notify_callbacks ()
 
trackableoperator= (const trackable &src)
 
trackableoperator= (trackable &&src)
 
void remove_destroy_notify_callback (void *data) const
 

Static Public Member Functions

static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system. More...
 

Protected Member Functions

 Seat ()
 
- Protected Member Functions inherited from Glib::Object
 Object ()
 
 Object (const Glib::ConstructParams &construct_params)
 
 Object (GObject *castitem)
 
 ~Object () noexcept override
 
- Protected Member Functions inherited from Glib::ObjectBase
 ObjectBase ()
 
 ObjectBase (const char *custom_type_name)
 
 ObjectBase (const std::type_info &custom_type_info)
 
 ObjectBase (ObjectBase &&src) noexcept
 
ObjectBaseoperator= (ObjectBase &&src) noexcept
 
virtual ~ObjectBase () noexcept=0
 
void initialize (GObject *castitem)
 
void initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)
 

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< Gdk::Seatwrap (GdkSeat* object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

Detailed Description

A Gdk::Seat object represents a collection of input devices that belong to a user.

Since gtkmm 3.20:

Member Typedef Documentation

◆ SlotGrabPrepare

For instance,
void on_grab_prepare(const Glib::RefPtr<Gdk::Window>& window);.

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
windowThe Gdk::Window being grabbed.
Since gtkmm 3.20:

Constructor & Destructor Documentation

◆ Seat() [1/2]

Gdk::Seat::Seat ( Seat&&  src)
noexcept

◆ ~Seat()

Gdk::Seat::~Seat ( )
overridenoexcept

◆ Seat() [2/2]

Gdk::Seat::Seat ( )
protected

Member Function Documentation

◆ get_capabilities()

Capabilities Gdk::Seat::get_capabilities ( ) const

Returns the capabilities this Gdk::Seat currently has.

Returns
The seat capabilities.

◆ get_display() [1/2]

Glib::RefPtr<Display> Gdk::Seat::get_display ( )

Returns the Gdk::Display this seat belongs to.

Returns
A Gdk::Display. This object is owned by GTK+ and must not be freed.

◆ get_display() [2/2]

Glib::RefPtr<const Display> Gdk::Seat::get_display ( ) const

Returns the Gdk::Display this seat belongs to.

Returns
A Gdk::Display. This object is owned by GTK+ and must not be freed.

◆ get_keyboard() [1/2]

Glib::RefPtr<Device> Gdk::Seat::get_keyboard ( )

Returns the master device that routes keyboard events.

Returns
A master Gdk::Device with keyboard capabilities. This object is owned by GTK+ and must not be freed.

◆ get_keyboard() [2/2]

Glib::RefPtr<const Device> Gdk::Seat::get_keyboard ( ) const

Returns the master device that routes keyboard events.

Returns
A master Gdk::Device with keyboard capabilities. This object is owned by GTK+ and must not be freed.

◆ get_master_pointers() [1/2]

std::vector<Glib::RefPtr<Device> > Gdk::Seat::get_master_pointers ( Capabilities  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 Gdk::Devices that represent these.

Parameters
capabilitiesQueried capabilities.
Returns
A list of master pointing devices.

◆ get_master_pointers() [2/2]

std::vector<Glib::RefPtr<const Device> > Gdk::Seat::get_master_pointers ( Capabilities  capabilities) const

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 Gdk::Devices that represent these.

Parameters
capabilitiesQueried capabilities.
Returns
A list of master pointing devices.

◆ get_pointer() [1/2]

Glib::RefPtr<Device> Gdk::Seat::get_pointer ( )

Returns the master device that routes pointer events.

Returns
A master Gdk::Device with pointer capabilities. This object is owned by GTK+ and must not be freed.

◆ get_pointer() [2/2]

Glib::RefPtr<const Device> Gdk::Seat::get_pointer ( ) const

Returns the master device that routes pointer events.

Returns
A master Gdk::Device with pointer capabilities. This object is owned by GTK+ and must not be freed.

◆ get_slaves() [1/2]

std::vector<Glib::RefPtr<Device> > Gdk::Seat::get_slaves ( Capabilities  capabilities)

Returns the slave devices that match the given capabilities.

Parameters
capabilitiesCapabilities to get devices for.
Returns
A list of Gdk::Devices.

◆ get_slaves() [2/2]

std::vector<Glib::RefPtr<const Device> > Gdk::Seat::get_slaves ( Capabilities  capabilities) const

Returns the slave devices that match the given capabilities.

Parameters
capabilitiesCapabilities to get devices for.
Returns
A list of Gdk::Devices.

◆ get_type()

static GType Gdk::Seat::get_type ( )
static

Get the GType for this class, for use with the underlying GObject type system.

◆ gobj() [1/2]

GdkSeat* Gdk::Seat::gobj ( )
inline

Provides access to the underlying C GObject.

◆ gobj() [2/2]

const GdkSeat* Gdk::Seat::gobj ( ) const
inline

Provides access to the underlying C GObject.

◆ gobj_copy()

GdkSeat* Gdk::Seat::gobj_copy ( )

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

◆ grab()

GrabStatus Gdk::Seat::grab ( const Glib::RefPtr< Window >&  window,
Capabilities  capabilities,
bool  owner_events,
const Glib::RefPtr< Cursor >&  cursor = Glib::RefPtrCursor >(),
const Glib::RefPtr< const Event >&  event = {},
const SlotGrabPrepare slot = SlotGrabPrepare() 
)

Grabs the seat so that all events corresponding to the given capabilities are passed to this application until the seat is ungrabbed with 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::Capabilities::POINTER, all other "pointing" capabilities (eg. Gdk::Seat::Capabilities::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::Capabilities::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 Gdk::Window 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 Gdk::EventGrabBroken events that are emitted when the grab ends unvoluntarily.

Parameters
windowThe Gdk::Window which will own the grab.
capabilitiesCapabilities that will be grabbed.
owner_eventsIf 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.
cursorThe cursor to display while the grab is active. If this is nullptr then the normal cursors are used for window and its descendants, and the cursor for window is used elsewhere.
eventThe event that is triggering the grab, or nullptr if none is available.
slotFunction to prepare the window to be grabbed, it can be nullptr if window is visible before this call.
Returns
Gdk::GrabStatus::SUCCESS if the grab was successful.

◆ operator=()

Seat& Gdk::Seat::operator= ( Seat&&  src)
noexcept

◆ property_display()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Display> > Gdk::Seat::property_display ( ) const

Gdk::Display of this seat.

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ signal_device_added()

Glib::SignalProxy<void(const Glib::RefPtr<Device>&)> Gdk::Seat::signal_device_added ( )
Slot Prototype:
void on_my_device_added(const Glib::RefPtr<Device>& device)

Flags: Run Last

The signal_device_added() signal is emitted when a new input device is related to this seat.

Parameters
deviceThe newly added Gdk::Device.

◆ signal_device_removed()

Glib::SignalProxy<void(const Glib::RefPtr<Device>&)> Gdk::Seat::signal_device_removed ( )
Slot Prototype:
void on_my_device_removed(const Glib::RefPtr<Device>& device)

Flags: Run Last

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

Parameters
deviceThe just removed Gdk::Device.

◆ signal_tool_added()

Glib::SignalProxy<void(const Glib::RefPtr<DeviceTool>&)> Gdk::Seat::signal_tool_added ( )
Slot Prototype:
void on_my_tool_added(const Glib::RefPtr<DeviceTool>& device)

Flags: Run Last

The signal_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 Gdk::Device::signal_tool_changed() signal accordingly.

A same tool may be used by several devices.

Since gtkmm 3.94:
Parameters
deviceThe new Gdk::DeviceTool known to the seat.

◆ signal_tool_removed()

Glib::SignalProxy<void(const Glib::RefPtr<DeviceTool>&)> Gdk::Seat::signal_tool_removed ( )
Slot Prototype:
void on_my_tool_removed(const Glib::RefPtr<DeviceTool>& device)

Flags: Run Last

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

Since gtkmm 3.94:
Parameters
deviceThe just removed Gdk::DeviceTool.

◆ ungrab()

void Gdk::Seat::ungrab ( )

Releases a grab added through grab().

Friends And Related Function Documentation

◆ wrap()

Glib::RefPtr< Gdk::Seat > wrap ( GdkSeat *  object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.