Release Clutter 1.11.4 (snapshot)
[profile/ivi/clutter.git] / clutter / clutter-event.h
1 /*
2  * Clutter.
3  *
4  * An OpenGL based 'interactive canvas' library.
5  *
6  * Authored By Matthew Allum  <mallum@openedhand.com>
7  *
8  * Copyright (C) 2006 OpenedHand
9  *
10  * This library is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU Lesser General Public
12  * License as published by the Free Software Foundation; either
13  * version 2 of the License, or (at your option) any later version.
14  *
15  * This library is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18  * Lesser General Public License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public
21  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
22  */
23
24 #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
25 #error "Only <clutter/clutter.h> can be included directly."
26 #endif
27
28 #ifndef __CLUTTER_EVENT_H__
29 #define __CLUTTER_EVENT_H__
30
31 #include <clutter/clutter-types.h>
32 #include <clutter/clutter-input-device.h>
33
34 G_BEGIN_DECLS
35
36 #define CLUTTER_TYPE_EVENT              (clutter_event_get_type ())
37
38 /**
39  * CLUTTER_PRIORITY_EVENTS:
40  *
41  * Priority for event handling.
42  *
43  * Since: 0.4
44  */
45 #define CLUTTER_PRIORITY_EVENTS         (G_PRIORITY_DEFAULT)
46
47 /**
48  * CLUTTER_CURRENT_TIME:
49  *
50  * Default value for "now".
51  *
52  * Since: 0.4
53  */
54 #define CLUTTER_CURRENT_TIME            (0L)
55
56 /**
57  * CLUTTER_EVENT_PROPAGATE:
58  *
59  * Continues the propagation of an event; this macro should be
60  * used in event-related signals.
61  *
62  * Since: 1.10
63  */
64 #define CLUTTER_EVENT_PROPAGATE         (FALSE)
65
66 /**
67  * CLUTTER_EVENT_STOP:
68  *
69  * Stops the propagation of an event; this macro should be used
70  * in event-related signals.
71  *
72  * Since: 1.10
73  */
74 #define CLUTTER_EVENT_STOP              (TRUE)
75
76 /**
77  * CLUTTER_BUTTON_PRIMARY:
78  *
79  * The primary button of a pointer device.
80  *
81  * This is typically the left mouse button in a right-handed
82  * mouse configuration.
83  *
84  * Since: 1.10
85  */
86 #define CLUTTER_BUTTON_PRIMARY          (1)
87
88 /**
89  * CLUTTER_BUTTON_MIDDLE:
90  *
91  * The middle button of a pointer device.
92  *
93  * Since: 1.10
94  */
95 #define CLUTTER_BUTTON_MIDDLE           (2)
96
97 /**
98  * CLUTTER_BUTTON_SECONDARY:
99  *
100  * The secondary button of a pointer device.
101  *
102  * This is typically the right mouse button in a right-handed
103  * mouse configuration.
104  *
105  * Since: 1.10
106  */
107 #define CLUTTER_BUTTON_SECONDARY        (3)
108
109 typedef struct _ClutterAnyEvent         ClutterAnyEvent;
110 typedef struct _ClutterButtonEvent      ClutterButtonEvent;
111 typedef struct _ClutterKeyEvent         ClutterKeyEvent;
112 typedef struct _ClutterMotionEvent      ClutterMotionEvent;
113 typedef struct _ClutterScrollEvent      ClutterScrollEvent;
114 typedef struct _ClutterStageStateEvent  ClutterStageStateEvent;
115 typedef struct _ClutterCrossingEvent    ClutterCrossingEvent;
116 typedef struct _ClutterTouchEvent       ClutterTouchEvent;
117
118 /**
119  * ClutterEventSequence:
120  *
121  * The <structname>ClutterEventSequence</structname> structure is an opaque
122  * type used to denote the event sequence of a touch event.
123  *
124  * Since: 1.12
125  */
126 typedef struct _ClutterEventSequence    ClutterEventSequence;
127
128 /**
129  * ClutterAnyEvent:
130  * @type: event type
131  * @time: event time
132  * @flags: event flags
133  * @source: event source actor
134  *
135  * Common members for a #ClutterEvent
136  *
137  * Since: 0.2
138  */
139 struct _ClutterAnyEvent
140 {
141   ClutterEventType type;
142   guint32 time;
143   ClutterEventFlags flags;
144   ClutterStage *stage;
145   ClutterActor *source;
146 };
147
148 /**
149  * ClutterKeyEvent:
150  * @type: event type
151  * @time: event time
152  * @flags: event flags
153  * @stage: event source stage
154  * @source: event source actor
155  * @modifier_state: key modifiers
156  * @keyval: raw key value
157  * @hardware_keycode: raw hardware key value
158  * @unicode_value: Unicode representation
159  * @device: reserved for future use
160  *
161  * Key event
162  *
163  * Since: 0.2
164  */
165 struct _ClutterKeyEvent
166 {
167   ClutterEventType type;
168   guint32 time;
169   ClutterEventFlags flags;
170   ClutterStage *stage;
171   ClutterActor *source;
172
173   ClutterModifierType modifier_state;
174   guint keyval;
175   guint16 hardware_keycode;
176   gunichar unicode_value;
177   ClutterInputDevice *device;
178 };
179
180 /**
181  * ClutterButtonEvent:
182  * @type: event type
183  * @time: event time
184  * @flags: event flags
185  * @stage: event source stage
186  * @source: event source actor
187  * @x: event X coordinate, relative to the stage
188  * @y: event Y coordinate, relative to the stage
189  * @modifier_state: button modifiers
190  * @button: event button
191  * @click_count: number of button presses within the default time
192  *   and radius
193  * @axes: reserved for future use
194  * @device: reserved for future use
195  *
196  * Button event.
197  *
198  * The event coordinates are relative to the stage that received the
199  * event, and can be transformed into actor-relative coordinates by
200  * using clutter_actor_transform_stage_point().
201  *
202  * Since: 0.2
203  */
204 struct _ClutterButtonEvent
205 {
206   ClutterEventType type;
207   guint32 time;
208   ClutterEventFlags flags;
209   ClutterStage *stage;
210   ClutterActor *source;
211
212   gfloat x;
213   gfloat y;
214   ClutterModifierType modifier_state;
215   guint32 button;
216   guint click_count;
217   gdouble *axes; /* Future use */
218   ClutterInputDevice *device;
219 };
220
221 /**
222  * ClutterCrossingEvent:
223  * @type: event type
224  * @time: event time
225  * @flags: event flags
226  * @stage: event source stage
227  * @source: event source actor
228  * @x: event X coordinate
229  * @y: event Y coordinate
230  * @related: actor related to the crossing
231  * @device: reserved for future use
232  *
233  * Event for the movement of the pointer across different actors
234  *
235  * Since: 0.2
236  */
237 struct _ClutterCrossingEvent
238 {
239   ClutterEventType type;
240   guint32 time;
241   ClutterEventFlags flags;
242   ClutterStage *stage;
243   ClutterActor *source;
244
245   gfloat x;
246   gfloat y;
247   ClutterInputDevice *device;
248   ClutterActor *related;
249 };
250
251 /**
252  * ClutterMotionEvent:
253  * @type: event type
254  * @time: event time
255  * @flags: event flags
256  * @stage: event source stage
257  * @source: event source actor
258  * @x: event X coordinate
259  * @y: event Y coordinate
260  * @modifier_state: button modifiers
261  * @axes: reserved for future use
262  * @device: reserved for future use
263  *
264  * Event for the pointer motion
265  *
266  * Since: 0.2
267  */
268 struct _ClutterMotionEvent
269 {
270   ClutterEventType type;
271   guint32 time;
272   ClutterEventFlags flags;
273   ClutterStage *stage;
274   ClutterActor *source;
275
276   gfloat x;
277   gfloat y;
278   ClutterModifierType modifier_state;
279   gdouble *axes; /* Future use */
280   ClutterInputDevice *device;
281 };
282
283 /**
284  * ClutterScrollEvent:
285  * @type: event type
286  * @time: event time
287  * @flags: event flags
288  * @stage: event source stage
289  * @source: event source actor
290  * @x: event X coordinate
291  * @y: event Y coordinate
292  * @direction: direction of the scrolling
293  * @modifier_state: button modifiers
294  * @axes: reserved for future use
295  * @device: reserved for future use
296  *
297  * Scroll wheel (or similar device) event
298  *
299  * Since: 0.2
300  */
301 struct _ClutterScrollEvent
302 {
303   ClutterEventType type;
304   guint32 time;
305   ClutterEventFlags flags;
306   ClutterStage *stage;
307   ClutterActor *source;
308
309   gfloat x;
310   gfloat y;
311   ClutterScrollDirection direction;
312   ClutterModifierType modifier_state;
313   gdouble *axes; /* future use */
314   ClutterInputDevice *device;
315 };
316
317 /**
318  * ClutterStageStateEvent:
319  * @type: event type
320  * @time: event time
321  * @flags: event flags
322  * @stage: event source stage
323  * @source: event source actor (unused)
324  * @changed_mask: bitwise OR of the changed flags
325  * @new_state: bitwise OR of the current state flags
326  *
327  * Event signalling a change in the #ClutterStage state.
328  *
329  * Since: 0.2
330  */
331 struct _ClutterStageStateEvent
332 {
333   ClutterEventType type;
334   guint32 time;
335   ClutterEventFlags flags;
336   ClutterStage *stage;
337   ClutterActor *source; /* XXX: should probably be the stage itself */
338
339   ClutterStageState changed_mask;
340   ClutterStageState new_state;
341 };
342
343 /**
344  * ClutterTouchEvent:
345  * @type: event type
346  * @time: event time
347  * @flags: event flags
348  * @stage: event source stage
349  * @source: event source actor (unused)
350  * @x: the X coordinate of the pointer, relative to the stage
351  * @y: the Y coordinate of the pointer, relative to the stage
352  * @sequence: the event sequence that this event belongs to
353  * @modifier_state: (type ClutterModifierType): a bit-mask representing the state
354  *   of modifier keys (e.g. Control, Shift, and Alt) and the pointer
355  *   buttons. See #ClutterModifierType
356  * @axes: reserved 
357  * @device: the device that originated the event
358  *
359  * Used for touch events.
360  *
361  * The @type field will be one of %CLUTTER_TOUCH_BEGIN, %CLUTTER_TOUCH_END,
362  * %CLUTTER_TOUCH_UPDATE, or %CLUTTER_TOUCH_CANCEL.
363  *
364  * Touch events are grouped into sequences; each touch sequence will begin
365  * with a %CLUTTER_TOUCH_BEGIN event, progress with %CLUTTER_TOUCH_UPDATE
366  * events, and end either with a %CLUTTER_TOUCH_END event or with a
367  * %CLUTTER_TOUCH_CANCEL event.
368  *
369  * With multi-touch capable devices there can be multiple event sequence
370  * running at the same time.
371  *
372  * Since: 1.10
373  */
374 struct _ClutterTouchEvent
375 {
376   ClutterEventType type;
377   guint32 time;
378   ClutterEventFlags flags;
379   ClutterStage *stage;
380   ClutterActor *source;
381
382   gfloat x;
383   gfloat y;
384   ClutterEventSequence *sequence;
385   ClutterModifierType modifier_state;
386   gdouble *axes; /* reserved */
387   ClutterInputDevice *device;
388 };
389
390 /**
391  * ClutterEvent:
392  *
393  * Generic event wrapper.
394  *
395  * Since: 0.2
396  */
397 union _ClutterEvent
398 {
399   /*< private >*/
400   ClutterEventType type;
401
402   ClutterAnyEvent any;
403   ClutterButtonEvent button;
404   ClutterKeyEvent key;
405   ClutterMotionEvent motion;
406   ClutterScrollEvent scroll;
407   ClutterStageStateEvent stage_state;
408   ClutterCrossingEvent crossing;
409   ClutterTouchEvent touch;
410 };
411
412 GType clutter_event_get_type (void) G_GNUC_CONST;
413
414 gboolean                clutter_events_pending                  (void);
415 ClutterEvent *          clutter_event_get                       (void);
416 ClutterEvent *          clutter_event_peek                      (void);
417 void                    clutter_event_put                       (const ClutterEvent     *event);
418
419 ClutterEvent *          clutter_event_new                       (ClutterEventType        type);
420 ClutterEvent *          clutter_event_copy                      (const ClutterEvent     *event);
421 void                    clutter_event_free                      (ClutterEvent           *event);
422
423 ClutterEventType        clutter_event_type                      (const ClutterEvent     *event);
424 void                    clutter_event_set_flags                 (ClutterEvent           *event,
425                                                                  ClutterEventFlags       flags);
426 ClutterEventFlags       clutter_event_get_flags                 (const ClutterEvent     *event);
427 void                    clutter_event_set_time                  (ClutterEvent           *event,
428                                                                  guint32                 time_);
429 guint32                 clutter_event_get_time                  (const ClutterEvent     *event);
430 void                    clutter_event_set_state                 (ClutterEvent           *event,
431                                                                  ClutterModifierType     state);
432 ClutterModifierType     clutter_event_get_state                 (const ClutterEvent     *event);
433 void                    clutter_event_set_device                (ClutterEvent           *event,
434                                                                  ClutterInputDevice     *device);
435 ClutterInputDevice *    clutter_event_get_device                (const ClutterEvent     *event);
436 void                    clutter_event_set_source_device         (ClutterEvent           *event,
437                                                                  ClutterInputDevice     *device);
438
439 ClutterInputDevice *    clutter_event_get_source_device         (const ClutterEvent     *event);
440 void                    clutter_event_set_source                (ClutterEvent           *event,
441                                                                  ClutterActor           *actor);
442 ClutterActor *          clutter_event_get_source                (const ClutterEvent     *event);
443 void                    clutter_event_set_stage                 (ClutterEvent           *event,
444                                                                  ClutterStage           *stage);
445 ClutterStage *          clutter_event_get_stage                 (const ClutterEvent     *event);
446
447 gint                    clutter_event_get_device_id             (const ClutterEvent     *event);
448 ClutterInputDeviceType  clutter_event_get_device_type           (const ClutterEvent     *event);
449
450 void                    clutter_event_set_coords                (ClutterEvent           *event,
451                                                                  gfloat                  x,
452                                                                  gfloat                  y);
453 void                    clutter_event_get_coords                (const ClutterEvent     *event,
454                                                                  gfloat                 *x,
455                                                                  gfloat                 *y);
456 CLUTTER_AVAILABLE_IN_1_12
457 void                    clutter_event_get_position              (const ClutterEvent     *event,
458                                                                  ClutterPoint           *position);
459 CLUTTER_AVAILABLE_IN_1_12
460 float                   clutter_event_get_distance              (const ClutterEvent     *source,
461                                                                  const ClutterEvent     *target);
462 CLUTTER_AVAILABLE_IN_1_12
463 double                  clutter_event_get_angle                 (const ClutterEvent     *source,
464                                                                  const ClutterEvent     *target);
465
466 gdouble *               clutter_event_get_axes                  (const ClutterEvent     *event,
467                                                                  guint                  *n_axes);
468
469 CLUTTER_AVAILABLE_IN_1_12
470 gboolean                clutter_event_has_shift_modifier        (const ClutterEvent     *event);
471 CLUTTER_AVAILABLE_IN_1_12
472 gboolean                clutter_event_has_control_modifier      (const ClutterEvent     *event);
473
474 void                    clutter_event_set_key_symbol            (ClutterEvent           *event,
475                                                                  guint                   key_sym);
476 guint                   clutter_event_get_key_symbol            (const ClutterEvent     *event);
477 void                    clutter_event_set_key_code              (ClutterEvent           *event,
478                                                                  guint16                 key_code);
479 guint16                 clutter_event_get_key_code              (const ClutterEvent     *event);
480 void                    clutter_event_set_key_unicode           (ClutterEvent           *event,
481                                                                  guint32                 key_unicode);
482 guint32                 clutter_event_get_key_unicode           (const ClutterEvent     *event);
483
484 void                    clutter_event_set_button                (ClutterEvent           *event,
485                                                                  guint32                 button);
486 guint32                 clutter_event_get_button                (const ClutterEvent     *event);
487 guint                   clutter_event_get_click_count           (const ClutterEvent     *event);
488
489 void                    clutter_event_set_related               (ClutterEvent           *event,
490                                                                  ClutterActor           *actor);
491 ClutterActor *          clutter_event_get_related               (const ClutterEvent     *event);
492
493 void                    clutter_event_set_scroll_direction      (ClutterEvent           *event,
494                                                                  ClutterScrollDirection  direction);
495 ClutterScrollDirection  clutter_event_get_scroll_direction      (const ClutterEvent     *event);
496 CLUTTER_AVAILABLE_IN_1_10
497 void                    clutter_event_set_scroll_delta          (ClutterEvent           *event,
498                                                                  gdouble                 dx,
499                                                                  gdouble                 dy);
500 CLUTTER_AVAILABLE_IN_1_10
501 void                    clutter_event_get_scroll_delta          (const ClutterEvent     *event,
502                                                                  gdouble                *dx,
503                                                                  gdouble                *dy);
504
505 CLUTTER_AVAILABLE_IN_1_10
506 ClutterEventSequence *  clutter_event_get_event_sequence        (const ClutterEvent     *event);
507
508 guint32                 clutter_keysym_to_unicode               (guint                   keyval);
509 CLUTTER_AVAILABLE_IN_1_10
510 guint                   clutter_unicode_to_keysym               (guint32                 wc);
511
512 guint32                 clutter_get_current_event_time          (void);
513 const ClutterEvent *    clutter_get_current_event               (void);
514
515 G_END_DECLS
516
517 #endif /* __CLUTTER_EVENT_H__ */