Module: AutoItX3

Defined in:
lib/AutoItX3/au3.rb,
lib/AutoItX3/misc.rb,
lib/AutoItX3/mouse.rb,
lib/AutoItX3/window.rb,
lib/AutoItX3/control.rb,
lib/AutoItX3/filedir.rb,
lib/AutoItX3/graphic.rb,
lib/AutoItX3/process.rb,
lib/AutoItX3/keyboard.rb

Overview

This file is part of au3. Copyright © 2009 Marvin Gülker

au3 is published under the same terms as Ruby. See www.ruby-lang.org/en/LICENSE.txt

Defined Under Namespace

Classes: AU3_Function, Au3Error, Button, ComboBox, Control, Edit, ListBox, ListView, TabBook, TreeView, Window

Constant Summary collapse

INTDEFAULT =

The smallest value AutoIt can handle. Used for some parameter defaults.

-2147483647
VERSION =

The version of this au3 library.

"0.1.0"
BUFFER_SIZE =

This is the buffer size used for AutoItX3’s text “returning” functions. It will be subtracted by 1 due to the trailing 0 of wchar_t * type strings.

100_000
UNKNOWN_CURSOR =

Unknown cursor icon

0
APP_STARTING_CURSOR =

Application starting cursor (arrow with a hourglass next to it)

1
ARROW_CURSOR =

The normal cursor

2
CROSS_CURSOR =

Cross cursor

3
HELP_CURSOR =

Cursor with a question mark next to it

4
IBEAM_CURSOR =

Cursor for editing lines of text

5
ICON_CURSOR = 
6
NO_CURSOR =

Cursor for forbidden actions (a circle with a strike through it)

7
SIZE_CURSOR = 
8
SIZE_ALL_CURSOR = 
9
SIZE_NESW_CURSOR = 
10
SIZE_NS_CURSOR = 
11
SIZE_NWSE_CURSOR = 
12
SIZE_WE_CURSOR = 
13
UP_ARROW_CURSOR = 
14
WAIT_CURSOR =

Wait (the well-known “hourglass”)

15
IDLE_PRIORITY =

Lowest process priorety

0
SUBNORMAL_PRIORITY =

Subnormal process priority

1
NORMAL_PRIORITY =

Normal process priority

2
SUPNORMAL_PRIORITY =

Process priority above normal

3
HIGH_PRIORITY =

High process priority

4
REALTIME_PRIORITY =

Highest process priority. Use this with caution, it’s is the priority system processes run with.

5
LOGOFF =

Logs the currect user out

0
SHUTDOWN =

Shuts the computer down

1
REBOOT =

Reboot the computer

2
FORCE_CLOSE =

Force hanging applications to close

4
POWER_DOWN =

Turn the power off after shutting down (if the computer supports this)

8

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.options ⇒ Object (readonly)

This hash is used for the #set_option method. Use the #set_option method to configure it.



144
145
146
 
# File 'lib/AutoItX3/au3.rb', line 144

def options
  @options
end

Class Method Details

.add_drive_map(device, remote_share, flags = 0, username = "", password = "") ⇒ Object

Arguments

Every | is ment to be a backslash.

  • device: The device letter to map the drive to, in the form "X:". If this is an asterisk *, the next available letter will be used.

  • remote_share: The address of the network drive, in the form "||Server|Drive" or "||Server|Share".

  • flags (0): A combination (via +) of 1 (PersistantMapping) and 8 (Show authentification dialog if neccessary).

  • username (“”): The username, of the form "username" or "Domain|username".

  • password (“”): The login password.

Description

Maps a network drive and raises an Au3Error if the action is not successful.



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/AutoItX3/filedir.rb', line 21

def add_drive_map(device, remote_share, flags = 0, username = "", password = "")
  @functions[__method__] ||= AU3_Function.new("DriveMapAdd", 'SSLSSPI')
  buffer = " " * BUFFER_SIZE
  buffer.wide!
  @functions[__method__].call(device, remote_share, flags, username, password, buffer, buffer.size - 1)
  
  case last_error
    when 1 then raise(Au3Error, "Unknown error occured while mapping network drive!")
    when 2 then raise(Au3Error, "Access denied!")
    when 3 then raise(Au3Error, "Device '#{device}' is already assigned!")
    when 4 then raise(Au3Error, "Invalid device name '#{device}'!")
    when 5 then raise(Au3Error, "Invalid remote share '#{remote_share}'!")
    when 6 then raise(Au3Error, "The password is incorrect!")
    else return buffer.normal.strip
  end
end

.block_input=(val) ⇒ Object

Blocks user input or enables it (but the user can gain back control by pressing [CTRL] + [ALT] + [DEL]). In older versions of Windows, AutoIt may also be blocked. Does not work with Windows Vista.



