Merge pull request #128 from cschreib/button-click

Allow configuring which events trigger Button click

Author: cschreib

include/lxgui/gui_button.hpp

@@ -27,16 +27,25 @@ class font_string;
  * case, the "normal" font is rendered with a slight offset that you
  * are free to define.
  *
- * Note that a button has frame::enable_mouse set to `true` by
+ * The button "click" event will be triggered by all registered combinations
+ * of mouse events configured with button::enable_button_clicks.
+ *
+ * Note that a button has frame::enable_mouse set to `true` and
+ * button::enable_button_clicks set to `true` for `"LeftMouseUp"` by
  * default.
  *
  * __Events.__ Hard-coded events available to all buttons, in
  * addition to those from frame:
  *
  * - `OnClick`: Triggered when the button is clicked, either when
- * button::click is called, or just when a mouse button is pressed
- * when the cursor is over the button.
- * - `OnDoubleClick`: Triggered when the button is double-clicked.
+ * button::click is called, or just when a mouse button is released or
+ * pressed when the cursor is over the button (depending on whether clicks
+ * are enabled for the mouse button and mouse button state, see
+ * button::enable_button_clicks). This event provides five arguments to
+ * the registered callback: a number identifying the mouse button, a number
+ * identifying the mouse button event, a string containing the human-readable
+ * name of this button event (e.g., `"LeftButtonUp"`, `"RightButtonDown"`, ...),
+ * and the mouse X and Y position.
  * - `OnEnable`: Triggered by button::enable.
  * - `OnDisable`: Triggered by button::disable.
  */
