Mouse
=====
Methods to interact with the mouse.

----

::

  type EMouseDistribution
~~~~~~~~~~~~~~~~~~~~~~~

The available distributions used to generate a point in a box.


  EMouseDistribution = (
    MOUSE_DISTRIBUTION_DEFAULT, // Use Mouse.Distribution
    MOUSE_DISTRIBUTION_RANDOM,  // Completely random point
    MOUSE_DISTRIBUTION_GAUSS,   // Weighted towards the center
    MOUSE_DISTRIBUTION_SKEWED,  // Weighted torwards current mouse position
    MOUSE_DISTRIBUTION_ROWP     // Weighted torwards current mouse position but more "rounded" compared to MOUSE_DISTRIBUTION_SKEWED
  );

----

::

  type TMouse
~~~~~~~~~~~


  TMouse = record(TSRLBaseRecord)
    Speed: Double;                     // Overall mouse speed (Default: 12)
    Gravity, Wind: Double;             // Gravity & Wind for generating mouse path (Default: 9 & 5)
    Distribution: EMouseDistribution;  // Default distribution to use (Default: MOUSE_DISTRIBUTION_ROWP)
    MissChance: Double;                // Percentage chance to "Miss" the mouse (Default: 10)
    IdleInterval: Double;              // Distance to travel before calling Mouse.Idle() (Default: 0)
    IdleProgress: Double;
    IdleGoal: Double;
    OnMoving: TMouseMovingEvent;       // Callback while mouse is being moved
    OnTeleport: TMouseTeleportEvent;   // Callback when mouse is teleported
  end;

----

Mouse.Setup
~~~~~~~~~~~
::

  procedure TMouse.Setup;

Initializes mouse variables.

.. note:: This is automatically called on the **Mouse** variable.

----

Mouse.Teleport
~~~~~~~~~~~~~~
::

  procedure TMouse.Teleport(X, Y: Int32);

Teleport the mouse to the desired X,Y coordinates.

Example::

  Mouse.Teleport(50, 50);

----

Mouse.Teleport
~~~~~~~~~~~~~~
::

  procedure TMouse.Teleport(P: TPoint);

Teleport the mouse to the desired point.

Example::

  Mouse.Teleport(50, 50);

----

Mouse.Position
~~~~~~~~~~~~~~
::

  function TMouse.Position: TPoint;

Returns the mouse current position.

Example::

  var P: TPoint;

  P := Mouse.Position();

  WriteLn('X: ', P.X);
  WriteLn('Y: ', P.Y);

----

Mouse.Hold
~~~~~~~~~~
::

  procedure TMouse.Hold(Button: Int32);

Holds the desired mouse button down. The button will continue to be held down until `Mouse.Release` is called.

Available buttons:
 - MOUSE_LEFT
 - MOUSE_RIGHT
 - MOUSE_SCROLL
 - MOUSE_EXTRA_1
 - MOUSE_EXTRA_2

Example::

  Mouse.Hold(MOUSE_LEFT); // The mouse is now holding down left click.

----

Mouse.Release
~~~~~~~~~~~~~
::

  procedure TMouse.Release(Button: Int32);

Releases the desired mouse button which has been previously held.

Available buttons:
 - MOUSE_LEFT
 - MOUSE_RIGHT
 - MOUSE_SCROLL
 - MOUSE_EXTRA_1
 - MOUSE_EXTRA_2

Example::

  Mouse.Release(MOUSE_LEFT); // The mouse is no holding left click.

----

Mouse.WindMouse
~~~~~~~~~~~~~~~
::

  procedure TMouse.Release(Button: Int32);

The internal algorithm used by **Mouse.Move** to move the mouse in a human'ish way.

