From 9a6de8757f27ff8a8cf9f89209f9366e03b7aadf Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 18 Feb 2010 11:34:06 +0000 Subject: [PATCH] docs: Document the InputDevice update method Embedding toolkits should benefit from a proper documentation of clutter_input_device_update_from_event(): its meaning, its use and the caveats for the "update_stage" argument. --- clutter/clutter-input-device.c | 49 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/clutter/clutter-input-device.c b/clutter/clutter-input-device.c index 0f93e93..833367d 100644 --- a/clutter/clutter-input-device.c +++ b/clutter/clutter-input-device.c @@ -577,6 +577,55 @@ clutter_input_device_get_device_name (ClutterInputDevice *device) * This function should never be used by applications: it is meant * for integration with embedding toolkits, like clutter-gtk * + * Embedding toolkits that disable the event collection inside Clutter + * need to use this function to update the state of input devices depending + * on a #ClutterEvent that they are going to submit to the event handling code + * in Clutter though clutter_do_event(). Since the input devices hold the state + * that is going to be used to fill in fields like the #ClutterButtonEvent + * click count, or to emit synthesized events like %CLUTTER_ENTER and + * %CLUTTER_LEAVE, it is necessary for embedding toolkits to also be + * responsible of updating the input device state. + * + * For instance, this might be the code to translate an embedding toolkit + * native motion notification into a Clutter #ClutterMotionEvent and ask + * Clutter to process it: + * + * |[ + * ClutterEvent c_event; + * + * translate_native_event_to_clutter (native_event, &c_event); + * + * clutter_do_event (&c_event); + * ]| + * + * Before letting clutter_do_event() process the event, it is necessary to call + * clutter_input_device_update_from_event(): + * + * |[ + * ClutterEvent c_event; + * ClutterDeviceManager *manager; + * ClutterInputDevice *device; + * + * translate_native_event_to_clutter (native_event, &c_event); + * + * /* get the device manager */ + * manager = clutter_device_manager_get_default (); + * + * /* use the default Core Pointer that Clutter + * * backends register by default + * */ + * device = clutter_device_manager_get_core_device (manager, %CLUTTER_POINTER_DEVICE); + * + * /* update the state of the input device */ + * clutter_input_device_update_from_event (device, &c_event, FALSE); + * + * clutter_do_event (&c_event); + * ]| + * + * The @update_stage boolean argument should be used when the input device + * enters and leaves a #ClutterStage; it will use the #ClutterStage field + * of the passed @event to update the stage associated to the input device. + * * Since: 1.2 */ void -- 2.7.4