andrek25/auto_click

Provide several Ruby methods for simulating mouse click, cursor movement and keystrokes in Windows. This gem use DL library and SendInput method so there is no dependency on FFI, AutoIt or Win32-api. (More control over mouse movement such as speed or locus will be implemented in future releases)

AutoClick¶ ↑

Smulating mouse click, cursor movement and keystrokes

Install¶ ↑

To install auto_click:

gem install auto_click

Basic Usage¶ ↑

Using auto_click is easy. To use the methods provided by auto_click. You need to require it.

require 'auto_click'

To move the mouse cursor to 50,50 ( the top left corner is 0,0) and perform a double left click:

mouse_move(50,50)
double_click

To move the mouse cursor to 50,50 and perform a right click:

mouse_move(50,50)
right_click

To scroll up (forward) 10 wheel steps:

mouse_scroll(10)

To scroll down (backward) 5 wheel steps:

mouse_scroll(-5)

To get the current cursor position

cursor_position

To drag the icon on (50,50) to (200,300):

left_drag(50,50,200,300)

Suppose the notepad window on the top left corner of the screen, to type “Auto Click” in notepad. (Methods like get_windows(“notepad”) will be implemented in future release. So that you do not need to use this left click things to get focus on the notepad window.…..in later release.…..)

mouse_move(100,100)
leftclick
type('Auto Click!')

The type method will Send keystroke for every characters of the string. It will ensure that the capslock is off and hold shift when it is typing a capital character or a character that need shift down (e.g. ‘!’). Notice that you need to escape the character \ and ‘ in single quote string, and you need to escape \ “ and # in double quote string. For example, to type #”\ , you can either do:

type('#\'\'\\')

or

type("\#''\\")

Advanced Usage¶ ↑

The methods shown in Basic Usage are convenient, but sometimes you may need more control on your mouse actions and key strokes.

To show the current cursor x and y position in pixels:

puts cursor_position[0]
puts cursor_position[1]

To move the mouse cursor downward 300 pixels

mouse_move(cursor_position[0]+300,cursor_position[1])

Yes this is not very efficient but mouse_move_relative methods will be implemented in later releases.

If you wish to left click and hold:

mouse_down(:left)

And remember to release the button later:

mouse_up(:left)

To perform a double_click, instead of using:

double_click

You can use two click calls:

left_click
left_click

And of course if for some reasons you need double middle mouse click, you can:

middle_click
middle_click

For get more refined control to key strokes simulation, you can use the method key_stroke, key_up and key_down methods

To send keystroke ‘a’:

key_stroke('a')

To send keystroke tab:

key_stroke('tab')

Therefore, to type “Auto Click!” , you can either use the simple type method stated basic usage section, or you can do:

key_down('shift')        
key_stroke('a')  
key_up('shift')
key_stroke('u')
key_stroke('t')
key_stroke('o')
key_stroke('space')
key_down('shift')
key_stroke('c')
key_up('shift')
key_stroke('l')
key_stroke('i')
key_stroke('c')
key_stroke('k')
key_down('shift')
key_stroke('num1')
key_up('shift')

And you can have detail adjustments to the keyboard behaviour that you need.

Notice that ‘a’ means the key ‘a’ instead of the letter ‘a’. Therefore key_stroke(‘a’) and key_stroke(‘A’) are basically the same. If the capslock is off but you want to type the capitalized A, you need to:

key_down('shift')        
key_stroke('a')  
key_up('shift')

A list of key stroke names will be included in the readme later. ‘a’ to ‘z’, ‘num0’ to ‘num9’, ‘f1’ to ‘f12’, ‘shift’ ‘ctrl’ ‘alt’ ‘win’ ‘tab’ ‘del’ ‘ins’ ‘return’ ‘esc’ ‘pageup’ ‘pagedown’ ‘left’ ‘right’ ‘up’ ‘down’ ‘equal’ ‘hyphen’.…..etc are all acceptable key names. I am trying to cater a certain number of name variations, for example:

key_stroke('left') 
key_stroke('leftarrow')
key_stroke('leftkey')

will do the same thing.

If you know the virtual key code you can directly enter the key code, for example:

key_stroke(0x41)

is the same as

key_stroke('a')

The list of virtual key codes can be found at msdn.microsoft.com/en-us/library/dd375731(v=vs.85).aspx

There are some methods which are not discussed here. Please see the following Method List for all the available methods.

Method List¶ ↑

• left_click

• right_click

• middle_click

• double_click

• mouse_down(button_name)

• mouse_up(button_name)

• cursor_position

• mouse_move(x,y)

• mouse_scroll(step)

• left_drag(x_start,y_start,x_end,y_end)

• right_drag(x_start,y_start,x_end,y_end)

• type(string)

• key_stroke(key_name)

• key_down(key_name)

• key_up(key_name)

To Do List¶ ↑

• Add options of movement speed of mouse so the cursor is actually “moving” instead of just show up at the destination instantly

• GetWindow and GetWindowFocus Method

• Refactor the ugly type(string) method

• More effective way to move mouse relative to current position

Change log ¶ ↑

(for full change log please refer to the CHANGELOG file in the repository)

• 0.1.15 Add more general mouse control methods: mouse_down(button_name), mouse_up(button_name)

• 0.1.14 Add middle_click and double_click

• 0.1.12 Super ugly implementation of the method type (need refactoring or even rewite later)

• 0.1.10 Implement get_key_state method. Refine the key_stroke, key_down and key_up method

• 0.1.9 Add support for keybaord region specific keys using US-keyboard standard

• 0.1.8 Implement key_stroke, key_down and key_up

• 0.1.7 Primitive implementation of key_stroke. Need good api before putting it into method list

• 0.1.4 Implement left_drag and right_drag

Tested with¶ ↑

• Ruby 1.9.1-p430, Windows 7

• Ruby 1.9.2-p0, Windows 7

• Ruby 1.9.2-p136, Windows 7

License¶ ↑

MIT license

Copyright © 2010-2011 by Tom Lam

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.