15
16
17
18
19
 
# File 'lib/AutoItX3/misc.rb', line 15

def block_input=(val)
  @functions[__method__] ||= AU3_Function.new("BlockInput", 'L')
  @functions[__method__].call(!!val)
  @input_blocked = !!val
end

.cliptext ⇒ Object

Returns the text saved in the clipboard. It will be truncated at the 99,999th character or at a NUL char.



71
72
73
74
75
76
77
 
# File 'lib/AutoItX3/misc.rb', line 71

def cliptext
  @functions[__method__] ||= AU3_Function.new("ClipGet", 'PL')
  cliptext = " " * BUFFER_SIZE
  cliptext.wide!
  @functions[__method__].call(cliptext, cliptext.size - 1)
  cliptext.normal.strip
end

.cliptext=(text) ⇒ Object

Writes text to the Windows clipboard. You can’t write NUL characters to the clipboard, the text will be terminated.



63
64
65
66
67
 
# File 'lib/AutoItX3/misc.rb', line 63

def cliptext=(text)
  @functions[__method__] ||= AU3_Function.new("ClipPut", 'S')
  @functions[__method__].call(text.wide)
  text
end

.close_cd_tray(tray) ⇒ Object

Closes a cd tray. drive should be of form "X:". The cd tray must be local at this computer, remote drives cannot be accessed. The method may return true if drive is a laptop drive which can only be closed manually.

Raises:

  • (ArgumentError) 


43
44
45
46
47
48
49
50
51
 
# File 'lib/AutoItX3/misc.rb', line 43

def close_cd_tray(tray)
  @functions[__method__] ||= AU3_Function.new("CDTray", 'SS', 'L')
  raise(ArgumentError, "The drive name has to be of form 'X:'!") unless tray =~ /^\w:$/
  if @functions[__method__].call(tray.wide, "closed".wide) == 0
    return false
  else
    return true
  end
end

.close_process(pid) ⇒ Object Also known as: kill_process

call-seq: 

close_process(pid) ==> nil
kill_process(pid) ==> nil

Closes the given process.



40
41
42
43
44
 
# File 'lib/AutoItX3/process.rb', line 40

def close_process(pid)
  @functions[__method__] ||= AU3_Function.new("ProcessClose", 'S', 'L')
  @functions[__method__].call(pid.to_s.wide)
  nil
end

.cursor_id ⇒ Object

call-seq: 

cursor_id ==> aFixnum
get_cursor_id ==> aFixnum

Returns one of the *_CURSOR constants to indicate which cursor icon is actually shown.



79
80
81
82
 
# File 'lib/AutoItX3/mouse.rb', line 79

def cursor_id
  @functions[__method__] ||= AU3_Function.new("MouseGetCursor", '', 'L')
  @functions[__method__].call
end

.cursor_pos ⇒ Object

call-seq: 

cursor_pos ==> anArray
get_cursor_pos ==> anArray

Returns the current cursor position in a two-element array of form [x, y].



89
90
91
92
93
 
# File 'lib/AutoItX3/mouse.rb', line 89

def cursor_pos
  @functions[:cursor_pos_x] ||= AU3_Function.new("MouseGetPosX", 'V', 'L')
  @functions[:cursor_pos_y] ||= AU3_Function.new("MouseGetPosY", 'V', 'L')
  [@functions[:cursor_pos_x].call, @functions[:cursor_pos_y].call]
end

.delete_drive_map(device) ⇒ Object

Disconnects a network drive. device can be either of form "X:" or "||Server|share" (imagine every | to be a backslash). Raises an Au3Error if the disconnection was unsucsessful.



41
42
43
44
45
46
47
48
 
# File 'lib/AutoItX3/filedir.rb', line 41

def delete_drive_map(device)
  @functions[__method__] ||= AU3_Function.new("DriveMapDel", 'S', 'L')
  result = @functions[__method__].call(device)
  if result == 0
    raise(Au3Error, "Failed to remove remote device '#{device}'!")
  end
  true
end

.delete_ini_entry(filename, section, key) ⇒ Object

Deletes a key-value pair in a standard .ini file.



66
67
68
69
70
71
72
73
 
# File 'lib/AutoItX3/filedir.rb', line 66

def delete_ini_entry(filename, section, key)
  @functions[__method__] ||= AU3_Function.new("IniDelete", 'SSS', 'L')
  if @functions[__method__].call(filename.wide, section.wide, key.wide) == 0
    false
  else
    true
  end
end

.drag_mouse(x1, y1, x2, y2, button = "Primary", speed = 10) ⇒ Object

Performes a drag & drop operation with the given parameters.

