brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
6cc58f7d7d
mutter/clutter/clutter-input-device.h

103 lines
5.7 KiB
C
Raw Normal View History

Add docs and licensing notices
2009-11-24 11:22:44 -05:00
/*
* Clutter.
*
* An OpenGL based 'interactive canvas' library.
*
input-device: Add documentation
2011-01-18 07:57:12 -05:00
* Copyright © 2009, 2010, 2011 Intel Corp.
Add docs and licensing notices
2009-11-24 11:22:44 -05:00
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*
* Author: Emmanuele Bassi <ebassi@linux.intel.com>
*/
device: Make InputDevice an object and subclass it for X11 ClutterInputDevice should be a type that we can subclass per-backend to add functionality.
2009-11-23 11:07:16 -05:00
#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
#error "Only <clutter/clutter.h> can be included directly."
#endif
#ifndef __CLUTTER_INPUT_DEVICE_H__
#define __CLUTTER_INPUT_DEVICE_H__
device: Add pointer actor getter ClutterInputDevice should have a getter method for retrieving the reactive actor underneath the pointer.
2010-01-12 06:53:12 -05:00
#include <clutter/clutter-types.h>
device: Make InputDevice an object and subclass it for X11 ClutterInputDevice should be a type that we can subclass per-backend to add functionality.
2009-11-23 11:07:16 -05:00
G_BEGIN_DECLS
#define CLUTTER_TYPE_INPUT_DEVICE (clutter_input_device_get_type ())
#define CLUTTER_INPUT_DEVICE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_INPUT_DEVICE, ClutterInputDevice))
#define CLUTTER_IS_INPUT_DEVICE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_INPUT_DEVICE))
#define CLUTTER_INPUT_DEVICE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), CLUTTER_TYPE_INPUT_DEVICE, ClutterInputDeviceClass))
#define CLUTTER_IS_INPUT_DEVICE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), CLUTTER_TYPE_INPUT_DEVICE))
#define CLUTTER_INPUT_DEVICE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_INPUT_DEVICE, ClutterInputDeviceClass))
/**
* ClutterInputDevice:
*
device: Add the :name property to InputDevice The InputDevice should have a name, possibly user readable, coming from the backend.
2010-01-15 06:37:43 -05:00
* Generic representation of an input device. The actual contents of this
* structure depend on the backend used.
device: Make InputDevice an object and subclass it for X11 ClutterInputDevice should be a type that we can subclass per-backend to add functionality.
2009-11-23 11:07:16 -05:00
*/
typedef struct _ClutterInputDevice ClutterInputDevice;
typedef struct _ClutterInputDeviceClass ClutterInputDeviceClass;
GType clutter_input_device_get_type (void) G_GNUC_CONST;
event/x11: Rework the way we translate X11 events This is a lump commit that is fairly difficult to break down without either breaking bisecting or breaking the test cases. The new design for handling X11 event translation works this way: - ClutterBackend::translate_event() has been added as the central point used by a ClutterBackend implementation to translate a native event into a ClutterEvent; - ClutterEventTranslator is a private interface that should be implemented by backend-specific objects, like stage implementations and ClutterDeviceManager sub-classes, and allows dealing with class-specific event translation; - ClutterStageX11 implements EventTranslator, and deals with the stage-relative X11 events coming from the X11 event source; - ClutterStageGLX overrides EventTranslator, in order to deal with the INTEL_GLX_swap_event extension, and it chains up to the X11 default implementation; - ClutterDeviceManagerX11 has been split into two separate classes, one that deals with core and (optionally) XI1 events, and the other that deals with XI2 events; the selection is done at run-time, since the core+XI1 and XI2 mechanisms are mutually exclusive. All the other backends we officially support still use their own custom event source and translation function, but the end goal is to migrate them to the translate_event() virtual function, and have the event source be a shared part of Clutter core.
2011-01-04 07:32:04 -05:00
ClutterInputDeviceType clutter_input_device_get_device_type (ClutterInputDevice *device);
gint clutter_input_device_get_device_id (ClutterInputDevice *device);
void clutter_input_device_get_device_coords (ClutterInputDevice *device,
gint *x,
gint *y);
ClutterActor * clutter_input_device_get_pointer_actor (ClutterInputDevice *device);
ClutterStage * clutter_input_device_get_pointer_stage (ClutterInputDevice *device);
Eliminate G_CONST_RETURN The G_CONST_RETURN define in GLib is, and has always been, a bit fuzzy. We always used it to conform to the platform, at least for public-facing API. At first I assumed it has something to do with brain-damaged compilers or with weird platforms where const was not really supported; sadly, it's something much, much worse: it's a define that can be toggled at compile-time to remove const from the signature of public API. This is a truly terrifying feature that I assume was added in the past century, and whose inception clearly had something to do with massive doses of absynthe and opium — because any other explanation would make the existence of such a feature even worse than assuming drugs had anything to do with it. Anyway, and pleasing the gods, this dubious feature is being removed/deprecated in GLib; see bug: https://bugzilla.gnome.org/show_bug.cgi?id=644611 Before deprecation, though, we should just remove its usage from the whole API. We should especially remove its usage from Cally's internals, since there it never made sense in the first place.
2011-06-07 10:49:20 -04:00
const gchar * clutter_input_device_get_device_name (ClutterInputDevice *device);
device: Add more accessors for properties Allow using real accessor methods for getting the ClutterInputDevice properties set on construction.
2011-01-18 12:33:22 -05:00
ClutterInputMode clutter_input_device_get_device_mode (ClutterInputDevice *device);
gboolean clutter_input_device_get_has_cursor (ClutterInputDevice *device);
device: Allow enabling/disabling non-master devices Slave and floating devices should always be disabled, and not deliver events to the scene. It is up to the user to enable non-master devices and handle events coming from them. ClutterInputDevice gets a new :enabled property, defaulting to FALSE; when a device manager creates a new device it has to set it to TRUE if the :device-mode property is set to CLUTTER_INPUT_MODE_MASTER. The main event queue entry point, _clutter_event_push(), will automatically discard events coming from disabled devices.
2011-01-19 11:23:45 -05:00
void clutter_input_device_set_enabled (ClutterInputDevice *device,
gboolean enabled);
gboolean clutter_input_device_get_enabled (ClutterInputDevice *device);
event/x11: Rework the way we translate X11 events This is a lump commit that is fairly difficult to break down without either breaking bisecting or breaking the test cases. The new design for handling X11 event translation works this way: - ClutterBackend::translate_event() has been added as the central point used by a ClutterBackend implementation to translate a native event into a ClutterEvent; - ClutterEventTranslator is a private interface that should be implemented by backend-specific objects, like stage implementations and ClutterDeviceManager sub-classes, and allows dealing with class-specific event translation; - ClutterStageX11 implements EventTranslator, and deals with the stage-relative X11 events coming from the X11 event source; - ClutterStageGLX overrides EventTranslator, in order to deal with the INTEL_GLX_swap_event extension, and it chains up to the X11 default implementation; - ClutterDeviceManagerX11 has been split into two separate classes, one that deals with core and (optionally) XI1 events, and the other that deals with XI2 events; the selection is done at run-time, since the core+XI1 and XI2 mechanisms are mutually exclusive. All the other backends we officially support still use their own custom event source and translation function, but the end goal is to migrate them to the translate_event() virtual function, and have the event source be a shared part of Clutter core.
2011-01-04 07:32:04 -05:00
guint clutter_input_device_get_n_axes (ClutterInputDevice *device);
device: Add keys and axes accessors Allow retrieving the number of keys and axes, since we provide the API to iterate over them both.
2011-01-18 11:13:26 -05:00
ClutterInputAxis clutter_input_device_get_axis (ClutterInputDevice *device,
guint index_);
device: Add get_axis_value() We need a convenience function for extracting the value of a specific axis type out of the array of axis values attached to events.
2011-01-18 11:55:14 -05:00
gboolean clutter_input_device_get_axis_value (ClutterInputDevice *device,
gdouble *axes,
ClutterInputAxis axis,
gdouble *value);
event/x11: Rework the way we translate X11 events This is a lump commit that is fairly difficult to break down without either breaking bisecting or breaking the test cases. The new design for handling X11 event translation works this way: - ClutterBackend::translate_event() has been added as the central point used by a ClutterBackend implementation to translate a native event into a ClutterEvent; - ClutterEventTranslator is a private interface that should be implemented by backend-specific objects, like stage implementations and ClutterDeviceManager sub-classes, and allows dealing with class-specific event translation; - ClutterStageX11 implements EventTranslator, and deals with the stage-relative X11 events coming from the X11 event source; - ClutterStageGLX overrides EventTranslator, in order to deal with the INTEL_GLX_swap_event extension, and it chains up to the X11 default implementation; - ClutterDeviceManagerX11 has been split into two separate classes, one that deals with core and (optionally) XI1 events, and the other that deals with XI2 events; the selection is done at run-time, since the core+XI1 and XI2 mechanisms are mutually exclusive. All the other backends we officially support still use their own custom event source and translation function, but the end goal is to migrate them to the translate_event() virtual function, and have the event source be a shared part of Clutter core.
2011-01-04 07:32:04 -05:00
device: Add keys and axes accessors Allow retrieving the number of keys and axes, since we provide the API to iterate over them both.
2011-01-18 11:13:26 -05:00
guint clutter_input_device_get_n_keys (ClutterInputDevice *device);
event/x11: Rework the way we translate X11 events This is a lump commit that is fairly difficult to break down without either breaking bisecting or breaking the test cases. The new design for handling X11 event translation works this way: - ClutterBackend::translate_event() has been added as the central point used by a ClutterBackend implementation to translate a native event into a ClutterEvent; - ClutterEventTranslator is a private interface that should be implemented by backend-specific objects, like stage implementations and ClutterDeviceManager sub-classes, and allows dealing with class-specific event translation; - ClutterStageX11 implements EventTranslator, and deals with the stage-relative X11 events coming from the X11 event source; - ClutterStageGLX overrides EventTranslator, in order to deal with the INTEL_GLX_swap_event extension, and it chains up to the X11 default implementation; - ClutterDeviceManagerX11 has been split into two separate classes, one that deals with core and (optionally) XI1 events, and the other that deals with XI2 events; the selection is done at run-time, since the core+XI1 and XI2 mechanisms are mutually exclusive. All the other backends we officially support still use their own custom event source and translation function, but the end goal is to migrate them to the translate_event() virtual function, and have the event source be a shared part of Clutter core.
2011-01-04 07:32:04 -05:00
void clutter_input_device_set_key (ClutterInputDevice *device,
guint index_,
guint keyval,
ClutterModifierType modifiers);
gboolean clutter_input_device_get_key (ClutterInputDevice *device,
guint index_,
guint *keyval,
ClutterModifierType *modifiers);
ClutterInputDevice * clutter_input_device_get_associated_device (ClutterInputDevice *device);
GList * clutter_input_device_get_slave_devices (ClutterInputDevice *device);
void clutter_input_device_update_from_event (ClutterInputDevice *device,
ClutterEvent *event,
gboolean update_stage);
device: Allow updating devices from embedding toolkits Embedding toolkits most likely will disable the event handling, so all the input device code will not be executed. Unfortunately, the newly added synthetic event generation of ENTER and LEAVE event pairs depends on having input devices. In order to unbreak things without reintroducing the madness of the previous code we should allow embedding toolkits to just update the state of an InputDevice by using the data contained inside the ClutterEvent. This strategy has two obvious reasons: • the embedding toolkit is creating a ClutterEvent by translating a toolkit-native event anyway • this is exactly what ClutterStage does when processing events We are, essentially, deferring input device handling to the embedding toolkits, just like we're deferring event handling to them.
2010-02-17 13:21:50 -05:00
Annotate all functions available since 1.10
2012-02-27 11:31:53 -05:00
CLUTTER_AVAILABLE_IN_1_10
Clean up grab implementation The grab API is a relic of Clutter 0.6, and hasn't been through proper vetting in a *long* time — mostly due to the fact that we don't really like grabs, and point to the ::captured-event as a way to implement "soft grabs" in toolkits and applications. The implementation of full and device grabs uses weak references on actors instead of using the ::destroy signal, which is meant exactly for the case of releasing pointers to actors when they are disposed. The API naming scheme is also fairly broken, especially for device-related grabs. Finally, keyboard device grabs are just not implemented. We can, in one go, clean up this mess and deprecate a bunch of badly named API by introducing generic device grab/ungrab methods on ClutterInputDevice, and re-implement the current API on top of them.
2011-10-10 11:45:20 -04:00
void clutter_input_device_grab (ClutterInputDevice *device,
ClutterActor *actor);
Annotate all functions available since 1.10
2012-02-27 11:31:53 -05:00
CLUTTER_AVAILABLE_IN_1_10
Clean up grab implementation The grab API is a relic of Clutter 0.6, and hasn't been through proper vetting in a *long* time — mostly due to the fact that we don't really like grabs, and point to the ::captured-event as a way to implement "soft grabs" in toolkits and applications. The implementation of full and device grabs uses weak references on actors instead of using the ::destroy signal, which is meant exactly for the case of releasing pointers to actors when they are disposed. The API naming scheme is also fairly broken, especially for device-related grabs. Finally, keyboard device grabs are just not implemented. We can, in one go, clean up this mess and deprecate a bunch of badly named API by introducing generic device grab/ungrab methods on ClutterInputDevice, and re-implement the current API on top of them.
2011-10-10 11:45:20 -04:00
void clutter_input_device_ungrab (ClutterInputDevice *device);
Annotate all functions available since 1.10
2012-02-27 11:31:53 -05:00
CLUTTER_AVAILABLE_IN_1_10
Clean up grab implementation The grab API is a relic of Clutter 0.6, and hasn't been through proper vetting in a *long* time — mostly due to the fact that we don't really like grabs, and point to the ::captured-event as a way to implement "soft grabs" in toolkits and applications. The implementation of full and device grabs uses weak references on actors instead of using the ::destroy signal, which is meant exactly for the case of releasing pointers to actors when they are disposed. The API naming scheme is also fairly broken, especially for device-related grabs. Finally, keyboard device grabs are just not implemented. We can, in one go, clean up this mess and deprecate a bunch of badly named API by introducing generic device grab/ungrab methods on ClutterInputDevice, and re-implement the current API on top of them.
2011-10-10 11:45:20 -04:00
ClutterActor * clutter_input_device_get_grabbed_actor (ClutterInputDevice *device);
device: Make InputDevice an object and subclass it for X11 ClutterInputDevice should be a type that we can subclass per-backend to add functionality.
2009-11-23 11:07:16 -05:00
G_END_DECLS
#endif /* __CLUTTER_INPUT_DEVICE_H__ */
Reference in New Issue Copy Permalink