IEventReceiver.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600
  1. // Copyright (C) 2002-2012 Nikolaus Gebhardt
  2. // This file is part of the "Irrlicht Engine".
  3. // For conditions of distribution and use, see copyright notice in irrlicht.h
  4. #pragma once
  5. #include "ILogger.h"
  6. #include "Keycodes.h"
  7. #include "irrString.h"
  8. namespace irr
  9. {
  10. //! Enumeration for all event types there are.
  11. enum EEVENT_TYPE
  12. {
  13. //! An event of the graphical user interface.
  14. /** GUI events are created by the GUI environment or the GUI elements in response
  15. to mouse or keyboard events. When a GUI element receives an event it will either
  16. process it and return true, or pass the event to its parent. If an event is not absorbed
  17. before it reaches the root element then it will then be passed to the user receiver. */
  18. EET_GUI_EVENT = 0,
  19. //! A mouse input event.
  20. /** Mouse events are created by the device and passed to IrrlichtDevice::postEventFromUser
  21. in response to mouse input received from the operating system.
  22. Mouse events are first passed to the user receiver, then to the GUI environment and its elements,
  23. then finally the input receiving scene manager where it is passed to the active camera.
  24. */
  25. EET_MOUSE_INPUT_EVENT,
  26. //! A key input event.
  27. /** Like mouse events, keyboard events are created by the device and passed to
  28. IrrlichtDevice::postEventFromUser. They take the same path as mouse events. */
  29. EET_KEY_INPUT_EVENT,
  30. //! A string input event.
  31. /** This event is created when multiple characters are sent at a time (e.g. using an IME). */
  32. EET_STRING_INPUT_EVENT,
  33. //! A touch input event.
  34. EET_TOUCH_INPUT_EVENT,
  35. //! A accelerometer event.
  36. EET_ACCELEROMETER_EVENT,
  37. //! A gyroscope event.
  38. EET_GYROSCOPE_EVENT,
  39. //! A device motion event.
  40. EET_DEVICE_MOTION_EVENT,
  41. //! A joystick (joypad, gamepad) input event.
  42. /** Joystick events are created by polling all connected joysticks once per
  43. device run() and then passing the events to IrrlichtDevice::postEventFromUser.
  44. They take the same path as mouse events.
  45. Windows, SDL: Implemented.
  46. Linux: Implemented, with POV hat issues.
  47. MacOS / Other: Not yet implemented.
  48. */
  49. EET_JOYSTICK_INPUT_EVENT,
  50. //! A log event
  51. /** Log events are only passed to the user receiver if there is one. If they are absorbed by the
  52. user receiver then no text will be sent to the console. */
  53. EET_LOG_TEXT_EVENT,
  54. //! A user event with user data.
  55. /** This is not used by Irrlicht and can be used to send user
  56. specific data though the system. The Irrlicht 'window handle'
  57. can be obtained from IrrlichtDevice::getExposedVideoData()
  58. The usage and behavior depends on the operating system:
  59. Windows: send a WM_USER message to the Irrlicht Window; the
  60. wParam and lParam will be used to populate the
  61. UserData1 and UserData2 members of the SUserEvent.
  62. Linux: send a ClientMessage via XSendEvent to the Irrlicht
  63. Window; the data.l[0] and data.l[1] members will be
  64. cast to s32 and used as UserData1 and UserData2.
  65. MacOS: Not yet implemented
  66. */
  67. EET_USER_EVENT,
  68. //! Application state events like a resume, pause etc.
  69. EET_APPLICATION_EVENT,
  70. //! This enum is never used, it only forces the compiler to
  71. //! compile these enumeration values to 32 bit.
  72. EGUIET_FORCE_32_BIT = 0x7fffffff
  73. };
  74. //! Enumeration for all mouse input events
  75. enum EMOUSE_INPUT_EVENT
  76. {
  77. //! Left mouse button was pressed down.
  78. EMIE_LMOUSE_PRESSED_DOWN = 0,
  79. //! Right mouse button was pressed down.
  80. EMIE_RMOUSE_PRESSED_DOWN,
  81. //! Middle mouse button was pressed down.
  82. EMIE_MMOUSE_PRESSED_DOWN,
  83. //! Left mouse button was left up.
  84. EMIE_LMOUSE_LEFT_UP,
  85. //! Right mouse button was left up.
  86. EMIE_RMOUSE_LEFT_UP,
  87. //! Middle mouse button was left up.
  88. EMIE_MMOUSE_LEFT_UP,
  89. //! The mouse cursor changed its position.
  90. EMIE_MOUSE_MOVED,
  91. //! The mouse wheel was moved. Use Wheel value in event data to find out
  92. //! in what direction and how fast.
  93. EMIE_MOUSE_WHEEL,
  94. //! Left mouse button double click.
  95. //! This event is generated after the second EMIE_LMOUSE_PRESSED_DOWN event.
  96. EMIE_LMOUSE_DOUBLE_CLICK,
  97. //! Right mouse button double click.
  98. //! This event is generated after the second EMIE_RMOUSE_PRESSED_DOWN event.
  99. EMIE_RMOUSE_DOUBLE_CLICK,
  100. //! Middle mouse button double click.
  101. //! This event is generated after the second EMIE_MMOUSE_PRESSED_DOWN event.
  102. EMIE_MMOUSE_DOUBLE_CLICK,
  103. //! Left mouse button triple click.
  104. //! This event is generated after the third EMIE_LMOUSE_PRESSED_DOWN event.
  105. EMIE_LMOUSE_TRIPLE_CLICK,
  106. //! Right mouse button triple click.
  107. //! This event is generated after the third EMIE_RMOUSE_PRESSED_DOWN event.
  108. EMIE_RMOUSE_TRIPLE_CLICK,
  109. //! Middle mouse button triple click.
  110. //! This event is generated after the third EMIE_MMOUSE_PRESSED_DOWN event.
  111. EMIE_MMOUSE_TRIPLE_CLICK,
  112. //! Mouse enters canvas used for rendering.
  113. //! Only generated on emscripten
  114. EMIE_MOUSE_ENTER_CANVAS,
  115. //! Mouse leaves canvas used for rendering.
  116. //! Only generated on emscripten
  117. EMIE_MOUSE_LEAVE_CANVAS,
  118. //! No real event. Just for convenience to get number of events
  119. EMIE_COUNT
  120. };
  121. //! Masks for mouse button states
  122. enum E_MOUSE_BUTTON_STATE_MASK
  123. {
  124. EMBSM_LEFT = 0x01,
  125. EMBSM_RIGHT = 0x02,
  126. EMBSM_MIDDLE = 0x04,
  127. //! currently only on windows
  128. EMBSM_EXTRA1 = 0x08,
  129. //! currently only on windows
  130. EMBSM_EXTRA2 = 0x10,
  131. EMBSM_FORCE_32_BIT = 0x7fffffff
  132. };
  133. //! Enumeration for all touch input events
  134. enum ETOUCH_INPUT_EVENT
  135. {
  136. //! Touch was pressed down.
  137. ETIE_PRESSED_DOWN = 0,
  138. //! Touch was left up.
  139. ETIE_LEFT_UP,
  140. //! The touch changed its position.
  141. ETIE_MOVED,
  142. //! No real event. Just for convenience to get number of events
  143. ETIE_COUNT
  144. };
  145. //! Enumeration for a commonly used application state events (it's useful mainly for mobile devices)
  146. enum EAPPLICATION_EVENT_TYPE
  147. {
  148. //! The application will be resumed.
  149. EAET_WILL_RESUME = 0,
  150. //! The application has been resumed.
  151. EAET_DID_RESUME,
  152. //! The application will be paused.
  153. EAET_WILL_PAUSE,
  154. //! The application has been paused.
  155. EAET_DID_PAUSE,
  156. //! The application will be terminated.
  157. EAET_WILL_TERMINATE,
  158. //! The application received a memory warning.
  159. EAET_MEMORY_WARNING,
  160. //! The display density changed (only works on SDL).
  161. EAET_DPI_CHANGED,
  162. //! No real event, but to get number of event types.
  163. EAET_COUNT
  164. };
  165. namespace gui
  166. {
  167. class IGUIElement;
  168. //! Enumeration for all events which are sendable by the gui system
  169. enum EGUI_EVENT_TYPE
  170. {
  171. //! A gui element has lost its focus.
  172. /** GUIEvent.Caller is losing the focus to GUIEvent.Element.
  173. If the event is absorbed then the focus will not be changed. */
  174. EGET_ELEMENT_FOCUS_LOST = 0,
  175. //! A gui element has got the focus.
  176. /** If the event is absorbed then the focus will not be changed. */
  177. EGET_ELEMENT_FOCUSED,
  178. //! The mouse cursor hovered over a gui element.
  179. /** If an element has sub-elements you also get this message for the subelements */
  180. EGET_ELEMENT_HOVERED,
  181. //! The mouse cursor left the hovered element.
  182. /** If an element has sub-elements you also get this message for the subelements */
  183. EGET_ELEMENT_LEFT,
  184. //! An element would like to close.
  185. /** Windows and context menus use this event when they would like to close,
  186. this can be canceled by absorbing the event. */
  187. EGET_ELEMENT_CLOSED,
  188. //! A button was clicked.
  189. EGET_BUTTON_CLICKED,
  190. //! A scrollbar has changed its position.
  191. EGET_SCROLL_BAR_CHANGED,
  192. //! A checkbox has changed its check state.
  193. EGET_CHECKBOX_CHANGED,
  194. //! A listbox would like to open.
  195. /** You can prevent the listbox from opening by absorbing the event. */
  196. EGET_LISTBOX_OPENED,
  197. //! A new item in a listbox was selected.
  198. /** NOTE: You also get this event currently when the same item was clicked again after more than 500 ms. */
  199. EGET_LISTBOX_CHANGED,
  200. //! An item in the listbox was selected, which was already selected.
  201. /** NOTE: You get the event currently only if the item was clicked again within 500 ms or selected by "enter" or "space". */
  202. EGET_LISTBOX_SELECTED_AGAIN,
  203. //! A file has been selected in the file dialog
  204. EGET_FILE_SELECTED,
  205. //! A directory has been selected in the file dialog
  206. EGET_DIRECTORY_SELECTED,
  207. //! A file open dialog has been closed without choosing a file
  208. EGET_FILE_CHOOSE_DIALOG_CANCELLED,
  209. //! In an editbox 'ENTER' was pressed
  210. EGET_EDITBOX_ENTER,
  211. //! The text in an editbox was changed. This does not include automatic changes in text-breaking.
  212. EGET_EDITBOX_CHANGED,
  213. //! The marked area in an editbox was changed.
  214. EGET_EDITBOX_MARKING_CHANGED,
  215. //! The tab was changed in an tab control
  216. EGET_TAB_CHANGED,
  217. //! The selection in a combo box has been changed
  218. EGET_COMBO_BOX_CHANGED,
  219. //! A table has changed
  220. EGET_TABLE_CHANGED,
  221. EGET_TABLE_HEADER_CHANGED,
  222. EGET_TABLE_SELECTED_AGAIN,
  223. //! No real event. Just for convenience to get number of events
  224. EGET_COUNT
  225. };
  226. } // end namespace gui
  227. //! SEvents hold information about an event. See irr::IEventReceiver for details on event handling.
  228. struct SEvent
  229. {
  230. //! Any kind of GUI event.
  231. struct SGUIEvent
  232. {
  233. //! IGUIElement who called the event
  234. gui::IGUIElement *Caller;
  235. //! If the event has something to do with another element, it will be held here.
  236. gui::IGUIElement *Element;
  237. //! Type of GUI Event
  238. gui::EGUI_EVENT_TYPE EventType;
  239. };
  240. //! Any kind of mouse event.
  241. struct SMouseInput
  242. {
  243. //! X position of mouse cursor
  244. s32 X;
  245. //! Y position of mouse cursor
  246. s32 Y;
  247. //! mouse wheel delta, often 1.0 or -1.0, but can have other values < 0.f or > 0.f;
  248. /** Only valid if event was EMIE_MOUSE_WHEEL */
  249. f32 Wheel;
  250. //! True if shift was also pressed
  251. bool Shift : 1;
  252. //! True if ctrl was also pressed
  253. bool Control : 1;
  254. //! A bitmap of button states. You can use isButtonPressed() to determine
  255. //! if a button is pressed or not.
  256. u32 ButtonStates;
  257. //! Is the left button pressed down?
  258. bool isLeftPressed() const { return 0 != (ButtonStates & EMBSM_LEFT); }
  259. //! Is the right button pressed down?
  260. bool isRightPressed() const { return 0 != (ButtonStates & EMBSM_RIGHT); }
  261. //! Is the middle button pressed down?
  262. bool isMiddlePressed() const { return 0 != (ButtonStates & EMBSM_MIDDLE); }
  263. //! Type of mouse event
  264. EMOUSE_INPUT_EVENT Event;
  265. };
  266. //! Any kind of keyboard event.
  267. struct SKeyInput
  268. {
  269. //! Character corresponding to the key (0, if not a character, value undefined in key releases)
  270. wchar_t Char;
  271. //! Key which has been pressed or released
  272. EKEY_CODE Key;
  273. //! System dependent code. Only set for systems which are described below, otherwise undefined.
  274. //! Android: int32_t with physical key as returned by AKeyEvent_getKeyCode
  275. u32 SystemKeyCode;
  276. //! If not true, then the key was left up
  277. bool PressedDown : 1;
  278. //! True if shift was also pressed
  279. bool Shift : 1;
  280. //! True if ctrl was also pressed
  281. bool Control : 1;
  282. };
  283. //! String input event.
  284. struct SStringInput
  285. {
  286. //! The string that is entered
  287. core::stringw *Str;
  288. };
  289. //! Any kind of touch event.
  290. struct STouchInput
  291. {
  292. // Touch ID.
  293. size_t ID;
  294. // X position of simple touch.
  295. s32 X;
  296. // Y position of simple touch.
  297. s32 Y;
  298. // number of current touches
  299. s32 touchedCount;
  300. //! Type of touch event.
  301. ETOUCH_INPUT_EVENT Event;
  302. };
  303. //! Any kind of accelerometer event.
  304. struct SAccelerometerEvent
  305. {
  306. // X acceleration.
  307. f64 X;
  308. // Y acceleration.
  309. f64 Y;
  310. // Z acceleration.
  311. f64 Z;
  312. };
  313. //! Any kind of gyroscope event.
  314. struct SGyroscopeEvent
  315. {
  316. // X rotation.
  317. f64 X;
  318. // Y rotation.
  319. f64 Y;
  320. // Z rotation.
  321. f64 Z;
  322. };
  323. //! Any kind of device motion event.
  324. struct SDeviceMotionEvent
  325. {
  326. // X angle - roll.
  327. f64 X;
  328. // Y angle - pitch.
  329. f64 Y;
  330. // Z angle - yaw.
  331. f64 Z;
  332. };
  333. //! A joystick event.
  334. /** Unlike other events, joystick events represent the result of polling
  335. * each connected joystick once per run() of the device. Joystick events will
  336. * not be generated by default. If joystick support is available for the
  337. * active device, and @ref irr::IrrlichtDevice::activateJoysticks() has been
  338. * called, an event of this type will be generated once per joystick per
  339. * @ref IrrlichtDevice::run() regardless of whether the state of the joystick
  340. * has actually changed. */
  341. struct SJoystickEvent
  342. {
  343. enum
  344. {
  345. NUMBER_OF_BUTTONS = 32,
  346. AXIS_X = 0, // e.g. analog stick 1 left to right
  347. AXIS_Y, // e.g. analog stick 1 top to bottom
  348. AXIS_Z, // e.g. throttle, or analog 2 stick 2 left to right
  349. AXIS_R, // e.g. rudder, or analog 2 stick 2 top to bottom
  350. AXIS_U,
  351. AXIS_V,
  352. NUMBER_OF_AXES = 18 // (please tell Irrlicht maintainers if you absolutely need more axes)
  353. };
  354. /** A bitmap of button states. You can use IsButtonPressed() to
  355. ( check the state of each button from 0 to (NUMBER_OF_BUTTONS - 1) */
  356. u32 ButtonStates;
  357. /** For AXIS_X, AXIS_Y, AXIS_Z, AXIS_R, AXIS_U and AXIS_V
  358. * Values are in the range -32768 to 32767, with 0 representing
  359. * the center position. You will receive the raw value from the
  360. * joystick, and so will usually want to implement a dead zone around
  361. * the center of the range. Axes not supported by this joystick will
  362. * always have a value of 0. On Linux, POV hats are represented as axes,
  363. * usually the last two active axis.
  364. */
  365. s16 Axis[NUMBER_OF_AXES];
  366. /** The POV represents the angle of the POV hat in degrees * 100,
  367. * from 0 to 35,900. A value of 65535 indicates that the POV hat
  368. * is centered (or not present).
  369. * This value is only supported on Windows. On Linux, the POV hat
  370. * will be sent as 2 axes instead. */
  371. u16 POV;
  372. //! The ID of the joystick which generated this event.
  373. /** This is an internal Irrlicht index; it does not map directly
  374. * to any particular hardware joystick. */
  375. u8 Joystick;
  376. //! A helper function to check if a button is pressed.
  377. bool IsButtonPressed(u32 button) const
  378. {
  379. if (button >= (u32)NUMBER_OF_BUTTONS)
  380. return false;
  381. return (ButtonStates & (1 << button)) ? true : false;
  382. }
  383. };
  384. //! Any kind of log event.
  385. struct SLogEvent
  386. {
  387. //! Pointer to text which has been logged
  388. const c8 *Text;
  389. //! Log level in which the text has been logged
  390. ELOG_LEVEL Level;
  391. };
  392. //! Any kind of user event.
  393. struct SUserEvent
  394. {
  395. //! Some user specified data as int
  396. size_t UserData1;
  397. //! Another user specified data as int
  398. size_t UserData2;
  399. };
  400. // Application state event
  401. struct SApplicationEvent
  402. {
  403. EAPPLICATION_EVENT_TYPE EventType;
  404. };
  405. EEVENT_TYPE EventType;
  406. union
  407. {
  408. struct SGUIEvent GUIEvent;
  409. struct SMouseInput MouseInput;
  410. struct SKeyInput KeyInput;
  411. struct SStringInput StringInput;
  412. struct STouchInput TouchInput;
  413. struct SAccelerometerEvent AccelerometerEvent;
  414. struct SGyroscopeEvent GyroscopeEvent;
  415. struct SDeviceMotionEvent DeviceMotionEvent;
  416. struct SJoystickEvent JoystickEvent;
  417. struct SLogEvent LogEvent;
  418. struct SUserEvent UserEvent;
  419. struct SApplicationEvent ApplicationEvent;
  420. };
  421. };
  422. //! Interface of an object which can receive events.
  423. /** Many of the engine's classes inherit IEventReceiver so they are able to
  424. process events. Events usually start at a postEventFromUser function and are
  425. passed down through a chain of event receivers until OnEvent returns true. See
  426. irr::EEVENT_TYPE for a description of where each type of event starts, and the
  427. path it takes through the system. */
  428. class IEventReceiver
  429. {
  430. public:
  431. //! Destructor
  432. virtual ~IEventReceiver() {}
  433. //! Called if an event happened.
  434. /** Please take care that you should only return 'true' when you want to _prevent_ Irrlicht
  435. * from processing the event any further. So 'true' does mean that an event is completely done.
  436. * Therefore your return value for all unprocessed events should be 'false'.
  437. \return True if the event was processed.
  438. */
  439. virtual bool OnEvent(const SEvent &event) = 0;
  440. };
  441. //! Information on a joystick, returned from @ref irr::IrrlichtDevice::activateJoysticks()
  442. struct SJoystickInfo
  443. {
  444. //! The ID of the joystick
  445. /** This is an internal Irrlicht index; it does not map directly
  446. * to any particular hardware joystick. It corresponds to the
  447. * irr::SJoystickEvent Joystick ID. */
  448. u8 Joystick;
  449. //! The name that the joystick uses to identify itself.
  450. core::stringc Name;
  451. //! The number of buttons that the joystick has.
  452. u32 Buttons;
  453. //! The number of axes that the joystick has, i.e. X, Y, Z, R, U, V.
  454. /** Note: with a Linux device, the POV hat (if any) will use two axes. These
  455. * will be included in this count. */
  456. u32 Axes;
  457. //! An indication of whether the joystick has a POV hat.
  458. /** A Windows device will identify the presence or absence of the POV hat.
  459. * A Linux device cannot, and will always return POV_HAT_UNKNOWN. */
  460. enum
  461. {
  462. //! A hat is definitely present.
  463. POV_HAT_PRESENT,
  464. //! A hat is definitely not present.
  465. POV_HAT_ABSENT,
  466. //! The presence or absence of a hat cannot be determined.
  467. POV_HAT_UNKNOWN
  468. } PovHat;
  469. }; // struct SJoystickInfo
  470. } // end namespace irr