Raises:



54
55
56
57
58
59
60
 
# File 'lib/AutoItX3/mouse.rb', line 54

def drag_mouse(x1, y1, x2, y2, button = "Primary", speed = 10)
  @functions[__method__] ||= AU3_Function.new("MouseClickDrag", 'SLLLLL', 'L')
  @functions[__method__].call(button.wide, x1, y1, x2, y2, speed)
  
  raise(Au3Error, "Invalid button '#{button}'!") if last_error == 1
  nil
end

.functions ⇒ Object 



115
116
117
 
# File 'lib/AutoItX3/au3.rb', line 115

def self.functions
  @functions
end

.functions=(val) ⇒ Object 



119
120
121
 
# File 'lib/AutoItX3/au3.rb', line 119

def self.functions=(val)
  @functions = val
end

.get_drive_map(device) ⇒ Object

Gets the server of the network drive named by device or raises an Au3Error if it can’t access the device for some reason. The returned string will be of form "||Server|drive" (every | is ment to be a backslash).



53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/AutoItX3/filedir.rb', line 53

def get_drive_map(device)
  @functions[__method__] ||= AU3_Function.new("DriveMapGet", 'SPI')
  buffer = " " * BUFFER_SIZE
  buffer.wide!
  ret = @functions[__method__].call(device, buffer, buffer.size - 1)
  
  if last_error == 1
    raise(Au3Error, "Failed to retrieve information about device '#{device}'")
  end
  buffer.normal.strip
end

.get_pixel_color(x, y, hex = false) ⇒ Object

Retrieves the decimal color value of a pixel. If you want the hexadecimal, pass in true as a third parameter.



23
24
25
26
27
28
 
# File 'lib/AutoItX3/graphic.rb', line 23

def get_pixel_color(x, y, hex = false)
  @functions[__method__] ||= AU3_Function.new("PixelGetColor", 'LL', 'L')
  res = @functions[__method__].call(x, y)
  return "#" + res.to_s(16).upcase if hex
  res
end

.hold_mouse_down(button = "Primary") ⇒ Object

call-seq: 

hold_mouse_down( [ button = "Primary" ] ) ==> nil
mouse_down( [ button = "Primary" ] ) ==> nil

Holds a mouse button down (the left by default, or the right if mouse buttons are swapped). You should release the mouse button somewhen.



68
69
70
71
72
 
# File 'lib/AutoItX3/mouse.rb', line 68

def hold_mouse_down(button = "Primary")
  @functions[__method__] ||= AU3_Function.new("MouseDown", 'S')
  @functions[__method__].call(button.wide)
  nil
end

.input_blocked? ⇒ Boolean

Returns wheather or not input is blocked by AutoItX3.

Returns:

  • (Boolean) 


22
23
24
 
# File 'lib/AutoItX3/misc.rb', line 22

def input_blocked?
  @input_blocked ||= false
end

.is_admin? ⇒ Boolean

Determines wheather the current user has administrator privileges.

Returns:

  • (Boolean) 


54
55
56
57
58
 
# File 'lib/AutoItX3/misc.rb', line 54

def is_admin?
  @functions[__method__] ||= AU3_Function.new("IsAdmin", 'V', 'L')
  return false if @functions[__method__].call == 0
  true
end

.last_error ⇒ Object

Returns the error code of the last called AutoItX3 function, which is 0 if everything worked fine.



148
149
150
151
 
# File 'lib/AutoItX3/au3.rb', line 148

def last_error
  @functions[__method__] ||= AU3_Function.new("error", '', 'L')
  @functions[__method__].call
end

.mouse_click(x = INTDEFAULT, y = INTDEFAULT, button = "Primary", clicks = 1, speed = 10) ⇒ Object

Arguments

  • x (INTDEFAULT): The X position. The cursor’s current X if not specified.

  • y (INTDEFAULT): The Y position. The cursor’s current Y if not specified.

  • button(“Primary”): The mouse button to click width. On a mouse for left-handed people the right, for right-handed people the left mouse button.

  • clicks(1): The number of times to click.

  • speed(10): The speed the mouse cursor will move with. If set to 0, the cursor is set immediatly.

Clicks the mouse.

Raises:



45
46
47
48
49
50
51
 
# File 'lib/AutoItX3/mouse.rb', line 45

def mouse_click(x = INTDEFAULT, y = INTDEFAULT, button = "Primary", clicks = 1, speed = 10)
  @functions[__method__] ||= AU3_Function.new("MouseClick", 'SLLLL', 'L')
  @functions[__method__].call(button.wide, x, y, clicks, speed)
  
  raise(Au3Error, "Invalid button '#{button}'!") if last_error == 1
  nil
