Merge pull request #83 from SLM-Audio/syl/mouse-manipulation

Add cursor manipulation functions

Author: MeijisIrlnd

include/mostly_harmless/CMakeLists.txt

@@ -19,6 +19,7 @@ set(MOSTLYHARMLESS_HEADERS
         ${CMAKE_CURRENT_SOURCE_DIR}/mostlyharmless_Parameters.h
         ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_WebviewBase.h
         ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_WebviewEditor.h
+        ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_Cursor.h
         ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_Colour.h
         ${CMAKE_CURRENT_SOURCE_DIR}/utils/mostlyharmless_TaskThread.h
         ${CMAKE_CURRENT_SOURCE_DIR}/utils/mostlyharmless_Timer.h

include/mostly_harmless/gui/mostlyharmless_Cursor.h

@@ -0,0 +1,29 @@
+//
+// Created by Syl Morrison on 17/01/2026.
+//
+
+#ifndef MOSTLYHARMLESS_CURSOR_H
+#define MOSTLYHARMLESS_CURSOR_H
+#include <cstdint>
+namespace mostly_harmless::gui::cursor {
+    /**
+     * Shows or hides the cursor
+     * @param show Whether the cursor should be shown or hidden.
+     */
+    auto setCursorState(bool show) -> void;
+
+    /**
+     * Retrieves the screen x & y for the cursor, and stores the results in x and y.
+     * @param x A pointer to a var to store the cursor's x position in.
+     * @param y A pointer to a var to store the cursor's y position in.
+     */
+    auto getCursorPosition(std::uint32_t* x, std::uint32_t* y) -> void;
+
+    /**
+     * Sets the cursor's position to the specified (screen) x & y coords.
+     * @param x The new x position for the cursor (in screen bounds).
+     * @param y The new y position for the cursor (in screen bounds).
+     */
+    auto setCursorPosition(std::uint32_t x, std::uint32_t y) -> void;
+} // namespace mostly_harmless::gui::cursor
+#endif // MOSTLYHARMLESS_CURSOR_H

include/mostly_harmless/gui/mostlyharmless_WebviewEditor.h

@@ -22,7 +22,7 @@ namespace mostly_harmless::gui {
      *
      * To use it, you'll probably want to still subclass it, but the boilerplate will be fairly minimal. See WebviewBase for more fine grained details.
      *
-     * The default implementation establishes bindings to 3 javascript functions, pertaining to parameter updates. These are:
+     * The default implementation establishes bindings to several javascript functions. Firstly the ones pertaining to parameter updates:
      * `beginParamGesture()`, `setParamValue()`, and `endParamGesture()`. \n
      * Each of these functions take an object as an arg, expected to be formatted as json containing the paramId to affect, and the value to set.
      * For example:
@@ -41,6 +41,18 @@ namespace mostly_harmless::gui {
      * The default implementation will attempt to parse the args (and assert fail if it failed),
      * and then enqueue the param changes to the guiToProcQueue, for the host and audio side to pick up.
      *
+     * For what I've been calling "ouroborosing" the cursor position, and generally providing the facilities to hide the cursor, snap back to original mouse down position on a drag etc, we also provide some extra helpers here.
+     * `beginScopedCursorMoveGesture()` caches the mouse down position at the time of calling, and hides the cursor.
+     * `endScopedCursorMoveGesture()` restores the cached cursor position, and shows the cursor. These functions should be called as a pair,
+     * for a slider in mouseDown / mouseUp for example.
+     *
+     * `resetCursorPosition()` does much the same as `endScopedCursorMoveGesture()`, except it doesn't zero any of the internally cached variables, and doesn't show the cursor.
+     * The use case is quite different, and is for forcing the cursor to be within a given area - this allows for "infinite drag", or "ouroborosing" without the cursor hitting the screen edges.
+     * If `resetCursorPosition()` is used, then to avoid unexpected jumps, use `tickCursorMove()`, and use its return value instead of the js side `event.movementY` variable.
+     * It updates the internal cache of the last mouse position, and then returns the difference between the old and new values. Call it every time `mousemove` is called for example.
+     * `clearPreviousCursorPosition()` in this paradigm should be called on mouseUp, and simply nulls the last mouse position stored in the cache, preparing it for a new gesture.
+     *
+     *
      *
      * The structure of an event in the default implementation is:
      *
@@ -158,6 +170,11 @@ namespace mostly_harmless::gui {
         virtual choc::value::Value endParamChangeGestureCallback(const choc::value::ValueView& args);
 
         core::ISharedState* m_sharedState{ nullptr };
+
+        struct {
+            std::optional<std::pair<std::uint32_t, std::uint32_t>> lastMouseDownLocation{};
+            std::optional<std::pair<std::uint32_t, std::uint32_t>> lastMousePosition{};
+        } m_cursorState;
     };
 } // namespace mostly_harmless::gui
 #endif // MOSTLYHARMLESS_MOSTLYHARMLESS_WEBVIEWEDITOR_H

include/mostly_harmless/gui/platform/mostlyharmless_GuiHelpersMacOS.h

@@ -4,6 +4,7 @@
 
 #ifndef MOSTLYHARMLESS_MOSTLYHARMLESS_GUIHELPERSMACOS_H
 #define MOSTLYHARMLESS_MOSTLYHARMLESS_GUIHELPERSMACOS_H
+#include <mostly_harmless/gui/mostlyharmless_Cursor.h>
 #include <mostly_harmless/gui/mostlyharmless_Colour.h>
 #include <cstdint>
 namespace mostly_harmless::gui::helpers::macos {
@@ -43,5 +44,32 @@ namespace mostly_harmless::gui::helpers::macos {
      * \param viewHandle A void* to the NSView to set hidden.
      */
     void hideView(void* viewHandle);
+
+    /**
+     * Retrieves the current mouse position in screen coords, and stores them in `x` and `y`.
+     * @param x A pointer to your x variable - the result will be written here.
+     * @param y A pointer to your y variable - the result will be written here.
+     */
+    void getMousePos(std::uint32_t* x, std::uint32_t* y);
+
+    /**
+     * Sets the mouse position to the provided position (in screen coords).
+     * Internally handles translating from screen coords to global space coords.
+     * @param newX The x position to set the mouse position to (in screen space).
+     * @param newY The y position to set the mouse position to (in screen space).
+     */
+    void setMousePos(std::uint32_t newX, std::uint32_t newY);
+
+    /**
+     * Shows (or more accurately, "unhides") the cursor.
+     */
+    void showCursor();
+
+    /**
+     * Hides the cursor.
+     */
+    void hideCursor();
+
+
 } // namespace mostly_harmless::gui::helpers::macos
 #endif // MOSTLYHARMLESS_MOSTLYHARMLESS_GUIHELPERSMACOS_H

source/CMakeLists.txt

@@ -26,6 +26,7 @@ set(MOSTLYHARMLESS_SOURCES
         ${CMAKE_CURRENT_SOURCE_DIR}/events/mostlyharmless_MidiEvent.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_WebviewBase.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_WebviewEditor.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_Cursor.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/gui/mostlyharmless_Colour.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/utils/mostlyharmless_TaskThread.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/utils/mostlyharmless_Timer.cpp

source/gui/mostlyharmless_Cursor.cpp

@@ -0,0 +1,50 @@
+//
+// Created by Syl Morrison on 17/01/2026.
+//
+
+#if defined(MOSTLY_HARMLESS_WINDOWS)
+#include <Windows.h>
+#elif defined(MOSTLY_HARMLESS_MACOS)
+#include <mostly_harmless/gui/platform/mostlyharmless_GuiHelpersMacOS.h>
+#endif
+#include <mostly_harmless/gui/mostlyharmless_Cursor.h>
+namespace mostly_harmless::gui::cursor {
+#if defined(MOSTLY_HARMLESS_WINDOWS)
+    auto setCursorState(bool show) -> void {
+        ::ShowCursor(show ? SW_SHOW : SW_HIDE);
+    }
+
+    auto getCursorPosition(std::uint32_t* x, std::uint32_t* y) -> void {
+        ::POINT cursorPos;
+        ::GetCursorPos(&cursorPos);
+        *x = static_cast<std::uint32_t>(cursorPos.x);
+        *y = static_cast<std::uint32_t>(cursorPos.y);
+    }
+
+    auto setCursorPosition(std::uint32_t x, std::uint32_t y) -> void {
+        ::SetCursorPos(static_cast<::LONG>(x), static_cast<::LONG>(y));
+    }
+
+#elif defined(MOSTLY_HARMLESS_MACOS)
+    auto setCursorState(bool show) -> void {
+        if (show) {
+            gui::helpers::macos::showCursor();
+        } else {
+            gui::helpers::macos::hideCursor();
+        }
+    }
+
+    auto getCursorPosition(std::uint32_t* x, std::uint32_t* y) -> void {
+        gui::helpers::macos::getMousePos(x, y);
+    }
+
+    auto setCursorPosition(std::uint32_t x, std::uint32_t y) -> void {
+        gui::helpers::macos::setMousePos(x, y);
+    }
+
+#else
+    static_assert(false);
+#endif
+
+
+} // namespace mostly_harmless::gui::cursor

source/gui/mostlyharmless_WebviewBase.cpp

@@ -280,5 +280,4 @@ namespace mostly_harmless::gui {
         m_impl->hide();
     }
 
-
 } // namespace mostly_harmless::gui

source/gui/mostlyharmless_WebviewEditor.cpp

@@ -1,18 +1,20 @@
 //
 // Created by Syl Morrison on 11/08/2024.
 //
-#include <choc/gui/choc_DesktopWindow.h>
-#include <choc/gui/choc_WebView.h>
 #include <mostly_harmless/gui/mostlyharmless_WebviewEditor.h>
+#include "mostly_harmless/utils/mostlyharmless_OnScopeExit.h"
 #include <mostly_harmless/utils/mostlyharmless_Macros.h>
 #if defined(MOSTLY_HARMLESS_MACOS)
 #include <mostly_harmless/gui/platform/mostlyharmless_GuiHelpersMacOS.h>
 #elif defined(MOSTLY_HARMLESS_WINDOWS)
 #include <windef.h>
 #include <winuser.h>
 #endif
+#include <choc/gui/choc_DesktopWindow.h>
+#include <choc/gui/choc_WebView.h>
 #include <cassert>
 #include <filesystem>
+#include <mostly_harmless/gui/mostlyharmless_Cursor.h>
 namespace mostly_harmless::gui {
 
     WebviewEditor::WebviewEditor(core::ISharedState* sharedState, std::uint32_t initialWidth, std::uint32_t initialHeight, Colour backgroundColour) : WebviewBase(initialWidth,
@@ -23,6 +25,7 @@ namespace mostly_harmless::gui {
 
     void WebviewEditor::initialise() {
         WebviewBase::initialise();
+
         auto beginParamGestureCallback_ = [this](const choc::value::ValueView& args) -> choc::value::Value {
             return beginParamChangeGestureCallback(args);
         };
@@ -34,9 +37,60 @@ namespace mostly_harmless::gui {
         auto endParamGestureCallback_ = [this](const choc::value::ValueView& args) -> choc::value::Value {
             return endParamChangeGestureCallback(args);
         };
+
+        auto beginScopedCursorMoveGestureCallback_ = [this](const choc::value::ValueView& args) -> choc::value::Value {
+            std::uint32_t x, y;
+            cursor::getCursorPosition(&x, &y);
+            m_cursorState.lastMouseDownLocation = std::make_pair(x, y);
+            cursor::setCursorState(false);
+            return {};
+        };
+
+        auto endScopedCursorMoveGestureCallback_ = [this](const choc::value::ValueView& args) -> choc::value::Value {
+            mostly_harmless::utils::OnScopeExit se{ [this]() -> void {
+                cursor::setCursorState(true);
+            } };
+            if (!m_cursorState.lastMouseDownLocation) {
+                return {};
+            }
+            const auto [x, y] = *m_cursorState.lastMouseDownLocation;
+            cursor::setCursorPosition(x, y);
+            m_cursorState.lastMouseDownLocation = {};
+            return {};
+        };
+
+        auto resetCursorPositionCallback_ = [this](const choc::value::ValueView& args) -> choc::value::Value {
+            const auto [x, y] = m_cursorState.lastMouseDownLocation.value_or(std::make_pair(0, 0));
+            mostly_harmless::gui::cursor::setCursorPosition(x, y);
+            m_cursorState.lastMousePosition = std::make_pair(x, y);
+            return {};
+        };
+
+        auto tickCursorMoveCallback_ = [this](const choc::value::ValueView& args) -> choc::value::Value {
+            const auto lastMouseDownLocation = m_cursorState.lastMouseDownLocation.value_or(std::make_pair(0, 0));
+            const auto [prevX, prevY] = m_cursorState.lastMousePosition.value_or(lastMouseDownLocation);
+            std::uint32_t x, y;
+            mostly_harmless::gui::cursor::getCursorPosition(&x, &y);
+            m_cursorState.lastMousePosition = std::make_pair(x, y);
+            const auto deltaX = static_cast<std::int32_t>(x) - static_cast<std::int32_t>(prevX);
+            const auto deltaY = static_cast<std::int32_t>(y) - static_cast<std::int32_t>(prevY);
+            const auto res = choc::json::create("x", deltaX, "y", deltaY);
+            return res;
+        };
+
+        auto clearPreviousCursorPositionCallback_ = [this](const choc::value::ValueView& args) -> choc::value::Value {
+            m_cursorState.lastMousePosition = {};
+            return {};
+        };
+
         m_internalWebview->bind("beginParamGesture", std::move(beginParamGestureCallback_));
         m_internalWebview->bind("setParamValue", std::move(paramChangeCallback_));
         m_internalWebview->bind("endParamGesture", std::move(endParamGestureCallback_));
+        m_internalWebview->bind("beginScopedCursorMoveGesture", std::move(beginScopedCursorMoveGestureCallback_));
+        m_internalWebview->bind("endScopedCursorMoveGesture", std::move(endScopedCursorMoveGestureCallback_));
+        m_internalWebview->bind("resetCursorPosition", std::move(resetCursorPositionCallback_));
+        m_internalWebview->bind("tickCursorMove", std::move(tickCursorMoveCallback_));
+        m_internalWebview->bind("clearPreviousCursorPosition", std::move(clearPreviousCursorPositionCallback_));
     }
 
     bool WebviewEditor::allowResize() const noexcept {

source/gui/platform/mostlyharmless_GuiHelpersMacOS.mm

@@ -68,4 +68,30 @@ void hideView(void* viewHandle) {
         auto* asView = static_cast<NSView*>(viewHandle);
         asView.hidden = true;
     }
+
+    void getMousePos(std::uint32_t* x, std::uint32_t* y) {
+        const auto mouseLocation = [NSEvent mouseLocation];
+        *x = static_cast<std::uint32_t>(mouseLocation.x);
+        *y = static_cast<std::uint32_t>(mouseLocation.y);
+    }
+
+    void setMousePos(std::uint32_t newX, std::uint32_t newY) {
+        const auto frame = [[NSScreen mainScreen] frame];
+        const auto h = frame.size.height;
+        const auto translatedY = h - newY;
+        const auto pt = CGPointMake(newX, translatedY);
+        // Note that while this doesn't generate an event, its delta will be added to the next mouse event that *does* generate an event - so in effect, this can cause a massive fucking jump -
+        // If you can intercept the next event, this is workaroundable - see WebviewEditor's ouroboros stuff
+        CGWarpMouseCursorPosition(pt);
+        CGAssociateMouseAndMouseCursorPosition(true);
+    }
+
+    void showCursor() {
+        [NSCursor unhide];
+    }
+
+    void hideCursor() {
+        [NSCursor hide];
+    }
+
 } // namespace mostly_harmless::gui::helpers::macos