Credit: BenLand100 (https://github.com/BenLand100/SMART/blob/master/src/EventNazi.java#L201)

----

Mouse.Idle
~~~~~~~~~~
::

  procedure TMouse.Idle;

When **IdleInterval** is reached this is called. Override to change behavior.

 - An **IdleInterval** of **1.0** equals to the distance between the top left and bottom right of the client.
 - Assuming the client dimensions are 500,500 the distance between (0,0) and (500,500) is ~700.
   With an **IdleInterval** of **2.0** this would automatically be called every time the mouse has travelled ~1400 pixels.

----

Mouse.Move
~~~~~~~~~~
::

  procedure TMouse.Move(Destination: TPoint);

Moves the mouse to the desired point.

Example::

  var P: TPoint;

  P.X := 50;
  P.Y := 50;

  Mouse.Move(P); // The mouse is now at 50,50

----

Mouse.Move
~~~~~~~~~~
::

  procedure TMouse.Move(P: TPoint);

Moves the mouse to the desired X,Y coordinate.

Example::

  Mouse.Move(50, 50); // The mouse is now at 50,50

----

Mouse.Move
~~~~~~~~~~
::

  procedure TMouse.Move(Center: TPoint; Radius: Int32; ForcedMove: Boolean = False);

Moves the mouse to a random point in an circle defined by **Center** and **Radius**.

- **ForcedMove** determines if the mouse should be moved if already inside the circle. By default this is **False**.

Example::

  Mouse.Move([100, 100], 25); // The mouse is now randomly within 100,100 with a radius of 25.

----

Mouse.Move
~~~~~~~~~~
::

  procedure TMouse.Move(Box: TBox; ForcedMove: Boolean = False; Distribution: EMouseDistribution = MOUSE_DISTRIBUTION_DEFAULT);

Moves the mouse to a random point in the box.

- **ForcedMove** determines if the mouse should be moved if already in the box. By default this is **False**
- **Distribution** determines the method to generate a random point. By default this uses **Mouse.Distribution**

Example::

  var B: TBox;

  B.X1 := 100;
  B.Y1 := 100;
  B.X2 := 200;
  B.Y2 := 200;

  Mouse.Move(B); // The mouse is now randomly within 100,100,200,200

----

Mouse.Move
~~~~~~~~~~
::

  procedure TMouse.Move(Circle: TCircle; ForcedMove: Boolean = False);

Moves the mouse to a random point in an circle.

- **ForcedMove** determines if the mouse should be moved if already in the circle. By default this is **False**.

Example::

  var C: TCircle;

  C.X := 100;
  C.Y := 100;
  C.Radius := 25;

  Mouse.Move(C); // The mouse is now randomly within 100,100 with a radius of 25.

----

Mouse.Move
~~~~~~~~~~
::

  procedure TMouse.Move(Rect: TRectangle; ForcedMove: Boolean = False);

Moves the mouse to a random point in an rectangle.

- **ForcedMove** determines if the mouse should be moved if already in the rectangle. By default this is **False**.

Example::

  var TPA: TPointArray;
  var R: TRectangle;

  R := TPA.MinAreaRect();

  Mouse.Move(R);

----

Mouse.Click
~~~~~~~~~~~
::

  procedure TMouse.Click(Button: Int32);

Clicks the mouse with the desired button at the current mouse position.

Available buttons:
 - MOUSE_LEFT
 - MOUSE_RIGHT
 - MOUSE_SCROLL
 - MOUSE_EXTRA_1
 - MOUSE_EXTRA_2

Example::

  Mouse.Click(MOUSE_LEFT); // Left click the current mouse position

----

Mouse.Click
~~~~~~~~~~~
::

  procedure TMouse.Click(X, Y: Int32; Button: Int32);

Moves the mouse to to X,Y and clicks the desired button.

Available buttons:
 - MOUSE_LEFT
 - MOUSE_RIGHT
 - MOUSE_SCROLL
 - MOUSE_EXTRA_1
 - MOUSE_EXTRA_2

Example::

  Mouse.Click(50, 50, MOUSE_LEFT); // Left click at 50,50

----

Mouse.Click
~~~~~~~~~~~
::

  procedure TMouse.Click(P: TPoint; Button: Int32);

Moves the mouse to P.X,P.Y and click the desired button.

Available buttons:
 - MOUSE_LEFT
 - MOUSE_RIGHT
 - MOUSE_SCROLL
 - MOUSE_EXTRA_1
 - MOUSE_EXTRA_2

Example::

  var P: TPoint;

  P.X := 50;
  P.Y := 50;

  Mouse.Click(P, MOUSE_LEFT); // Left click at 50,50

----

Mouse.Click
~~~~~~~~~~~
TMouse.Click(Circle: TCircle; Button: Int32; ForcedMove: Boolean = False);

Moves the mouse to a random point in an circle defined by **Center** and **Radius** and clicks the desired button.

 - **ForcedMove** determines if the mouse should be moved if already in the circle. By default this is **False**.

Example::

  Mouse.Click([100, 100], 25, MOUSE_LEFT); // Left clicked somewhere nearby 100,100 with a radius of 25.

----

Mouse.Click
~~~~~~~~~~~
::

  procedure TMouse.Click(Box: TBox; Button: Int32; ForcedMove: Boolean = False; Distribution: EMouseDistribution = MOUSE_DISTRIBUTION_DEFAULT);

Moves the mouse to a random point in the box and clicks the desired button.

- **ForcedMove** determines if the mouse should be moved if already in the box. By default this is **False**
- **Distribution** determines the method to generate a random point. By default this uses **Mouse.Distribution**

Available buttons:
 - MOUSE_LEFT
 - MOUSE_RIGHT
 - MOUSE_SCROLL
 - MOUSE_EXTRA_1
 - MOUSE_EXTRA_2

Example::

  var B: TBox;

  B.X1 := 100;
  B.Y1 := 100;
  B.X2 := 200;
  B.Y2 := 200;

  Mouse.Click(B, MOUSE_LEFT); // Left clicked somewhere within 100,100,200,200

----

Mouse.Click
~~~~~~~~~~~
TMouse.Click(Circle: TCircle; Button: Int32; ForcedMove: Boolean = False);

Moves the mouse to a random point in an circle and clicks the desired button.

 - **ForcedMove** determines if the mouse should be moved if already in the circle. By default this is **False**.

Example::

  var C: TCircle;

  C.X := 100;
  C.Y := 100;
  C.Radius := 25;

  Mouse.Click(C, MOUSE_LEFT); // Left clicked somewhere nearby 100,100 with a radius of 25.

----

Mouse.Click
~~~~~~~~~~~
::

  procedure TMouse.Click(Rect: TRectangle; Button: Int32; ForcedMove: Boolean = False);

Moves the mouse to a random point in an rectangle then clicks the desired button.

 - **ForcedMove** determines if the mouse should be moved if already in the rectangle. By default this is **False**.

Example::

  var TPA: TPointArray;
  var R: TRectangle;

  R := TPA.MinAreaRect();

  Mouse.Click(R, MOUSE_LEFT);

----

Mouse.Miss
~~~~~~~~~~
::

  function TMouse.Miss(P: TPoint): TPoint;

"Misses" the destination point **P**. Will stop somewhere along the path or overshoot.
Returns the position the mouse was moved to.

This could automatically be called depending on **Mouse.MissChance**.

----

Mouse.DragTo
~~~~~~~~~~~~
::

  procedure TMouse.DragTo(X, Y: Int32; Button: Int32 = MOUSE_LEFT)

Holds the desired button and moves the mouse to X,Y coordinates.

 - **Button** by default is MOUSE_LEFT.

Example::

  Mouse.DragTo(50, 50); // Moves the mouse to 50,50 while holding MOUSE_LEFT

----

Mouse.DragTo
~~~~~~~~~~~~
::

  procedure TMouse.DragTo(P: TPoint; Button: Int32 = MOUSE_LEFT)

Holds the desired button and moves the mouse to `P` coordinates.

 - **Button** by default is MOUSE_LEFT.

Example::

  var P: TPoint;

  P.X := 50;
  P.Y := 50;

  Mouse.DragTo(P); // Moves the mouse to 50,50 while holding MOUSE_LEFT

----

Mouse.Scroll
~~~~~~~~~~~~
::

  procedure TMouse.Scroll(Amount: Int32; Down: Boolean);

Scrolls the mouse X amount of times at the current mouse position.

Example::

  Mouse.Scroll(5, True);  // Scroll 5 times down
  Mouse.Scroll(5, False); // Scroll 5 times up

----

Mouse.Scroll
~~~~~~~~~~~~
::

  procedure TMouse.Scroll(P: TPoint; Scrolls: Int32; Down: Boolean);

Moves the mouse to desired position `P` then scrolls X amount of times.

Example::

  var P: TPoint;

  P.X := 50;
  P.Y := 50;

  Mouse.Scroll(P, 5, True);  // Scroll 5 times down at 50,50
  Mouse.Scroll(P, 5, False); // Scroll 5 times up at 50,50

----

Mouse.Scroll
~~~~~~~~~~~~
::

  procedure TMouse.Scroll(Box: TBox; Amount: Int32; Down: Boolean);

Moves the mouse to a random point in the box then scrolls X amount of times.

Example::

  var B: TBox;

  B.X1 := 100;
  B.Y1 := 100;
  B.X2 := 200;
  B.Y2 := 200;

  Mouse.Scroll(B, 5, True); // Scroll the mouse down 5 times somewhere within 100,100,200,200
  Mouse.Scroll(B, 5, False); // Scroll the mouse up 5 times somewhere within 100,100,200,200

----

::

  var Mouse
~~~~~~~~~
  Global mouse variable.