From a9b18e4e137da34650ca20b4150f9390754792b2 Mon Sep 17 00:00:00 2001 From: dtookey Date: Sun, 6 Aug 2023 21:15:15 -0400 Subject: [PATCH] included usage examples in Controllers.kt --- src/main/kotlin/Controllers.kt | 116 ++++++++++++++++++++++++++------- 1 file changed, 92 insertions(+), 24 deletions(-) diff --git a/src/main/kotlin/Controllers.kt b/src/main/kotlin/Controllers.kt index a239af3..5dc12f3 100644 --- a/src/main/kotlin/Controllers.kt +++ b/src/main/kotlin/Controllers.kt @@ -41,7 +41,7 @@ interface InputController { fun keyPress(keyCode: Int) /** - * Performs a scroll in motion. + * Performs a mousewheel scroll in motion. * * This will move the scroll wheel forward by the number of ticks * over the duration. It will sleep for short intervals between @@ -53,7 +53,7 @@ interface InputController { fun scrollIn(sleepDur: Long, sleepDurVariance: Long) /** - * Performs a scroll out motion. + * Performs a mousewheel scroll out motion. * * Same as [scrollIn] but moves the scroll wheel backward. */ @@ -106,6 +106,16 @@ interface TemporalController { * For example, if a target destination point is (100, 200), the wiggle params * might generate an actual movement point like (102, 198) to add some randomness. * + * Usage: + * + * ``` + * val controller = DesktopController() + * val wiggle = WiggleParams(xWiggle = 10, yWiggle = 15) + * + * val target = Point(100, 200) + * val actual = controller.getAlmostPoint(target, wiggle) // (104, 197) + * ``` + * * @param xWiggle The max amount of variance in x direction. Default 25. * @param yWiggle The max amount of variance in y direction. Default 25. */ @@ -205,28 +215,46 @@ interface Automaton : DesktopController, InputController, TemporalController * RobotController aims to provide a simple and easy to use API for * automating desktop interactions and workflows. * + * Usage example: + * + * ``` + * val robot = RobotController() + * + * // Move mouse to 100, 200 + * robot.mouseMove(Point(100, 200)) + * + * // Left click at current position + * robot.click(InputEvent.BUTTON1_MASK) + * + * // Press A key + * robot.keyPress(KeyEvent.VK_A) + * ``` + * * @param robot The Robot instance to use. A default is created if not provided. */ open class RobotController(private val robot: Robot = Robot()) : Automaton { /** - * Moves the mouse cursor to the given [Point]. + * Moves the mouse cursor to the given [Point] destination. * - * This uses the Robot [mouseMove] method to move the mouse cursor - * to the x and y coordinates specified by the provided [Point] p. + * Uses the Robot [mouseMove] method to move the mouse cursor to the x and y + * coordinates specified by the provided [Point]. * - * Usage: - *``` - * val doer = Doer() + * Adding some random variance to the target [Point] can simulate human-like + * imperfect mouse movements. * - * // Create target point - * val target = Point(100, 200) + * Example usage: * - * // Move mouse to target - * doer.mouseMove(target) - *``` + * ``` + * val robot = RobotController() * + * // Target destination point + * val target = Point(100, 200) * - * @param point The [Point] representing the x and y coordinates to move the mouse to. + * // Move mouse to target + * robot.mouseMove(target) + * ``` + * + * @param destination The [Point] representing the target x and y coordinates. */ override fun moveMouse(point: Point) { robot.mouseMove(point.x, point.y) @@ -240,6 +268,15 @@ open class RobotController(private val robot: Robot = Robot()) : Automaton { * A random sleep is added in between pressing and releasing the button * to add variance and avoid robotic timing. * + * Example usage: + * + * ``` + * val robot = RobotController() + * + * // Perform left click at current mouse position + * robot.click(InputEvent.BUTTON1_MASK) + * ``` + * * @param button The button to click. Must be a valid constant like [InputEvent.BUTTON1_MASK]. * * Returns immediately If button is negative. Button must be a positive integer. @@ -265,29 +302,49 @@ open class RobotController(private val robot: Robot = Robot()) : Automaton { * A random sleep is added after pressing the key before releasing it to add variance * and avoid robotic timing. * - * @param key The key code of the key to press, such as [KeyEvent.VK_A]. + * Example usage: * - * returns immediately if key < 0. This can be useful for skipping actions with a -1 + * ``` + * val robot = RobotController() + * + * // Press the 'A' key + * robot.keyPress(KeyEvent.VK_A) + * ``` + * + * @param keyCode The key code of the key to press, such as [KeyEvent.VK_A]. + * + * Returns immediately if keyCode < 0. This can be useful for skipping actions by passing -1 */ - override fun keyPress(key: Int) { + override fun keyPress(keyCode: Int) { //guardian logic - if (key < 0) { + if (keyCode < 0) { return } - robot.keyPress(key) + robot.keyPress(keyCode) //we add in some random time variance here to appear less robotic sleepWithVariance(8, 8) - robot.keyRelease(key) + robot.keyRelease(keyCode) } /** * Scrolls the mouse wheel down by one unit. * - * Uses the Robot [mouseWheel] method to scroll up and then sleeps - * for a random duration between 16-32ms to pace the scrolling. + * Uses the Robot [mouseWheel] method to scroll down and then sleeps + * for a random duration between 10-20ms to pace the scrolling. + * + * Example usage: + * + * ``` + * val robot = RobotController() + * + * // Scroll down 5 units + * repeat(5) { + * robot.scrollDown() + * } + * ``` */ override fun scrollOut(sleepDur: Long, sleepDurVariance: Long) { robot.mouseWheel(1) @@ -297,8 +354,19 @@ open class RobotController(private val robot: Robot = Robot()) : Automaton { /** * Scrolls the mouse wheel up by one unit. * - * Uses the Robot [mouseWheel] method to scroll up and then sleeps - * for a random duration between 16-32ms to pace the scrolling. + * Uses the Robot [mouseWheel] method to scroll up and then sleeps for a + * random duration between 10-20ms to pace the scrolling. + * + * Example usage: + * + * ``` + * val robot = RobotController() + * + * // Scroll up 10 units + * repeat(10) { + * robot.scrollUp() + * } + * ``` */ override fun scrollIn(sleepDur: Long, sleepDurVariance: Long) { robot.mouseWheel(-1)