changeset 568:2b2844ab4e6b

core: doxygenize event
author David Demelier <markand@malikania.fr>
date Wed, 08 Mar 2023 21:30:32 +0100
parents 90302d95cd33
children e13d79a14791
files libmlk-core/mlk/core/event.h
diffstat 1 files changed, 185 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/libmlk-core/mlk/core/event.h	Wed Mar 08 21:13:07 2023 +0100
+++ b/libmlk-core/mlk/core/event.h	Wed Mar 08 21:30:32 2023 +0100
@@ -19,60 +19,237 @@
 #ifndef MLK_CORE_EVENT_H
 #define MLK_CORE_EVENT_H
 
+/**
+ * \file mlk/core/event.h
+ * \brief Event management
+ *
+ * The Molko's Engine framework pushes input events into a queue that the main
+ * loop should pull out in the main game loop. For maximum reactivity, the
+ * events should be pull all at once in the beginning of the loop.
+ *
+ * An event is described as an union (::mlk_event) storing every event
+ * supported by the framework. The union has a special ::mlk_event::type field
+ * describing the type and which underlying structure to use.
+ *
+ * See the enumeration constants for more details.
+ */
+
 #include "key.h"
 #include "mouse.h"
 #include "gamepad.h"
 
+/**
+ * \enum mlk_event_type
+ * \brief Describe an event
+ */
 enum mlk_event_type {
+	/**
+	 * Mouse click press.
+	 *
+	 * Access through ::mlk_event::click.
+	 */
 	MLK_EVENT_CLICKDOWN,
+
+	/**
+	 * Mouse click release.
+	 *
+	 * Access through ::mlk_event::click.
+	 */
 	MLK_EVENT_CLICKUP,
+
+	/**
+	 * Keyboard key press.
+	 *
+	 * Access through ::mlk_event::key.
+	 */
 	MLK_EVENT_KEYDOWN,
+
+	/**
+	 * Keyboard key release.
+	 *
+	 * Access through ::mlk_event::key.
+	 */
 	MLK_EVENT_KEYUP,
+
+	/**
+	 * Mouse motion.
+	 *
+	 * Access through ::mlk_event::mouse.
+	 */
 	MLK_EVENT_MOUSE,
+
+	/**
+	 * Game controller D-Pad/button press.
+	 *
+	 * Access through ::mlk_event::pad.
+	 */
 	MLK_EVENT_PADUP,
+
+	/**
+	 * Game controller D-Pad/button release.
+	 *
+	 * Access through ::mlk_event::pad.
+	 */
 	MLK_EVENT_PADDOWN,
+
+	/**
+	 * Game controller joystick axis motion.
+	 *
+	 * Access through ::mlk_event::axis.
+	 */
 	MLK_EVENT_AXIS,
+
+	/**
+	 * Window manager quit event.
+	 *
+	 * No value.
+	 */
 	MLK_EVENT_QUIT,
-	MLK_EVENT_NUM
 };
 
+/**
+ * \struct mlk_event_key
+ * \brief Keyboard event press/release
+ */
 struct mlk_event_key {
+	/**
+	 * Set to ::MLK_EVENT_KEYDOWN or ::MLK_EVENT_KEYUP.
+	 */
 	enum mlk_event_type type;
+
+	/**
+	 * Which key constant has been pressed/released.
+	 */
 	enum mlk_key key;
 };
 
+/**
+ * \struct mlk_event_mouse
+ * \brief Mouse motion event
+ */
 struct mlk_event_mouse {
+	/**
+	 * Set to MLK_EVENT_MOUSE.
+	 */
 	enum mlk_event_type type;
+
+	/**
+	 * Buttons currently pressed as a bitmask.
+	 */
 	enum mlk_mouse_button buttons;
+
+	/**
+	 * New mouse position in x.
+	 */
 	int x;
+
+	/**
+	 * New mouse position in y.
+	 */
 	int y;
 };
 
+/**
+ * \struct mlk_event_click
+ * \brief Mouse button click
+ */
 struct mlk_event_click {
+	/**
+	 * Set to ::MLK_EVENT_CLICKDOWN or ::MLK_EVENT_CLICKUP.
+	 */
 	enum mlk_event_type type;
+
+	/**
+	 * Which button has been pressed/released.
+	 */
 	enum mlk_mouse_button button;
+
+	/**
+	 * Position in x.
+	 */
 	int x;
+
+	/**
+	 * Position in y.
+	 */
 	int y;
+
+	/**
+	 * Number of clicks if supported.
+	 */
 	unsigned int clicks;
 };
 
+/**
+ * \struct mlk_event_pad
+ * \brief Game controller button press/release
+ */
 struct mlk_event_pad {
+	/**
+	 * Set to ::MLK_EVENT_PADDOWN or ::MLK_EVENT_PADUP.
+	 */
 	enum mlk_event_type type;
+
+	/**
+	 * Game controller button that has been pressed/released
+	 */
 	enum mlk_gamepad_button button;
 };
 
+/**
+ * \struct mlk_event_axis
+ * \brief Game controller joystick axis event
+ */
 struct mlk_event_axis {
+	/**
+	 * Set to ::MLK_EVENT_AXIS.
+	 */
 	enum mlk_event_type type;
+
+	/**
+	 * Which axis.
+	 */
 	enum mlk_gamepad_axis axis;
+
+	/**
+	 * The new value.
+	 */
 	int value;
 };
 
+/**
+ * \union mlk_event
+ * \brief Generic input event
+ */
 union mlk_event {
+	/**
+	 * Present for all substructures to be present in the union itself.
+	 */
 	enum mlk_event_type type;
+
+	/**
+	 * For ::MLK_EVENT_KEYDOWN, ::MLK_EVENT_KEYUP.
+	 */
 	struct mlk_event_key key;
+
+	/**
+	 * For ::MLK_EVENT_MOUSE.
+	 */
 	struct mlk_event_mouse mouse;
+
+	/**
+	 * For ::MLK_EVENT_CLICKDOWN, ::MLK_EVENT_CLICKUP.
+	 */
 	struct mlk_event_click click;
+
+	/**
+	 * For ::MLK_EVENT_PADDOWN, ::MLK_EVENT_PADUP.
+	 */
 	struct mlk_event_pad pad;
+
+	/**
+	 * For ::MLK_EVENT_AXIS.
+	 */
 	struct mlk_event_axis axis;
 };
 
@@ -80,8 +257,14 @@
 extern "C" {
 #endif
 
+/**
+ * Get the next event in the queue.
+ *
+ * \param event the event to fill
+ * \return 1 if an event was found, 0 otherwise
+ */
 int
-mlk_event_poll(union mlk_event *);
+mlk_event_poll(union mlk_event *event);
 
 #if defined(__cplusplus)
 }