end

.mouse_wheel(direction, times = 5) ⇒ Object

Scrolls up or down the mouse wheel times times. Use ether “Up” or “Down” as the value for direction.

Raises:



120
121
122
123
124
125
126
 
# File 'lib/AutoItX3/mouse.rb', line 120

def mouse_wheel(direction, times = 5)
  @functions[__method__] ||= AU3_Function.new("MouseWheel", 'SL')
  @functions[__method__].call(direction.wide, times)
  
  raise(Au3Error, "Undefined mouse wheel direction '#{direction}!") if last_error == 1
  nil
end

.move_mouse(x, y, speed = 10) ⇒ Object

call-seq: 

move_mouse( x , y [, speed = 10 ] ) ==> nil
mouse_move( x , y [, speed = 10 ] ) ==> nil

Moves the mouse cursor to the given position. If speed is 0, it’s set immediately.



101
102
103
104
105
 
# File 'lib/AutoItX3/mouse.rb', line 101

def move_mouse(x, y, speed = 10)
  @functions[__method__] ||= AU3_Function.new("MouseMove", 'LLL', 'L')
  @functions[__method__].call(x, y, speed)
  nil
end

.msleep(msecs) ⇒ Object

Wait for the specified amount of milliseconds. In AutoIt, this function is named “Sleep”, but to avoid compatibility issues with Ruby’s own sleep I decided to name the function “msleep” (the “m” indicates “milli”). If you wish to name it “sleep”, simply define an alias.



98
99
100
101
 
# File 'lib/AutoItX3/misc.rb', line 98

def msleep(msecs)
  @functions[__method__] ||= AU3_Function.new("Sleep", 'L')
  @functions[__method__].call(msecs)
end

.open_cd_tray(tray) ⇒ Object

Opens the cd drive named in drive. drive should be of form "X:". The cd tray must be local at this computer, remote drives cannot be accessed.

Raises:

  • (ArgumentError) 


29
30
31
32
33
34
35
36
37
 
# File 'lib/AutoItX3/misc.rb', line 29

def open_cd_tray(tray)
  @functions[__method__] ||= AU3_Function.new("CDTray", 'SS', 'L')
  raise(ArgumentError, "The drive name has to be of form 'X:'!") unless tray =~ /^\w:$/
  if @functions[__method__].call(tray.wide, "open".wide) == 0
    return false
  else
    return true
  end
end

.pixel_checksum(x1, y1, x2, y2, step = 1) ⇒ Object

Computes a checksum of the pixels in the specified region. If the checksum changes, that only indidcates that something has changed, not what. Note that this method may be very time-consuming, so think about increasing the step parameter (but bear in mind that that will generate more inaccurate checksums).



16
17
18
19
 
# File 'lib/AutoItX3/graphic.rb', line 16

def pixel_checksum(x1, y1, x2, y2, step = 1)
  @functions[__method__] ||= AU3_Function.new("PixelChecksum", 'LLLLL', 'L')
  @functions[__method__].call(x1, y1, x2, y2, step)
end

.process_exists?(pid) ⇒ Boolean

Checks wheather or not the given name or PID exists. If successful, this method returns the PID of the process.

Returns:

  • (Boolean) 


49
50
51
52
53
54
55
56
57
58
 
# File 'lib/AutoItX3/process.rb', line 49

def process_exists?(pid)
  @functions[__method__] ||= AU3_Function.new("ProcessExists", 'S', 'L')
  pid = @functions[__method__].call(pid.to_s.wide)
  if pid == 0
    false
  else
    pid
  end
  
end

.read_ini_entry(filename, section, key, default = nil) ⇒ Object

Reads a value from a standard .ini file or returns the string given by default if it can’t find the key. The returned string will have a maximum length of 99,999 characters.



77
78
79
80
81
82
83
 
# File 'lib/AutoItX3/filedir.rb', line 77

def read_ini_entry(filename, section, key, default = nil)
  @functions[__method__] ||= AU3_Function.new("IniRead", 'SSSSPI')
  buffer = " " * BUFFER_SIZE
  buffer.wide!
  @functions[__method__].call(filename.wide, section.wide, key.wide, default.to_s.wide, buffer, buffer.size - 1)
  buffer.normal.strip
end

.release_mouse(button = "Primary") ⇒ Object

call-seq: 

release_mouse( [ button = "Primary" ] ) ==> nil
mouse_up( [ button = "Primary" ] ) ==> nil

Releases a mouse button hold down by #hold_mouse_down.



112
113
114
115
116
 
# File 'lib/AutoItX3/mouse.rb', line 112

def release_mouse(button = "Primary")
  @functions[__method__] ||= AU3_Function.new("MouseUp", 'S')
  @functions[__method__].call(button.wide)
  nil
