diff --git a/src/main/kotlin/Doer.kt b/src/main/kotlin/Doer.kt index 0f2360c..d81249e 100644 --- a/src/main/kotlin/Doer.kt +++ b/src/main/kotlin/Doer.kt @@ -5,14 +5,61 @@ import java.awt.event.InputEvent import java.util.concurrent.TimeUnit import kotlin.random.Random +/** + * Class providing methods for programmatic control of mouse and keyboard. + * + * This uses a Robot instance to facilitate actions like mouse movements, + * clicks, scrolls, and key presses. + * + * It contains utility methods to perform actions in a human-like way, + * including random pacing and wiggle to avoid robotic movement. + * + * Typical usage: + * + * ``` + * val doer = Doer() + * doer.mouseMove(Point(100, 200)) + * doer.click(InputEvent.BUTTON1_DOWN_MASK) + * ``` + */ class Doer { + + /** + * The Robot instance used to perform mouse and keyboard actions. + */ private val robot = Robot() companion object { - // The mouse button mask for a left click - const val LeftClick = InputEvent.BUTTON1_DOWN_MASK - // The duration in ms of one "tick" used for pacing actions + + /** + * Mouse button mask for a left mouse click. + * + * This stores the button mask value from [InputEvent] that represents a left mouse click. + * + * It can be passed to [click] or other methods that expect a mouse button value. + */ + private const val LEFT_CLICK = InputEvent.BUTTON1_DOWN_MASK + + /** + * The duration in milliseconds of one "tick". + * + * This defines the concept of a "tick" as a unit of time used for pacing actions. + * + * It is used in methods like [sleepForNTicks] to calculate sleep durations + * based on multiplying a number of ticks by this value. + * + * For example, 5 ticks with this value would be 5 * 600 = 3000ms sleep duration. + */ const val TICK_DURATION_MS = 600L - // Extra padding in ms added before actions to account for latency + + /** + * Extra padding in milliseconds added before actions to account for latency. + * + * This defines an extra duration in milliseconds that is added to sleeps + * and waits. + * + * It is to account for latency in the system before actions like mouse moves + * and clicks actually take effect. + */ const val LATENCY_PADDING_MS = 500L } @@ -79,7 +126,7 @@ class Doer { * Moves the mouse to a point, left clicks, and sleeps. * * This moves the mouse to the given [Point] p, sleeps for 100ms ± 50ms, - * left clicks using [LeftClick], and then sleeps for the given duration + * left clicks using [LEFT_CLICK], and then sleeps for the given duration * dur ± durRange. * * @param p The [Point] to move the mouse to. @@ -89,7 +136,7 @@ class Doer { fun moveMouseLeftClickAndSleep(p: Point, dur: Long, durRange: Long) { mouseMove(p) sleep(100, 50) - click(LeftClick) + click(LEFT_CLICK) sleep(dur, durRange) }