mouse class documentation enhancements and clarifications

[daluu]

Looking over current docs:

Issue/Item 1:

mouse.toggle(down, button=LEFT_BUTTON)
Holds down or releases the given mouse button in the current position. button can be LEFT_BUTTON, RIGHT_BUTTON, or CENTER_BUTTON. If no button is given, the left button is defaulted to.

Clarification to make: down should be a boolean, True = hold down, False = release up, based on similar doc for

key.toggle(key, down_or_up, [modifiers])
Holds down the given key or keycode if down_or_up is True, or releases it if not. Integer keycodes and modifiers should be taken from module constants (e.g., key.K_DELETE or key.MOD_META). If the given key is a character, it is automatically converted to a keycode corresponding to the current keyboard layout.

Issue/Item 2:

mouse.move(x, y) VS mouse.smooth_move(x, y)

There is some mention of this on the intro/tutorial readme page but not so much on the API docs page. May want to standardize the docs on both to say the same thing to the user to cause less confusion, for novices, etc.

Basically what I suggest to document is that for typical GUI automation (driving an app to do stuff or to test an app), one should use mouse.smooth_move() as it most realistically simulates a user mouse movement, and if mouse.move() doesn't seem to work, use smooth_move().

I say this because I prefer using most optimal/efficient method for (test) automation, but in a simple test using AutoPy to drive HTML5 drag & drop (http://html5demos.com/drag), when I have the coordinates of the source and target locations to perform it at, mouse.move() didn't work, or was too fast to trigger an OS/browser response for the drag & drop. Using smooth_move() worked nicely. On the otherhand, mouse.move() works fine if one does something like a right-click at a location, when I was debugging the issue.