end

.run(name, workingdir = "", flag = 1) ⇒ Object

Runs a program. The program flow continues, if you want to wait for the process to finish, use #run_and_wait. Returns the PID of the created process or nil if there was a failure starting the process. The flag parameter can be one of the SW_HIDE, SW_MINIMZE or SW_MAXIMIZE constants in the Window class.

Raises:



104
105
106
107
108
109
 
# File 'lib/AutoItX3/process.rb', line 104

def run(name, workingdir = "", flag = 1)
  @functions[__method__] ||= AU3_Function.new("Run", 'SSL', 'L')
  pid = @functions[__method__].call(name.wide, workingdir.wide, flag)
  raise(Au3Error, "An error occured while starting process '#{name}'!") if last_error == 1
  pid
end

.run_and_wait(name, workingdir = "", flag = 1) ⇒ Object

Runs a program. This method waits until the process has finished and returns the exitcode of the process (or false if there was an error initializing it). If you don’t want this behaviour, use #run. The flag parameter can be one of the SW_HIDE, SW_MINIMZE or SW_MAXIMIZE constants in the Window class.

Raises:



116
117
118
119
120
121
 
# File 'lib/AutoItX3/process.rb', line 116

def run_and_wait(name, workingdir = "", flag = 1)
  @functions[__method__] ||= AU3_Function.new("RunWait", 'SSL', 'L')
  exitcode = @functions[__method__].call(name.wide, workingdir.wide, flag)
  raise(Au3Error, "An error occured while starting process '#{name}'!") if last_error == 1
  exitcode
end

.run_as_set(username, domain, password, options = 1) ⇒ Object

Changes the the owner of following #run and #run_and_wait methods to the given user. Raises a NotImplementedError if your system is Win2000 or older.



125
126
127
128
129
130
131
 
# File 'lib/AutoItX3/process.rb', line 125

def run_as_set(username, domain, password, options = 1)
  @functions[__method__] ||= AU3_Function.new("RunAsSet", 'SSSI', 'L')
  if @functions[__method__].call(username.wide, domain.wide, password.wide, options) == 0
    raise(NotImplementedError, "Your system does not support the #run_as_set method.")
  end
  nil
end

.send_keys(keys, flag = false) ⇒ Object

Simulates the given keystrokes. If you don’t set flag to true (which disables escape sequences), you may use some of the follwing escape sequences in braces { and } (copied from the AutoItX3 help): 

