1 // Copyright (C) 2002-2012 Nikolaus Gebhardt
\r
2 // This file is part of the "Irrlicht Engine".
\r
3 // For conditions of distribution and use, see copyright notice in irrlicht.h
\r
5 #ifndef __I_EVENT_RECEIVER_H_INCLUDED__
\r
6 #define __I_EVENT_RECEIVER_H_INCLUDED__
\r
9 #include "Keycodes.h"
\r
10 #include "irrString.h"
\r
14 //! Enumeration for all event types there are.
\r
17 //! An event of the graphical user interface.
\r
18 /** GUI events are created by the GUI environment or the GUI elements in response
\r
19 to mouse or keyboard events. When a GUI element receives an event it will either
\r
20 process it and return true, or pass the event to its parent. If an event is not absorbed
\r
21 before it reaches the root element then it will then be passed to the user receiver. */
\r
24 //! A mouse input event.
\r
25 /** Mouse events are created by the device and passed to IrrlichtDevice::postEventFromUser
\r
26 in response to mouse input received from the operating system.
\r
27 Mouse events are first passed to the user receiver, then to the GUI environment and its elements,
\r
28 then finally the input receiving scene manager where it is passed to the active camera.
\r
30 EET_MOUSE_INPUT_EVENT,
\r
32 //! A key input event.
\r
33 /** Like mouse events, keyboard events are created by the device and passed to
\r
34 IrrlichtDevice::postEventFromUser. They take the same path as mouse events. */
\r
35 EET_KEY_INPUT_EVENT,
\r
37 //! A string input event.
\r
38 /** This event is created when multiple characters are sent at a time (e.g. using an IME). */
\r
39 EET_STRING_INPUT_EVENT,
\r
41 //! A touch input event.
\r
42 EET_TOUCH_INPUT_EVENT,
\r
44 //! A accelerometer event.
\r
45 EET_ACCELEROMETER_EVENT,
\r
47 //! A gyroscope event.
\r
48 EET_GYROSCOPE_EVENT,
\r
50 //! A device motion event.
\r
51 EET_DEVICE_MOTION_EVENT,
\r
53 //! A joystick (joypad, gamepad) input event.
\r
54 /** Joystick events are created by polling all connected joysticks once per
\r
55 device run() and then passing the events to IrrlichtDevice::postEventFromUser.
\r
56 They take the same path as mouse events.
\r
57 Windows, SDL: Implemented.
\r
58 Linux: Implemented, with POV hat issues.
\r
59 MacOS / Other: Not yet implemented.
\r
61 EET_JOYSTICK_INPUT_EVENT,
\r
64 /** Log events are only passed to the user receiver if there is one. If they are absorbed by the
\r
65 user receiver then no text will be sent to the console. */
\r
68 //! A user event with user data.
\r
69 /** This is not used by Irrlicht and can be used to send user
\r
70 specific data though the system. The Irrlicht 'window handle'
\r
71 can be obtained from IrrlichtDevice::getExposedVideoData()
\r
72 The usage and behavior depends on the operating system:
\r
73 Windows: send a WM_USER message to the Irrlicht Window; the
\r
74 wParam and lParam will be used to populate the
\r
75 UserData1 and UserData2 members of the SUserEvent.
\r
76 Linux: send a ClientMessage via XSendEvent to the Irrlicht
\r
77 Window; the data.l[0] and data.l[1] members will be
\r
78 cast to s32 and used as UserData1 and UserData2.
\r
79 MacOS: Not yet implemented
\r
83 //! Pass on raw events from the OS
\r
86 //! Application state events like a resume, pause etc.
\r
87 EET_APPLICATION_EVENT,
\r
89 //! This enum is never used, it only forces the compiler to
\r
90 //! compile these enumeration values to 32 bit.
\r
91 EGUIET_FORCE_32_BIT = 0x7fffffff
\r
95 //! Enumeration for all mouse input events
\r
96 enum EMOUSE_INPUT_EVENT
\r
98 //! Left mouse button was pressed down.
\r
99 EMIE_LMOUSE_PRESSED_DOWN = 0,
\r
101 //! Right mouse button was pressed down.
\r
102 EMIE_RMOUSE_PRESSED_DOWN,
\r
104 //! Middle mouse button was pressed down.
\r
105 EMIE_MMOUSE_PRESSED_DOWN,
\r
107 //! Left mouse button was left up.
\r
108 EMIE_LMOUSE_LEFT_UP,
\r
110 //! Right mouse button was left up.
\r
111 EMIE_RMOUSE_LEFT_UP,
\r
113 //! Middle mouse button was left up.
\r
114 EMIE_MMOUSE_LEFT_UP,
\r
116 //! The mouse cursor changed its position.
\r
119 //! The mouse wheel was moved. Use Wheel value in event data to find out
\r
120 //! in what direction and how fast.
\r
123 //! Left mouse button double click.
\r
124 //! This event is generated after the second EMIE_LMOUSE_PRESSED_DOWN event.
\r
125 EMIE_LMOUSE_DOUBLE_CLICK,
\r
127 //! Right mouse button double click.
\r
128 //! This event is generated after the second EMIE_RMOUSE_PRESSED_DOWN event.
\r
129 EMIE_RMOUSE_DOUBLE_CLICK,
\r
131 //! Middle mouse button double click.
\r
132 //! This event is generated after the second EMIE_MMOUSE_PRESSED_DOWN event.
\r
133 EMIE_MMOUSE_DOUBLE_CLICK,
\r
135 //! Left mouse button triple click.
\r
136 //! This event is generated after the third EMIE_LMOUSE_PRESSED_DOWN event.
\r
137 EMIE_LMOUSE_TRIPLE_CLICK,
\r
139 //! Right mouse button triple click.
\r
140 //! This event is generated after the third EMIE_RMOUSE_PRESSED_DOWN event.
\r
141 EMIE_RMOUSE_TRIPLE_CLICK,
\r
143 //! Middle mouse button triple click.
\r
144 //! This event is generated after the third EMIE_MMOUSE_PRESSED_DOWN event.
\r
145 EMIE_MMOUSE_TRIPLE_CLICK,
\r
147 //! Mouse enters canvas used for rendering.
\r
148 //! Only generated on emscripten
\r
149 EMIE_MOUSE_ENTER_CANVAS,
\r
151 //! Mouse leaves canvas used for rendering.
\r
152 //! Only generated on emscripten
\r
153 EMIE_MOUSE_LEAVE_CANVAS,
\r
155 //! No real event. Just for convenience to get number of events
\r
159 //! Masks for mouse button states
\r
160 enum E_MOUSE_BUTTON_STATE_MASK
\r
163 EMBSM_RIGHT = 0x02,
\r
164 EMBSM_MIDDLE = 0x04,
\r
166 //! currently only on windows
\r
167 EMBSM_EXTRA1 = 0x08,
\r
169 //! currently only on windows
\r
170 EMBSM_EXTRA2 = 0x10,
\r
172 EMBSM_FORCE_32_BIT = 0x7fffffff
\r
175 //! Enumeration for all touch input events
\r
176 enum ETOUCH_INPUT_EVENT
\r
178 //! Touch was pressed down.
\r
179 ETIE_PRESSED_DOWN = 0,
\r
181 //! Touch was left up.
\r
184 //! The touch changed its position.
\r
187 //! No real event. Just for convenience to get number of events
\r
191 enum ESYSTEM_EVENT_TYPE
\r
193 //! From Android command handler for native activity messages
\r
194 ESET_ANDROID_CMD = 0,
\r
196 // TODO: for example ESET_WINDOWS_MESSAGE for win32 message loop events
\r
198 //! No real event, but to get number of event types
\r
202 //! Enumeration for a commonly used application state events (it's useful mainly for mobile devices)
\r
203 enum EAPPLICATION_EVENT_TYPE
\r
205 //! The application will be resumed.
\r
206 EAET_WILL_RESUME = 0,
\r
208 //! The application has been resumed.
\r
211 //! The application will be paused.
\r
214 //! The application has been paused.
\r
217 //! The application will be terminated.
\r
218 EAET_WILL_TERMINATE,
\r
220 //! The application received a memory warning.
\r
221 EAET_MEMORY_WARNING,
\r
223 //! No real event, but to get number of event types.
\r
232 //! Enumeration for all events which are sendable by the gui system
\r
233 enum EGUI_EVENT_TYPE
\r
235 //! A gui element has lost its focus.
\r
236 /** GUIEvent.Caller is losing the focus to GUIEvent.Element.
\r
237 If the event is absorbed then the focus will not be changed. */
\r
238 EGET_ELEMENT_FOCUS_LOST = 0,
\r
240 //! A gui element has got the focus.
\r
241 /** If the event is absorbed then the focus will not be changed. */
\r
242 EGET_ELEMENT_FOCUSED,
\r
244 //! The mouse cursor hovered over a gui element.
\r
245 /** If an element has sub-elements you also get this message for the subelements */
\r
246 EGET_ELEMENT_HOVERED,
\r
248 //! The mouse cursor left the hovered element.
\r
249 /** If an element has sub-elements you also get this message for the subelements */
\r
252 //! An element would like to close.
\r
253 /** Windows and context menus use this event when they would like to close,
\r
254 this can be canceled by absorbing the event. */
\r
255 EGET_ELEMENT_CLOSED,
\r
257 //! A button was clicked.
\r
258 EGET_BUTTON_CLICKED,
\r
260 //! A scrollbar has changed its position.
\r
261 EGET_SCROLL_BAR_CHANGED,
\r
263 //! A checkbox has changed its check state.
\r
264 EGET_CHECKBOX_CHANGED,
\r
266 //! A new item in a listbox was selected.
\r
267 /** NOTE: You also get this event currently when the same item was clicked again after more than 500 ms. */
\r
268 EGET_LISTBOX_CHANGED,
\r
270 //! An item in the listbox was selected, which was already selected.
\r
271 /** NOTE: You get the event currently only if the item was clicked again within 500 ms or selected by "enter" or "space". */
\r
272 EGET_LISTBOX_SELECTED_AGAIN,
\r
274 //! A file has been selected in the file dialog
\r
275 EGET_FILE_SELECTED,
\r
277 //! A directory has been selected in the file dialog
\r
278 EGET_DIRECTORY_SELECTED,
\r
280 //! A file open dialog has been closed without choosing a file
\r
281 EGET_FILE_CHOOSE_DIALOG_CANCELLED,
\r
283 //! 'Yes' was clicked on a messagebox
\r
284 EGET_MESSAGEBOX_YES,
\r
286 //! 'No' was clicked on a messagebox
\r
287 EGET_MESSAGEBOX_NO,
\r
289 //! 'OK' was clicked on a messagebox
\r
290 EGET_MESSAGEBOX_OK,
\r
292 //! 'Cancel' was clicked on a messagebox
\r
293 EGET_MESSAGEBOX_CANCEL,
\r
295 //! In an editbox 'ENTER' was pressed
\r
296 EGET_EDITBOX_ENTER,
\r
298 //! The text in an editbox was changed. This does not include automatic changes in text-breaking.
\r
299 EGET_EDITBOX_CHANGED,
\r
301 //! The marked area in an editbox was changed.
\r
302 EGET_EDITBOX_MARKING_CHANGED,
\r
304 //! The tab was changed in an tab control
\r
307 //! A menu item was selected in a (context) menu
\r
308 EGET_MENU_ITEM_SELECTED,
\r
310 //! The selection in a combo box has been changed
\r
311 EGET_COMBO_BOX_CHANGED,
\r
313 //! The value of a spin box has changed
\r
314 EGET_SPINBOX_CHANGED,
\r
316 //! A table has changed
\r
317 EGET_TABLE_CHANGED,
\r
318 EGET_TABLE_HEADER_CHANGED,
\r
319 EGET_TABLE_SELECTED_AGAIN,
\r
321 //! A tree view node lost selection. See IGUITreeView::getLastEventNode().
\r
322 EGET_TREEVIEW_NODE_DESELECT,
\r
324 //! A tree view node was selected. See IGUITreeView::getLastEventNode().
\r
325 EGET_TREEVIEW_NODE_SELECT,
\r
327 //! A tree view node was expanded. See IGUITreeView::getLastEventNode().
\r
328 EGET_TREEVIEW_NODE_EXPAND,
\r
330 //! A tree view node was collapsed. See IGUITreeView::getLastEventNode().
\r
331 EGET_TREEVIEW_NODE_COLLAPSE,
\r
333 //! deprecated - use EGET_TREEVIEW_NODE_COLLAPSE instead. This
\r
334 //! may be removed by Irrlicht 1.9
\r
335 EGET_TREEVIEW_NODE_COLLAPS = EGET_TREEVIEW_NODE_COLLAPSE,
\r
337 //! No real event. Just for convenience to get number of events
\r
340 } // end namespace gui
\r
343 //! SEvents hold information about an event. See irr::IEventReceiver for details on event handling.
\r
346 //! Any kind of GUI event.
\r
349 //! IGUIElement who called the event
\r
350 gui::IGUIElement* Caller;
\r
352 //! If the event has something to do with another element, it will be held here.
\r
353 gui::IGUIElement* Element;
\r
355 //! Type of GUI Event
\r
356 gui::EGUI_EVENT_TYPE EventType;
\r
360 //! Any kind of mouse event.
\r
363 //! X position of mouse cursor
\r
366 //! Y position of mouse cursor
\r
369 //! mouse wheel delta, often 1.0 or -1.0, but can have other values < 0.f or > 0.f;
\r
370 /** Only valid if event was EMIE_MOUSE_WHEEL */
\r
373 //! True if shift was also pressed
\r
376 //! True if ctrl was also pressed
\r
379 //! A bitmap of button states. You can use isButtonPressed() to determine
\r
380 //! if a button is pressed or not.
\r
381 //! Currently only valid if the event was EMIE_MOUSE_MOVED
\r
384 //! Is the left button pressed down?
\r
385 bool isLeftPressed() const { return 0 != ( ButtonStates & EMBSM_LEFT ); }
\r
387 //! Is the right button pressed down?
\r
388 bool isRightPressed() const { return 0 != ( ButtonStates & EMBSM_RIGHT ); }
\r
390 //! Is the middle button pressed down?
\r
391 bool isMiddlePressed() const { return 0 != ( ButtonStates & EMBSM_MIDDLE ); }
\r
393 //! Type of mouse event
\r
394 EMOUSE_INPUT_EVENT Event;
\r
397 //! Any kind of keyboard event.
\r
400 //! Character corresponding to the key (0, if not a character, value undefined in key releases)
\r
403 //! Key which has been pressed or released
\r
406 //! System dependent code. Only set for systems which are described below, otherwise undefined.
\r
407 //! Android: int32_t with physical key as returned by AKeyEvent_getKeyCode
\r
410 //! If not true, then the key was left up
\r
411 bool PressedDown:1;
\r
413 //! True if shift was also pressed
\r
416 //! True if ctrl was also pressed
\r
420 //! String input event.
\r
421 struct SStringInput
\r
423 //! The string that is entered
\r
424 core::stringw *Str;
\r
427 //! Any kind of touch event.
\r
433 // X position of simple touch.
\r
436 // Y position of simple touch.
\r
439 // number of current touches
\r
442 //! Type of touch event.
\r
443 ETOUCH_INPUT_EVENT Event;
\r
446 //! Any kind of accelerometer event.
\r
447 struct SAccelerometerEvent
\r
459 //! Any kind of gyroscope event.
\r
460 struct SGyroscopeEvent
\r
472 //! Any kind of device motion event.
\r
473 struct SDeviceMotionEvent
\r
478 // Y angle - pitch.
\r
485 //! A joystick event.
\r
486 /** Unlike other events, joystick events represent the result of polling
\r
487 * each connected joystick once per run() of the device. Joystick events will
\r
488 * not be generated by default. If joystick support is available for the
\r
489 * active device, _IRR_COMPILE_WITH_JOYSTICK_EVENTS_ is defined, and
\r
490 * @ref irr::IrrlichtDevice::activateJoysticks() has been called, an event of
\r
491 * this type will be generated once per joystick per @ref IrrlichtDevice::run()
\r
492 * regardless of whether the state of the joystick has actually changed. */
\r
493 struct SJoystickEvent
\r
497 NUMBER_OF_BUTTONS = 32,
\r
499 AXIS_X = 0, // e.g. analog stick 1 left to right
\r
500 AXIS_Y, // e.g. analog stick 1 top to bottom
\r
501 AXIS_Z, // e.g. throttle, or analog 2 stick 2 left to right
\r
502 AXIS_R, // e.g. rudder, or analog 2 stick 2 top to bottom
\r
505 NUMBER_OF_AXES=18 // (please tell Irrlicht maintainers if you absolutely need more axes)
\r
508 /** A bitmap of button states. You can use IsButtonPressed() to
\r
509 ( check the state of each button from 0 to (NUMBER_OF_BUTTONS - 1) */
\r
512 /** For AXIS_X, AXIS_Y, AXIS_Z, AXIS_R, AXIS_U and AXIS_V
\r
513 * Values are in the range -32768 to 32767, with 0 representing
\r
514 * the center position. You will receive the raw value from the
\r
515 * joystick, and so will usually want to implement a dead zone around
\r
516 * the center of the range. Axes not supported by this joystick will
\r
517 * always have a value of 0. On Linux, POV hats are represented as axes,
\r
518 * usually the last two active axis.
\r
520 s16 Axis[NUMBER_OF_AXES];
\r
522 /** The POV represents the angle of the POV hat in degrees * 100,
\r
523 * from 0 to 35,900. A value of 65535 indicates that the POV hat
\r
524 * is centered (or not present).
\r
525 * This value is only supported on Windows. On Linux, the POV hat
\r
526 * will be sent as 2 axes instead. */
\r
529 //! The ID of the joystick which generated this event.
\r
530 /** This is an internal Irrlicht index; it does not map directly
\r
531 * to any particular hardware joystick. */
\r
534 //! A helper function to check if a button is pressed.
\r
535 bool IsButtonPressed(u32 button) const
\r
537 if(button >= (u32)NUMBER_OF_BUTTONS)
\r
540 return (ButtonStates & (1 << button)) ? true : false;
\r
544 //! Any kind of log event.
\r
547 //! Pointer to text which has been logged
\r
550 //! Log level in which the text has been logged
\r
554 //! Any kind of user event.
\r
557 //! Some user specified data as int
\r
560 //! Another user specified data as int
\r
564 // Raw events from the OS
\r
565 struct SSystemEvent
\r
567 //! Android command handler native activity messages.
\r
570 //! APP_CMD_ enums defined in android_native_app_glue.h from the Android NDK
\r
574 // TOOD: more structs for iphone, Windows, X11, etc.
\r
576 ESYSTEM_EVENT_TYPE EventType;
\r
579 struct SAndroidCmd AndroidCmd;
\r
583 // Application state event
\r
584 struct SApplicationEvent
\r
586 EAPPLICATION_EVENT_TYPE EventType;
\r
589 EEVENT_TYPE EventType;
\r
592 struct SGUIEvent GUIEvent;
\r
593 struct SMouseInput MouseInput;
\r
594 struct SKeyInput KeyInput;
\r
595 struct SStringInput StringInput;
\r
596 struct STouchInput TouchInput;
\r
597 struct SAccelerometerEvent AccelerometerEvent;
\r
598 struct SGyroscopeEvent GyroscopeEvent;
\r
599 struct SDeviceMotionEvent DeviceMotionEvent;
\r
600 struct SJoystickEvent JoystickEvent;
\r
601 struct SLogEvent LogEvent;
\r
602 struct SUserEvent UserEvent;
\r
603 struct SSystemEvent SystemEvent;
\r
604 struct SApplicationEvent ApplicationEvent;
\r
609 //! Interface of an object which can receive events.
\r
610 /** Many of the engine's classes inherit IEventReceiver so they are able to
\r
611 process events. Events usually start at a postEventFromUser function and are
\r
612 passed down through a chain of event receivers until OnEvent returns true. See
\r
613 irr::EEVENT_TYPE for a description of where each type of event starts, and the
\r
614 path it takes through the system. */
\r
615 class IEventReceiver
\r
620 virtual ~IEventReceiver() {}
\r
622 //! Called if an event happened.
\r
623 /** Please take care that you should only return 'true' when you want to _prevent_ Irrlicht
\r
624 * from processing the event any further. So 'true' does mean that an event is completely done.
\r
625 * Therefore your return value for all unprocessed events should be 'false'.
\r
626 \return True if the event was processed.
\r
628 virtual bool OnEvent(const SEvent& event) = 0;
\r
632 //! Information on a joystick, returned from @ref irr::IrrlichtDevice::activateJoysticks()
\r
633 struct SJoystickInfo
\r
635 //! The ID of the joystick
\r
636 /** This is an internal Irrlicht index; it does not map directly
\r
637 * to any particular hardware joystick. It corresponds to the
\r
638 * irr::SJoystickEvent Joystick ID. */
\r
641 //! The name that the joystick uses to identify itself.
\r
642 core::stringc Name;
\r
644 //! The number of buttons that the joystick has.
\r
647 //! The number of axes that the joystick has, i.e. X, Y, Z, R, U, V.
\r
648 /** Note: with a Linux device, the POV hat (if any) will use two axes. These
\r
649 * will be included in this count. */
\r
652 //! An indication of whether the joystick has a POV hat.
\r
653 /** A Windows device will identify the presence or absence of the POV hat.
\r
654 * A Linux device cannot, and will always return POV_HAT_UNKNOWN. */
\r
657 //! A hat is definitely present.
\r
660 //! A hat is definitely not present.
\r
663 //! The presence or absence of a hat cannot be determined.
\r
666 }; // struct SJoystickInfo
\r
669 } // end namespace irr
\r