@@ -301,6 +310,21 @@ class button : public frame {
      */
     virtual void release();
 
+    /**
+     * \brief Handle a mouse click over this button.
+     * \param mouse_event The mouse event with which to generate a click
+     * \note This calls the OnClick() handler only if the event is registered for clicks.
+     */
+    void click(const std::string& mouse_event);
+
+    /**
+     * \brief Handle a mouse click over this button.
+     * \param button_id The mouse button with which to generate a click
+     * \param button_event The mouse button event with which to generate a click
+     * \note This calls the OnClick() handler only if the event is registered for clicks.
+     */
+    void click(input::mouse_button button_id, input::mouse_button_event button_event);
+
     /**
      * \brief Highlights this button.
      * \note The button will be highlighted even if the
@@ -345,6 +369,99 @@ class button : public frame {
      */
     const vector2f& get_pushed_text_offset() const;
 
+    /**
+     * \brief Make this button generate OnClick events when a specific mouse event occurs over the button.
+     * \param mouse_event The mouse event for which to enable or disable OnClick events
+     * \param enable 'true' to enable, 'false' to disable
+     * \see enable_button_clicks()
+     * \see disable_button_clicks()
+     */
+    void set_button_clicks_enabled(const std::string& mouse_event, bool enable) {
+        if (enable) {
+            enable_button_clicks(mouse_event);
+        } else {
+            disable_button_clicks(mouse_event);
+        }
+    }
+
+    /**
+     * \brief Make this button generate OnClick events when a specific mouse event occurs over the button.
+     * \param button_id The mouse button for which to enable or disable OnClick events
+     * \param button_event The mouse button event for which to enable or disable OnClick events
+     * \param enable 'true' to enable, 'false' to disable
+     * \see enable_button_clicks()
+     * \see disable_button_clicks()
+     */
+    void set_button_clicks_enabled(
+        input::mouse_button button_id, input::mouse_button_event button_event, bool enable) {
+        if (enable) {
+            enable_button_clicks(button_id, button_event);
+        } else {
+            disable_button_clicks(button_id, button_event);
+        }
+    }
+
+    /**
+     * \brief Make this button generate OnClick events when a specific mouse event occurs over the button.
+     * \param mouse_event The mouse event for which to enable OnClick events
+     * \note The mouse event string must be of the form "<button>Up" or "<button>Down". For
+     * example, "LeftButtonUp".
+     * \see disable_button_clicks()
+     */
+    void enable_button_clicks(const std::string& mouse_event);
+
+    /**
+     * \brief Make this button generate OnClick events when a specific mouse event occurs over the button.
+     * \param button_id The mouse button for which to enable OnClick events
+     * \param button_event The mouse button event for which to enable OnClick events
+     * \note See @ref enable_button_clicks(const std::string&) for more information.
+     * \see disable_button_clicks()
+     */
+    void
+    enable_button_clicks(input::mouse_button button_id, input::mouse_button_event button_event);
+
+    /**
+     * \brief Stop this button from generating OnClick events when a specific mouse event occurs over the button.
+     * \param mouse_event The mouse event for which to stop generating OnClick events
+     * \see enable_button_clicks()
+     */
+    void disable_button_clicks(const std::string& mouse_event);
+
+    /**
+     * \brief Stop this button from generating OnClick events when a specific mouse event occurs over the button.
+     * \param button_id The mouse button for which to stop generating OnClick events
+     * \param button_event The state of the button for which to stop generating OnClick events
+     * \note See @ref disable_button_clicks(const std::string&) for more information.
+     * \see enable_button_clicks()
+     */
+    void
+    disable_button_clicks(input::mouse_button button_id, input::mouse_button_event button_event);
+
+    /**
+     * \brief Stop this button from generating OnClick events.
+     * \see enable_button_clicks()
+     * \see is_button_clicks_enabled()
+     */
+    void disable_button_clicks();
+
+    /**
+     * \brief Checks if this button can generate OnClick events when a specific mouse event occurs over the button.
+     * \param mouse_event The mouse event to check
+     * \return 'true' if this button can generate OnClick events from this mouse event
+     * \see enable_button_clicks()
+     */
+    bool is_button_clicks_enabled(const std::string& mouse_event) const;
+
+    /**
+     * \brief Checks if this button can generate OnClick events when a specific mouse event occurs over the button.
+     * \param button_id The mouse button for which to check
+     * \param button_event The mouse button event for which to check
+     * \return 'true' if this button can generate OnClick events from this mouse event
+     * \see enable_button_clicks()
+     */
+    bool is_button_clicks_enabled(
+        input::mouse_button button_id, input::mouse_button_event button_event) const;
+
     /// Registers this region class to the provided Lua state
     static void register_on_lua(sol::state& lua);
 
@@ -354,6 +471,11 @@ class button : public frame {
     void parse_attributes_(const layout_node& node) override;
     void parse_all_nodes_before_children_(const layout_node& node) override;
 
+    bool is_button_clicks_enabled_(input::mouse_button button_id) const;
+
+    virtual void click_(
+        input::mouse_button button_id, input::mouse_button_event button_event, float mx, float my);
+
     const std::vector<std::string>& get_type_list_() const override;
 
     state state_               = state::up;
@@ -373,6 +495,8 @@ class button : public frame {
     utils::observer_ptr<font_string> current_font_string_ = nullptr;
 
     vector2f pushed_text_offset_ = vector2f::zero;
+
+    std::set<std::string> reg_click_list_;
 };
 
 } // namespace lxgui::gui

include/lxgui/gui_frame.hpp

@@ -133,6 +133,7 @@ using script_list_view = script_signal::slot_list_view;
  *
  * - `OnChar`: Triggered whenever a character is typed and the frame has focus
  * (see @ref frame::set_focus).
+ * - `OnDoubleClick`: Triggered when the frame is double-clicked.
  * - `OnDragStart`: Triggered when one of the mouse button registered for
  * dragging (see frame::enable_drag) has been pressed inside the
  * area of the screen occupied by the frame, and a mouse movement is first
@@ -200,9 +201,10 @@ using script_list_view = script_signal::slot_list_view;
  * last call to `OnMouseMove` (or since the last position before the mouse
  * entered this frame), and the mouse X and Y position.
  * - `OnMouseUp`: Similar to `OnMouseDown`, but triggered when the mouse button
- * is released. This event provides one extra argument compared to `OnMouseDown`:
+ * is released. This event provides two extra argument compared to `OnMouseDown`:
  * a boolean flag indicating whether the mouse was released after a drag
- * operation (true) or not (false).
+ * operation (true) or not (false), and another boolean flag indicating whether
+ * the mouse button was initially pressed on this frame (true) or not (false).
  * - `OnMouseWheel`: Triggered when the mouse wheel is moved and this frame is
  * the topmost mouse-wheel-enabled frame under the mouse pointer. Will not
  * trigger if the frame is hidden. This event provides three arguments to the
@@ -557,7 +559,6 @@ class frame : public region {
 
     /**
      * \brief Marks this frame as unable to receive keyboard input from any key.
-     * \param key_name The key to capture
      * \see enable_key_capture()
      * \see is_key_capture_enabled()
      * \see set_keyboard_enabled()

include/lxgui/gui_root.hpp

@@ -49,10 +49,10 @@ class root :
     ~root() override;
 
     // Non-copiable, non-movable
-    root(const root&) = delete;
-    root(root&&)      = delete;
+    root(const root&)            = delete;
+    root(root&&)                 = delete;
     root& operator=(const root&) = delete;
-    root& operator=(root&&) = delete;
+    root& operator=(root&&)      = delete;
 
     /**
      * \brief Returns the width and height of this renderer's main render target (e.g., screen).
@@ -327,8 +327,9 @@ class root :
     std::vector<utils::scoped_connection> connections_;
 
     // Mouse IO
-    utils::observer_ptr<frame> hovered_frame_ = nullptr;
-    utils::observer_ptr<frame> dragged_frame_ = nullptr;
+    utils::observer_ptr<frame> hovered_frame_     = nullptr;
+    utils::observer_ptr<frame> dragged_frame_     = nullptr;
+    utils::observer_ptr<frame> start_click_frame_ = nullptr;
 
     utils::observer_ptr<region> moved_object_ = nullptr;
     utils::observer_ptr<region> sized_object_ = nullptr;

include/lxgui/input_keys.hpp

@@ -4,12 +4,15 @@
 #include "lxgui/lxgui.hpp"
 
 #include <cstdint>
+#include <optional>
 #include <string_view>
 
 namespace lxgui::input {
 
 enum class mouse_button : std::uint8_t { left = 0, right, middle };
 
+enum class mouse_button_event : std::uint8_t { up = 0, down = 1, double_click = 2 };
+
 enum class key : std::uint8_t {
     k_unassigned   = 0x00,
     k_escape       = 0x01,
@@ -162,6 +165,7 @@ enum class key : std::uint8_t {
 /**
  * \brief Returns a standard English name for the provided mouse button.
  * \param button_id The ID code of the mouse button
+ * \return The corresponding code name in English
  * \note This will return a standard English button name, e.g., "LeftButton" for the left mouse
  * button. This can be used for string-based key identification in scripts, where key
  * integer codes would be less usable, or for displaying debug or error messages.
@@ -177,6 +181,45 @@ std::string_view get_mouse_button_codename(mouse_button button_id);
  */
 std::string_view get_localizable_mouse_button_name(mouse_button button_id);
 
+/**
+ * \brief Returns a standard English name for the provided mouse button event.
+ * \param button_event The ID code of the mouse button event
+ * \return The corresponding code name in English
+ * \note This will return a standard English button name, e.g., "Up" for the mouse up event.
+ * This can be used for string-based key identification in scripts, where key
+ * integer codes would be less usable, or for displaying debug or error messages.
+ */
+std::string_view get_mouse_button_event_codename(mouse_button_event button_event);
+
+/**
+ * \brief Returns the localizable name of the provided mouse button event.
+ * \param button_event The ID code of the mouse button event
+ * \return The localizable name of the provided mouse button event
+ * \note This will return localizable button names, e.g., "{mouse_event_up}" for the mouse up event.
+ * Use a @ref lxgui::gui::localizer to transform this into a user-friendly name.
+ */
+std::string_view get_localizable_mouse_button_event_name(mouse_button_event button_event);
+
+/**
+ * \brief Returns a standard Engilsh name for the provided mouse button and event.
+ * \param button_id The ID code of the mouse button
+ * \param button_event The ID code of the mouse button event
+ * \return The corresponding code name in English
+ * \note This will return a string with the format "<button>:<event>".
+ * \see get_mouse_button_codename()
+ * \see get_mouse_button_event_codename()
+ */
+std::string_view
+get_mouse_button_and_event_codename(mouse_button button_id, mouse_button_event button_event);
+
+/**
+ * \brief Returns a mouse button and a button event ID from a string formatted as "<button>:<event>".
+ * \param event_name The name of the mouse button event, as "<button>:<event>"
+ * \return The pair of decoded button and event ID, or std::nullopt if parsing failed.
+ */
+std::optional<std::pair<mouse_button, mouse_button_event>>
+get_mouse_button_and_event_from_codename(std::string_view button_and_event_name);
+
 /**
  * \brief Returns a standard English name for the provided key.
  * \param key_id The key