Escape sequence     | Resulting keypress
====================+============================================================
!                   | !
--------------------+------------------------------------------------------------
#                   | #
--------------------+------------------------------------------------------------
+                   | +
--------------------+------------------------------------------------------------
^                   | ^
--------------------+------------------------------------------------------------
{                   | {
--------------------+------------------------------------------------------------
}                   | }
--------------------+------------------------------------------------------------
SPACE               | SPACE
--------------------+------------------------------------------------------------
ENTER               | Return on the main keyboard
--------------------+------------------------------------------------------------
ALT                 | Alt
--------------------+------------------------------------------------------------
BACKSPACE or BS     | Backspace
--------------------+------------------------------------------------------------
DELETE or DEL       | Del
--------------------+------------------------------------------------------------
UP                  | Up arrow
--------------------+------------------------------------------------------------
DOWN                | Down arrow
--------------------+------------------------------------------------------------
LEFT                | Left arrow
--------------------+------------------------------------------------------------
RIGHT               | Right arrow
--------------------+------------------------------------------------------------
HOME                | Home
--------------------+------------------------------------------------------------
END                 | End
--------------------+------------------------------------------------------------
ESCAPE or ESC       | ESC
--------------------+------------------------------------------------------------
INSERT or INS       | Ins
--------------------+------------------------------------------------------------
PGUP                | Page Up
--------------------+------------------------------------------------------------
PGDN                | Page Down
--------------------+------------------------------------------------------------
F1 - F12            | Function keys 1 to 12
--------------------+------------------------------------------------------------
TAB                 | Tab
--------------------+------------------------------------------------------------
PRINTSCREEN         | Printscreen
--------------------+------------------------------------------------------------
LWIN                | Left Windows key
--------------------+------------------------------------------------------------
RWIN                | Right Windows key
--------------------+------------------------------------------------------------
NUMLOCK on          | NumLock on
--------------------+------------------------------------------------------------
CAPSLOCK off        | CapsLock off
--------------------+------------------------------------------------------------
SCROLLLOCK toggle   | ScrollLock toggle
--------------------+------------------------------------------------------------
BREAK               | For CTRL-Break processing
--------------------+------------------------------------------------------------
PAUSE               | Pause
--------------------+------------------------------------------------------------
NUMPAD0 - NUMPAD9   | Numpad number keys. 
--------------------+------------------------------------------------------------
NUMPADMUTLT         | Numpad Multipy
--------------------+------------------------------------------------------------
NUMPADADD           | Numpad Add
--------------------+------------------------------------------------------------
NUMPADSUBT          | Numpad Subtract
--------------------+------------------------------------------------------------
NUMPADDIV           | Numpad Division
--------------------+------------------------------------------------------------
NUMPADDOT           | Numpad dot
--------------------+------------------------------------------------------------
NUMPADENTER         | Numpad return key
--------------------+------------------------------------------------------------
APPSKEY             | Windows App key
--------------------+------------------------------------------------------------
LALT                | Left Alt key
--------------------+------------------------------------------------------------
RALT                | Right Alt key
--------------------+------------------------------------------------------------
LCTRL               | Left control key
--------------------+------------------------------------------------------------
LSHIFT              | Left Shift key
--------------------+------------------------------------------------------------
RSHIFT              | Right Shift key
--------------------+------------------------------------------------------------
SLEEP               | Computer Sleep key
--------------------+------------------------------------------------------------
ALTDOWN             | Hold Alt down until ALTUP is sent
--------------------+------------------------------------------------------------
SHIFTDOWN           | Hold Shift down until SHIFTUP is sent
--------------------+------------------------------------------------------------
CTRLDOWN            | Hold CTRL down until CTRLUP is sent
--------------------+------------------------------------------------------------
LWINDOWN            | Hold the left Windows key down until LWDINUP is sent
--------------------+------------------------------------------------------------
RWINDOWN            | Hold the right Windows key down until RWINUP is sent
--------------------+------------------------------------------------------------
ASC nnnn            | Send the kombination Alt+nnnn on numpad
--------------------+------------------------------------------------------------
BROWSER_BACK        | 2000/XP Only: Select the browser "back" button
--------------------+------------------------------------------------------------
BROWSER_FORWARD     | 2000/XP Only: Select the browser "forward" button
--------------------+------------------------------------------------------------
BROWSER_REFRESH     | 2000/XP Only: Select the browser "refresh" button
--------------------+------------------------------------------------------------
BROWSER_STOP        | 2000/XP Only: Select the browser "stop" button
--------------------+------------------------------------------------------------
BROWSER_SEARCH      | 2000/XP Only: Select the browser "search" button
--------------------+------------------------------------------------------------
BROWSER_FAVORITES   | 2000/XP Only: Select the browser "favorites" button
--------------------+------------------------------------------------------------
BROWSER_HOME        | 2000/XP Only: Launch the browser and go to the home page
--------------------+------------------------------------------------------------
VOLUME_MUTE         | 2000/XP Only: Mute the volume
--------------------+------------------------------------------------------------
VOLUME_DOWN         | 2000/XP Only: Reduce the volume
--------------------+------------------------------------------------------------
VOLUME_UP           | 2000/XP Only: Increase the volume
--------------------+------------------------------------------------------------
MEDIA_NEXT          | 2000/XP Only: Select next track in media player
--------------------+------------------------------------------------------------
MEDIA_PREV          | 2000/XP Only: Select previous track in media player
--------------------+------------------------------------------------------------
MEDIA_STOP          | 2000/XP Only: Stop media player
--------------------+------------------------------------------------------------
MEDIA_PLAY_PAUSE    | 2000/XP Only: Play/pause media player
--------------------+------------------------------------------------------------
LAUNCH_MAIL         | 2000/XP Only: Launch the email application
--------------------+------------------------------------------------------------
LAUNCH_MEDIA        | 2000/XP Only: Launch media player
--------------------+------------------------------------------------------------
LAUNCH_APP1         | 2000/XP Only: Launch user app1
--------------------+------------------------------------------------------------
LAUNCH_APP2         | 2000/XP Only: Launch user app2

A “!” in keys indicates an ALT keystroke, the “+” means SHIFT, “^” CTRL and “#” is the Windows key.



159
160
161
162
 
# File 'lib/AutoItX3/keyboard.rb', line 159

def send_keys(keys, flag = false)
  @functions[__method__] ||= AU3_Function.new("Send", 'SL')
  @functions[__method__].call(keys.wide, flag)
end

.set_option(option, value) ⇒ Object Also known as: opt

call-seq: 

set_option( option , value ) ==> anInteger
set_option( option , value) {...} ==> anObject
opt( option , value ) ==> anInteger
opt( option , value ) {...} ==> anObject

Sets an option that changes the behaviour of AutoIt. If you choose the block form, the option will be resetted after the block finished. The block form returns the last expression, the normal form the previously set option.

