splash mouse events scripting docs

docs/scripting-ref.rst

@@ -2102,3 +2102,141 @@ Example:
              error("Splash 1.8 or newer required")
          end
      end
+
+.. _splash-mouse-click:
+
+splash:mouse_click
+------------------
+
+Trigger mouse click event in web page.
+
+**Signature:** ``splash:mouse_click(x, y)``
+
+**Parameters:**
+
+* x - integer or float with x position of element to be clicked
+* y - integer or float with y position of element to be clicked
+
+**Returns:** nil
+
+**Async:**: no.
+
+
+.. note::
+
+    Coordinates for mouse events must be relative to web document. Element on which action is performed must be inside viewport (must be visible
+    to the user). If element is outside viewport and user needs to scroll to see it, you must either scroll
+    down with splash or simply set viewport to full with :ref:`splash-set-viewport-full`.
+
+.. note::
+
+    Mouse events are not propagated immediately, to see consequences of click  reflected in page source you must call :ref:`splash-wait`
+
+Example:
+
+.. code-block:: lua
+
+    -- get button element dimensions with javascript and perform mouse click
+
+    function main(splash)
+        assert(splash:go(splash.args.url))
+        get_dimensions = splash:jsfunc([[
+            function () {
+                rect = document.getElementById('button').getBoundingClientRect();
+                return {"x":rect.left, "y": rect.top}
+            }
+        ]])
+        dimensions = get_dimensions()
+        splash:mouse_click(dimensions.x, dimensions.y)
+        -- wait split second to allow event to propagate
+        splash:wait(0.1)
+        return splash:html()
+    end
+
+Example 2:
+
+.. code-block:: lua
+
+    -- click on element outside viewport
+
+    function main(splash)
+        get_dimensions = splash:jsfunc([[
+            function () {
+                rect = document.getElementById('must_scroll_to_see').getBoundingClientRect();
+                return {"x":rect.left, "y": rect.top}
+            }
+        ]])
+        assert(splash:go(splash.args.url))
+        splash:set_viewport_full()
+        dimensions = get_dimensions()
+        splash:mouse_click(dimensions.x, dimensions.y)
+        splash:wait(0.1)
+        return splash:html()
+    end
+
+
+Under the hood ``splash:mouse_click`` simply performs :ref:`splash-mouse-press` followed by :ref:`splash-mouse-release`.
+
+At the moment only left click is supported by Splash. Click with right mouse button or double click is not supported.
+
+
+.. _splash-mouse-hover:
+
+splash:mouse_hover
+------------------
+
+Trigger mouse hover (JavaScript mouseover) event in web page.
+
+**Signature:** ``splash:mouse_hover(x, y)``
+
+**Parameters:**
+
+* x - integer or float with x position of element to be hovered on
+* y - integer or float with y position of element to be hovered on
+
+**Returns:** nil
+
+**Async:**: no.
+
+See notes about mouse events in :ref:`splash-mouse-click`
+
+
+.. _splash-mouse-press:
+
+splash:mouse_press
+------------------
+
+Trigger mouse press event in web page.
+
+**Signature:** ``splash:mouse_press(x, y)``
+
+**Parameters:**
+
+* x - integer or float with x position of element over which mouse button is pressed
+* y - integer or float with y position of element over which mouse button is pressed
+
+**Returns:** nil
+
+**Async:**: no.
+
+See notes about mouse events in :ref:`splash-mouse-click`
+
+.. _splash-mouse-release:
+
+splash:mouse_release
+--------------------
+
+Trigger mouse release event in web page.
+
+**Signature:** ``splash:mouse_release(x, y)``
+
+**Parameters:**
+
+* x - integer or float with x position of element over which mouse button is released
+* y - integer or float with y position of element over which mouse button is released
+
+**Returns:** nil
+
+**Async:**: no.
+
+See notes about mouse events in :ref:`splash-mouse-click`