tookeyman/Tool-Assisted-RS
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

included usage examples in Controllers.kt

Browse Source
This commit is contained in:
dtookey 2023-08-06 21:15:15 -04:00
parent b8ac295330
commit a9b18e4e13
1 changed files with 92 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
src/main/kotlin/Controllers.kt
View File

@ -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
* Example usage:
*
* ```
* val robot = RobotController()
*
* // Target destination point
* val target = Point(100, 200)
*
* // Move mouse to target
* doer.mouseMove(target)
*```
* robot.mouseMove(target)
* ```
*
*
* @param point The [Point] representing the x and y coordinates to move the mouse to.
* @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)