The following options are possible (copied from the AutoItX3 help file): 

Option              | Description
====================+============================================================
CaretCoordMode      | Sets the way coords are used in the caret functions, 
                    | either absolute coords or coords relative to the current 
                    | active window:
                    | 0 = relative coords to the active window
                    | 1 = absolute screen coordinates (default)
                    | 2 = relative coords to the client area of the active window
--------------------+------------------------------------------------------------
ColorMode           | Sets the way colors are defined, either RGB or BGR. RGB is 
                    | the default but in previous versions of AutoIt (pre 3.0.102) 
                    | BGR was the default:
                    | 0 = Colors are defined as RGB (0xRRGGBB) (default)
                    | 1 = Colors are defined as BGR (0xBBGGRR) (the mode used in 
                    |     older versions of AutoIt)
--------------------+------------------------------------------------------------
MouseClickDelay     | Alters the length of the brief pause in between mouse 
                    | clicks. 
                    | Time in milliseconds to pause (default=10). 
--------------------+------------------------------------------------------------
MouseClickDownDelay | Alters the length a click is held down before release. 
                    | Time in milliseconds to pause (default=10). 
--------------------+------------------------------------------------------------
MouseClickDragDelay | Alters the length of the brief pause at the start and 
                    | end of a mouse drag operation. 
                    | Time in milliseconds to pause (default=250). 
--------------------+------------------------------------------------------------
MouseCoordMode      | Sets the way coords are used in the mouse functions, 
                    | either absolute coords or coords relative to the current 
                    | active window: 
                    | 0 = relative coords to the active window
                    | 1 = absolute screen coordinates (default)
                    | 2 = relative coords to the client area of the active window
--------------------+------------------------------------------------------------
PixelCoordMode      | Sets the way coords are used in the pixel functions, 
                    | either absolute coords or coords relative to the current 
                    | active window:
                    | 0 = relative coords to the active window
                    | 1 = absolute screen coordinates (default)
                    | 2 = relative coords to the client area of the active window
--------------------+------------------------------------------------------------
SendAttachMode      | Specifies if AutoIt attaches input threads when using then 
                    | Send() function. When not attaching (default mode=0) 
                    | detecting the state of capslock/scrolllock and numlock 
                    | can be unreliable under NT4. However, when you specify 
                    | attach mode=1 the Send("{... down/up}") syntax will not 
                    | work and there may be problems with sending keys to "hung" 
                    | windows. ControlSend() ALWAYS attaches and is not affected 
                    | by this mode. 
                    | 0 = don't attach (default)
                    | 1 = attach
--------------------+------------------------------------------------------------
SendCapslockMode    | Specifies if AutoIt should store the state of capslock 
                    | before a Send function and restore it afterwards. 
                    | 0 = don't store/restore
                    | 1 = store and restore (default)
--------------------+------------------------------------------------------------
SendKeyDelay        | Alters the the length of the brief pause in between 
                    | sent keystrokes. 
                    | Time in milliseconds to pause (default=5). Sometimes a 
                    | value of 0 does not work; use 1 instead.
--------------------+------------------------------------------------------------
SendKeyDownDelay    | Alters the length of time a key is held down before 
                    | released during a keystroke. For applications that 
                    | take a while to register keypresses (and many games) 
                    | you may need to raise this value from the default. 
                    | Time in milliseconds to pause (default=1).
--------------------+------------------------------------------------------------
WinDetectHiddenText | Specifies if hidden window text can be "seen" by the 
                    | window matching functions. 
                    | 0 = Do not detect hidden text (default)
                    | 1 = Detect hidden text
--------------------+------------------------------------------------------------
WinSearchChildren   | Allows the window search routines to search child windows 
                    | as well as top-level windows. 
                    | 0 = Only search top-level windows (default)
                    | 1 = Search top-level and child windows
--------------------+------------------------------------------------------------
WinTextMatchMode    | Alters the method that is used to match window text 
                    | during search operations. 
                    | 1 = Complete / Slow mode (default)
                    | 2 = Quick mode
                    | In quick mode AutoIt can usually only "see" dialog text, 
                    | button text and the captions of some controls. In the 
                    | default mode much more text can be seen (for instance the 
                    | contents of the Notepad window). 
                    | If you are having performance problems when performing 
                    | many window searches then changing to the "quick" mode may 
                    | help. 
--------------------+------------------------------------------------------------
WinTitleMatchMode   | Alters the method that is used to match window titles 
                    | during search operations. 
                    | 1 = Match the title from the start (default)
                    | 2 = Match any substring in the title
                    | 3 = Exact title match
                    | 4 = Advanced mode, see the AutoItX3 help. 
--------------------+------------------------------------------------------------
WinWaitDelay        | Alters how long a script should briefly pause after a 
                    | successful window-related operation. 
                    | Time in milliseconds to pause (default=250).

Raises:

  • (ArgumentError) 


264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/AutoItX3/au3.rb', line 264

def set_option(option, value)
  raise(ArgumentError, "Unknown option '#{option}'!") unless @options.include? option
  @functions[__method__] ||= AU3_Function.new("AutoItSetOption", 'PL', 'L')
  if block_given?
    previous = @options[option]
    @functions[__method__].call(option.to_wchar_t, value)
    ret = yield
    @functions[__method__].call(option.to_wchar_t, previous)
  else
    ret = @functions[__method__].call(option.to_wchar_t, value)
    @options[option] = ret
  end
  ret
end

.set_process_priority(pid, priority) ⇒ Object

Sets a process’s priority. Use one of the *_PRIORITY constants.



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/AutoItX3/process.rb', line 61

def set_process_priority(pid, priority)
  @functions[__method__] ||= AU3_Function.new("ProcessSetPriority", 'SL', 'L')
  @functions[__method__].call(pid.to_s.wide, priority)
  
  case last_error
    when 1 then raise(Au3Error, "Unknown error occured when trying to set process priority of '#{pid}'!")
    when 2 then raise(Au3Error, "Unsupported priority '#{priority}'!")
    else
      return priority
  end
end

.shutdown(code) ⇒ Object

Executes one of the the following commands:

  • SHUTDOWN

  • REBOOT

  • LOGOFF

You can combine the above actions with the below constants, except LOGOFF and POWER_DOWN. Use the + operator to combine them.

  • FORCE_CLOSE

  • POWER_DOWN



141
142
143
144
145
146
147
148
 
# File 'lib/AutoItX3/process.rb', line 141

def shutdown(code)
  @functions[__method__] ||= AU3_Function.new("Shutdown", 'L', 'L')
  if @functions[__method__].call(code) == 0
    false
  else
    true
  end
end

.tool_tip(text, x = INTDEFAULT, y = INTDEFAULT) ⇒ Object Also known as: tooltip

call-seq: 

tool_tip( text [, x = INTDEFAULT [, y = INTDEFAULT ] ] ) ==> nil
tooltip( text [, x = INTDEFAULT [, y = INTDEFAULT ] ] ) ==> nil

Displays a tooltip at the given position. If x and y are ommited, the tooltip will be displayed at the current cursor position. Coordinates out of range are automatically corrected. The tooltip will be deleted when the program ends, or after a system-dependent timeout.



88
89
90
91
 
# File 'lib/AutoItX3/misc.rb', line 88

def tool_tip(text, x = INTDEFAULT, y = INTDEFAULT)
  @functions[__method__] ||= AU3_Function.new("ToolTip", 'SLL')
  @functions[__method__].call(text.wide, x, y)
end

.wait_for_process(procname, timeout = 0) ⇒ Object

Waits for the given process name to exist. This is the only process-related method that doesn’t take a PID, because to wait for a special PID doesn’t make sense, since PIDs are generated randomly.

Return false if timeout was reached.



78
79
80
81
82
83
84
85
 
# File 'lib/AutoItX3/process.rb', line 78

def wait_for_process(procname, timeout = 0)
  @functions[__method__] ||= AU3_Function.new("ProcessWait", 'SL', 'L')
  if @functions[__method__].call(procname.to_s.wide, timeout) == 0
    false
  else
    true
  end
end

.wait_for_process_close(pid, timeout = 0) ⇒ Object

Waits for the given process name or PID to disappear.

Returns false if timeout was reached.



90
91
92
93
94
95
96
97
 
# File 'lib/AutoItX3/process.rb', line 90

def wait_for_process_close(pid, timeout = 0)
  @functions[__method__] ||= AU3_Function.new("ProcessWaitClose", 'SL', 'L')
  if @functions[__method__].call(pid.to_s.wide, timeout) == 0
    false
  else
    true
  end
end

.write_ini_entry(filename, section, key_value, value) ⇒ Object

Writes the specified key-value pair in a .ini file. Existing key-value pairs are overwritten. A non-existing file will be created. Raises an Au3Error if filename is read-only.



87
88
89
90
91
92
93
94
95
 
# File 'lib/AutoItX3/filedir.rb', line 87

def write_ini_entry(filename, section, key_value, value)
  @functions[__method__] ||= AU3_Function.new("IniWrite", 'SSSS', 'L')
  
  if @functions[__method__].call(filename.wide, section.wide, key_value.wide, value.wide) == 0
    raise(Au3Error, "Cannot open file for write access!")
  else
    value
  end
end