au3 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  #Encoding: UTF-8
2
2
  #This file is part of au3.
3
- #Copyright © 2009 Marvin Gülker
3
+ #Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
4
4
  #
5
5
  #au3 is published under the same terms as Ruby.
6
6
  #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -36,7 +36,18 @@ module AutoItX3
36
36
  #call-seq:
37
37
  # close_process(pid) ==> nil
38
38
  # kill_process(pid) ==> nil
39
+ #
39
40
  #Closes the given process.
41
+ #===Parameters
42
+ #[+pid+] The PID or name of the process to close.
43
+ #===Return value
44
+ #nil.
45
+ #===Example
46
+ # AutoItX3.close_process(1234)
47
+ #===Remarks
48
+ #This method doesn't ask the process to terminate nicely, it just kills it.
49
+ #If you're familiar with Unix process signals, this method is nearer to
50
+ #sending SIGKILL than sending SIGTERM.
40
51
  def close_process(pid)
41
52
  @functions[__method__] ||= AU3_Function.new("ProcessClose", 'S', 'L')
42
53
  @functions[__method__].call(pid.to_s.wide)
@@ -44,20 +55,35 @@ module AutoItX3
44
55
  end
45
56
  alias kill_process close_process
46
57
 
47
- #Checks wheather or not the given name or PID exists. If successful,
48
- #this method returns the PID of the process.
58
+ #Checks wheather or not the given name or PID exists.
59
+ #===Parameters
60
+ #[+pid+] The PID or name of the process to check.
61
+ #===Return value
62
+ #false if the process doesn't exist, otherwise the PID of the process.
63
+ #===Example
64
+ # p AutoItX3.process_exists?(1234) #=> false
65
+ # p AutoItX3.process_exists("ruby.exe") #=> 4084
49
66
  def process_exists?(pid)
50
67
  @functions[__method__] ||= AU3_Function.new("ProcessExists", 'S', 'L')
51
68
  pid = @functions[__method__].call(pid.to_s.wide)
52
- if pid == 0
53
- false
54
- else
55
- pid
56
- end
57
-
69
+ pid > 0 && pid
58
70
  end
59
71
 
60
- #Sets a process's priority. Use one of the *_PRIORITY constants.
72
+ #Sets a process's priority.
73
+ #===Parameters
74
+ #[+pid+] The PID or name of the process whose priority you want to change.
75
+ #[+priority+] One of the *_PRIORITY constants.
76
+ #===Return value
77
+ #The argument passed as +priority+.
78
+ #===Raises
79
+ #[Au3Error] You passed an invalid priority value or some other error occured.
80
+ #===Example
81
+ # AutoItX3.set_process_priority(4084, AutoItX3::HIGH_PRIORITY)
82
+ # AutoItX3.set_process_priority("ruby.exe", AutoItX3::SUBNORMAL_PRIORITY)
83
+ #===Remarks
84
+ #You shouldn't set a process's priority to REALTIME_PRIORITY, since that
85
+ #is the priority system processes run with which are likely more important than your process.
86
+ #The same goes the other way round: Don't decrease a system process's priority.
61
87
  def set_process_priority(pid, priority)
62
88
  @functions[__method__] ||= AU3_Function.new("ProcessSetPriority", 'SL', 'L')
63
89
  @functions[__method__].call(pid.to_s.wide, priority)
@@ -70,37 +96,54 @@ module AutoItX3
70
96
  end
71
97
  end
72
98
 
73
- #Waits for the given process name to exist. This is the only process-related
74
- #method that doesn't take a PID, because to wait for a special PID doesn't make
75
- #sense, since PIDs are generated randomly.
76
- #
77
- #Return false if +timeout+ was reached.
99
+ #Waits for the given process name to exist.
100
+ #===Parameters
101
+ #[+procname+] The name of the process to wait for.
102
+ #[+timeout+] (+0+) The time to wait, in seconds. The default is to wait infinitely.
103
+ #===Return value
104
+ #true if the process was found, false if +timeout+ was reached.
105
+ #===Example
106
+ # AutoItX3.wait_for_process("nonexistant.exe", 2) #| false
107
+ # AutoItX3.wait_for_process("ruby.exe") #| true
108
+ #===Remarks
109
+ #This is the only process-related method that doesn't take a PID,
110
+ #because to wait for a special PID doesn't make sense, since PIDs
111
+ #are generated randomly.
78
112
  def wait_for_process(procname, timeout = 0)
79
113
  @functions[__method__] ||= AU3_Function.new("ProcessWait", 'SL', 'L')
80
- if @functions[__method__].call(procname.to_s.wide, timeout) == 0
81
- false
82
- else
83
- true
84
- end
114
+ @functions[__method__].call(procname.to_s.wide, timeout) == 1
85
115
  end
86
116
 
87
117
  #Waits for the given process name or PID to disappear.
88
- #
89
- #Returns false if +timeout+ was reached.
118
+ #===Parameters
119
+ #[+pid+] The PID or process name to wait for.
120
+ #[+timeout+] The time to wait, in seconds. 0 means to wait infinitely, which is the default.
121
+ #===Return value
122
+ #true if the process disappeared, false if +timeout+ was reached.
123
+ #===Example
124
+ # AutoItX3.wait_for_process_close(4084) #| true
125
+ # AutoItX3.wait_for_process_close("ruby.exe", 1) #| false
126
+ # #Attention on this one:
127
+ # AutoItX3.wait_for_process_close("nonexistant.exe") #| true
90
128
  def wait_for_process_close(pid, timeout = 0)
91
129
  @functions[__method__] ||= AU3_Function.new("ProcessWaitClose", 'SL', 'L')
92
- if @functions[__method__].call(pid.to_s.wide, timeout) == 0
93
- false
94
- else
95
- true
96
- end
130
+ @functions[__method__].call(pid.to_s.wide, timeout) == 1
97
131
  end
98
132
 
99
- #Runs a program. The program flow continues, if you want to wait for the process to
133
+ #Runs a program.
134
+ #===Parameters
135
+ #[+name+] The command to run.
136
+ #[+workingdir+] (<tt>""</tt>) The working directory to start the process in. Default is the current one.
137
+ #[+flag+] (+1+) Additional properties you want to set on the window. Possible value include SW_HIDE, SW_MINIMIZE and SW_MAXIMIZE, which are defined as constants of the Window class. Default is to set nothing.
138
+ #===Return value
139
+ #The PID of the newly created process.
140
+ #===Raises
141
+ #[Au3Error] Couldn't awake the specified program.
142
+ #===Example
143
+ # p AutoItX3.run("notepad.exe") #=> 502
144
+ #===Remarks
145
+ #The program flow continues; if you want to wait for the process to
100
146
  #finish, use #run_and_wait.
101
- #Returns the PID of the created process or nil if there was a failure starting the process.
102
- #The +flag+ parameter can be one of the SW_HIDE, SW_MINIMZE or SW_MAXIMIZE
103
- #constants in the Window class.
104
147
  def run(name, workingdir = "", flag = 1)
105
148
  @functions[__method__] ||= AU3_Function.new("Run", 'SSL', 'L')
106
149
  pid = @functions[__method__].call(name.wide, workingdir.wide, flag)
@@ -108,11 +151,23 @@ module AutoItX3
108
151
  pid
109
152
  end
110
153
 
111
- #Runs a program. This method waits until the process has finished and returns
112
- #the exitcode of the process (or false if there was an error initializing it). If
113
- #you don't want this behaviour, use #run.
114
- #The +flag+ parameter can be one of the SW_HIDE, SW_MINIMZE or SW_MAXIMIZE
115
- #constants in the Window class.
154
+ #Runs a program and waits until the process has finished.
155
+ #===Parameters
156
+ #[+name+] The command to run.
157
+ #[+workingdir+] (<tt>""</tt>) The working directory to start the process in. Default is the current one.
158
+ #[+flag+] (+1+) Additional properties you want to set on the window. Possible value include SW_HIDE, SW_MINIMIZE and SW_MAXIMIZE, which are defined as constants of the Window class. Default is to set nothing.
159
+ #===Return value
160
+ #The exitcode of the process.
161
+ #===Raises
162
+ #[Au3Error] Couldn't awake the specified program.
163
+ #===Example
164
+ # AutoItX3.run_and_wait("ipconfig") #| 0
165
+ # AutoItX3.run_and_wait("nonexistant.exe")
166
+ #===Remarks
167
+ #If you don't want to wait until the program has finished, use #run.
168
+ #
169
+ #This method doesn't do anything different from Ruby's own Kernel#system method beside
170
+ #the flag you can pass to GUI applications.
116
171
  def run_and_wait(name, workingdir = "", flag = 1)
117
172
  @functions[__method__] ||= AU3_Function.new("RunWait", 'SSL', 'L')
118
173
  exitcode = @functions[__method__].call(name.wide, workingdir.wide, flag)
@@ -121,7 +176,19 @@ module AutoItX3
121
176
  end
122
177
 
123
178
  #Changes the the owner of following #run and #run_and_wait methods to the given
124
- #user. Raises a NotImplementedError if your system is Win2000 or older.
179
+ #user.
180
+ #===Parameters
181
+ #[+username+] The name of the user you want to run commands as.
182
+ #[+domain+] The user's domain.
183
+ #[+password+] The user's password.
184
+ #[+options+] (+1+) One of the following: 0: don't load the user profile, 1 (default): load the user profile, 2: Only for networking.
185
+ #===Return value
186
+ #nil.
187
+ #===Raises
188
+ #[NotImplementedError] You're using Windows ME or earlier which don't support this method.
189
+ #===Example
190
+ # AutoItX3.run_as_set("Rubyist", "WORKGROUP", "MyFamousUncrackablePassword")
191
+ # AutoItX3.run("hack_them_all.exe")
125
192
  def run_as_set(username, domain, password, options = 1)
126
193
  @functions[__method__] ||= AU3_Function.new("RunAsSet", 'SSSI', 'L')
127
194
  if @functions[__method__].call(username.wide, domain.wide, password.wide, options) == 0
@@ -130,23 +197,21 @@ module AutoItX3
130
197
  nil
131
198
  end
132
199
 
133
- #Executes one of the the following commands:
134
- #- SHUTDOWN
135
- #- REBOOT
136
- #- LOGOFF
137
- #You can combine the above actions with the below constants, except
138
- #LOGOFF and POWER_DOWN. Use the + operator to combine them.
139
- #- FORCE_CLOSE
140
- #- POWER_DOWN
200
+ #Shuts down or reboots your computer, or logs you off.
201
+ #===Parameters
202
+ #[+code+] One of the following constants: SHUTDOWN, REBOOT, LOGOFF. You may combine (by using addition with +) each of them with FORCE_CLOSE which forces all hanging applications to close. Additionally, you may combine SHUTDOWN with POWEROFF which ensures that your computer gets cut off from the power supply.
203
+ #===Return value
204
+ #Unknown.
205
+ #===Example
206
+ # AutoItX3.shutdown(AutoItX3::LOGOFF | AutoItX3::FORCE_CLOSE)
207
+ # AutoItX3.shutdown(AutoItX3::REBOOT)
208
+ # AutoItX3.shutdown(AutoItX3::SHUTDOWN + AutoItX3::FORCE_CLOSE + AutoItX3::POWEROFF)
209
+ # #If your computer is still running after executing this sequence of commands, you may should check your hardware.
141
210
  def shutdown(code)
142
211
  @functions[__method__] ||= AU3_Function.new("Shutdown", 'L', 'L')
143
- if @functions[__method__].call(code) == 0
144
- false
145
- else
146
- true
147
- end
212
+ @functions[__method__].call(code) == 1
148
213
  end
149
214
 
150
215
  end
151
216
 
152
- end
217
+ end
@@ -1,6 +1,6 @@
1
1
  #Encoding: UTF-8
2
2
  #This file is part of au3.
3
- #Copyright © 2009 Marvin Gülker
3
+ #Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
4
4
  #
5
5
  #au3 is published under the same terms as Ruby.
6
6
  #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -12,6 +12,19 @@ module AutoItX3
12
12
  #If you want to get a real handle to the window,
13
13
  #call #handle on your Window object (but you won't
14
14
  #need that unless you want to use it for Win32 API calls).
15
+ #
16
+ #Every window is clearly defined by two properties: The window't title
17
+ #(or at least a part of it, see AutoItX3.opts) and it's text.
18
+ #In most cases you can ignore the text, since a window's title is usually
19
+ #enough to identify a window, but if you're only using parts of titles, you may have
20
+ #to check texts as well, but be prepared that the "text" a window holds
21
+ #doesn't have to correspond with the text you actually see on the window.
22
+ #If you set a method's +text+ parameter to an empty string (which is the default),
23
+ #a window will only be searched for by title.
24
+ #
25
+ #Please also note that the handle a Window object holds gets invalid if the window it
26
+ #refers to is closed. This class doesn't automatically notify you if that occures, so
27
+ #don't wonder about "window not found" errors after a window was closed.
15
28
  class Window
16
29
 
17
30
  #A window describing the desktop.
@@ -48,18 +61,28 @@ module AutoItX3
48
61
  end
49
62
 
50
63
  #Checks if a window with the given properties exists.
64
+ #===Parameters
65
+ #[+title+] The window's title.
66
+ #[+text+] (<tt>""</tt>) The window's text.
67
+ #===Return value
68
+ #true or false.
69
+ #===Example
70
+ # p AutoItX3::Window.exists?("Untitled - notepad") #=> true
71
+ # p AutoItX3::Window.exists?("Nonexistant") #=> false
51
72
  def exists?(title, text = "")
52
73
  @functions[__method__] ||= AU3_Function.new("WinExists", 'SS', 'L')
53
- if @functions[__method__].call(title.wide, text.wide) == 0
54
- return false;
55
- else
56
- return true;
57
- end
74
+ @functions[__method__].call(title.wide, text.wide) == 1
58
75
  end
59
76
 
60
- #Returns a two-element array of form <tt>[x , y]</tt> reflecting the
61
- #position of the caret in the active window. This doesn't work with
62
- #every window.
77
+ #Returns the position of the caret in the active window.
78
+ #===Return value
79
+ #A two-element array of form <tt>[x , y]</tt>, which are meant to be row and column, not pixel values.
80
+ #===Example
81
+ # p AutoItX3::Window.caret_pos #=> [8, 28]
82
+ #===Remarks
83
+ #This doesn't work with every window. Many MDI windows, for example, use absolute coordinates and yet other always report static coordinates.
84
+ #
85
+ #The caret is the blinking pipe cursor that is displayed when editing lines of text (it has nothing to do with the mouse cursor).
63
86
  def caret_pos
64
87
  @functions[:caret_pos_x] ||= AU3_Function.new("WinGetCaretPosX", '', 'L')
65
88
  @functions[:caret_pos_y] ||= AU3_Function.new("WinGetCaretPosY", '', 'L')
@@ -69,6 +92,10 @@ module AutoItX3
69
92
  end
70
93
 
71
94
  #Minimizes all available windows.
95
+ #===Return value
96
+ #nil.
97
+ #===Example
98
+ # AutoItX3::Window.minimize_all
72
99
  def minimize_all
73
100
  @functions[__method__] ||= AU3_Function.new("WinMinimizeAll", '')
74
101
  @functions[__method__].call
@@ -76,15 +103,28 @@ module AutoItX3
76
103
  end
77
104
 
78
105
  #Undoes a previous call to Window.minimize_all.
106
+ #===Return value
107
+ #nil.
108
+ #===Example
109
+ # AutoItX3::Window.minimize_all
110
+ # sleep 3
111
+ # AutoItX3::Window.undo_minimize_all
79
112
  def undo_minimize_all
80
113
  @functions[__method__] ||= AU3_Function.new("WinMinimizeAllUndo", '')
81
114
  @functions[__method__].call
82
115
  nil
83
116
  end
84
117
 
85
- #Waits for a window with the given properties to exist. You may
86
- #specify a +timeout+ in seconds. +wait+ normally returns true, but if
87
- #the timeout is expired, it returns false.
118
+ #Waits for a window with the given properties to exist.
119
+ #===Parameters
120
+ #[+title+] The title of the window to wait for.
121
+ #[+text+] (<tt>""</tt> The text of the window to wait for.
122
+ #[+timeout+] (+0+) The time to wait for, in seconds. Zero means to wait infinitely.
123
+ #===Return value
124
+ #true if the window has been found, false if +timeout+ was reached.
125
+ #===Example
126
+ # AutoItX3::Window.wait("Untitled - Notepad") #| true
127
+ # AutoItX3::Window.wait("Nonexistant", 3) #| false
88
128
  def wait(title, text = "", timeout = 0)
89
129
  @functions[__method__] ||= AU3_Function.new("WinWait", 'SSL', 'L')
90
130
  @functions[__method__].call(title.wide, text.wide, timeout) != 0
@@ -92,11 +132,16 @@ module AutoItX3
92
132
 
93
133
  end
94
134
 
95
- #Creates a new Window object. This method checks if a window
96
- #with the given properties exists (via Window.exists?) and raises
97
- #an Au3Error if it does not. Use Window::DESKTOP_WINDOW as
98
- #the +title+ to get a window describing the desktop. Use Window::ACTIVE_WINDOW
99
- #as the +title+ to get a window describing the active (foreground) window.
135
+ #Creates a new Window object.
136
+ #===Parameters
137
+ #[+title+] The title of the window you want a reference to. Use DESKTOP_WINDOW for a handle to the desktop and ACTIVE_WINDOW for a handle to the currently selected window.
138
+ #[+text+] The text of the window you want a reference to.
139
+ #===Return value
140
+ #The newly created Window object.
141
+ #===Raises
142
+ #[Au3Error] No window with the given properties was found.
143
+ #===Example
144
+ # win = AutoItX3::Window.new("Untitled - Notepad")
100
145
  def initialize(title, text = "")
101
146
  @title = title
102
147
  @text = text
@@ -105,22 +150,35 @@ module AutoItX3
105
150
 
106
151
  #Human-readable output of form <tt>"<Window: WINDOW_TITLE (WINDOW_HANDLE)>"</tt>.
107
152
  #The title is determined by calling #title.
108
- def inspect
153
+ def inspect # :nodoc:
109
154
  "<Window: #{title} (#{handle})>"
110
155
  end
111
156
 
112
- #Returns +self+'s title by returning the value of @title.
157
+ #Returns the window's title.
158
+ #===Return value
159
+ #+self+'s title by (the value of <tt>@title</tt>).
160
+ #===Example
161
+ # puts win.to_s #=> Untitled - Notepad
113
162
  def to_s
114
163
  @title
115
164
  end
116
165
 
117
- #Returns the handle of the window as an integer by calling
118
- #<tt>.to_i(16)</tt> on the result of #handle.
166
+ #Returns the actual handle of the window.
167
+ #===Return value
168
+ #The window's handle as an integer.
169
+ #===Example
170
+ # p win.handle #=> 721996
171
+ #===Remarks
172
+ #See also #handle.
119
173
  def to_i
120
174
  handle.to_i(16)
121
175
  end
122
176
 
123
177
  #Activates the window and returns true if it was successfully activated (using #active? to check).
178
+ #===Return value
179
+ #true if the window is activated now, otherwise false.
180
+ #===Example
181
+ # win.activate
124
182
  def activate
125
183
  Window.functions[__method__] ||= AU3_Function.new("WinActivate", 'SS')
126
184
  Window.functions[__method__].call(@title.wide, @text.wide)
@@ -128,16 +186,24 @@ module AutoItX3
128
186
  end
129
187
 
130
188
  #Checks wheather or not the window is active.
189
+ #===Return value
190
+ #true if the window is active, otherwise false.
191
+ #===Example
192
+ # p win.active? #=> false
193
+ # win.activate #| true
194
+ # p win.active? #=> true
131
195
  def active?
132
196
  Window.functions[__method__] ||= AU3_Function.new("WinActive", 'SS', 'L')
133
- if Window.functions[__method__].call(@title.wide, @text.wide) == 0
134
- return false
135
- else
136
- return true
137
- end
197
+ Window.functions[__method__].call(@title.wide, @text.wide) == 1
138
198
  end
139
199
 
140
- #Sends WM_CLOSE to +self+. WM_CLOSE may be processed by the window,
200
+ #Sends WM_CLOSE to +self+. This is like clicking on the [X] button on top of the window.
201
+ #===Return value
202
+ #nil.
203
+ #===Example
204
+ # win.close
205
+ #===Remarks
206
+ #WM_CLOSE may be processed by the window,
141
207
  #it could, for example, ask to save or the like. If you want to kill a window
142
208
  #without giving the ability to process your message, use the #kill method.
143
209
  def close
@@ -151,12 +217,25 @@ module AutoItX3
151
217
  # valid? ==> true or false
152
218
  #
153
219
  #Calls the Window.exists? class method with the values given in Window.new.
220
+ #===Return value
221
+ #true if this object refers to an existing window, false otherwise.
222
+ #===Example
223
+ # p win.exists? #=> true
224
+ # win.close
225
+ # p win.exists? #=> false
154
226
  def exists?
155
227
  Window.exists?(@title, @text)
156
228
  end
157
229
  alias valid? exists?
158
230
 
159
- #*Returns an array of all used window classes of +self+.
231
+ #Returns an array of all used window classes of +self+.
232
+ #===Return value
233
+ #An array containg all the window classes as strings.
234
+ #===Raises
235
+ #[Au3Error] Window not found.
236
+ #===Example
237
+ # p win.class_list
238
+ # #=> ["SciTEWindowContent", "Scintilla", "Scintilla", "ToolbarWindow32", "SciTeTabCtrl", "msctls_statusbar32"]
160
239
  def class_list
161
240
  Window.functions[__method__] ||= AU3_Function.new("WinGetClassList", 'SSPI')
162
241
  buffer = " " * AutoItX3::BUFFER_SIZE
@@ -166,20 +245,34 @@ module AutoItX3
166
245
  buffer.normal.split("\n").map{|str| str.strip.empty? ? nil : str.strip}.compact
167
246
  end
168
247
 
169
- #Returns the client area size of +self+ as a two-element array of
170
- #form <tt>[ width , height ]</tt>. Returns <tt>[0, 0]</tt> on minimized
248
+ #Gets the size of a window's client area.
249
+ #===Return value
250
+ #A two-element array of form <tt>[ width , height ]</tt>. Returns <tt>[0, 0]</tt> on minimized
171
251
  #windows.
252
+ #===Raises
253
+ #[Au3Error] Window not found.
254
+ #===Example
255
+ # p win.client_size #=> [784, 564]
256
+ # #Minimized:
257
+ # p win.client_size #=> [0, 0]
172
258
  def client_size
173
259
  Window.functions[:client_size_width] ||= AU3_Function.new("WinGetClientSizeWidth", 'SS', 'L')
174
260
  Window.functions[:client_size_height] ||= AU3_Function.new("WinGetClientSizeHeight", 'SS', 'L')
175
- size = [Window.functions[:client_size_width].call, Window.functions[:client_size_height].call]
261
+ size = [Window.functions[:client_size_width].call(@title.wide, @text.wide), Window.functions[:client_size_height].call(@title.wide, @text.wide)]
176
262
  raise_unfound if AutoItX3.last_error == 1
177
263
  size
178
264
  end
179
265
 
180
- #Returns the numeric handle of a window as a string. It can be used
181
- #with the WinTitleMatchMode option set to advanced or for direct calls
182
- #to the windows API (but you have to call <tt>.to_i(16)</tt> on the string then).
266
+ #Returns the handle of a window.
267
+ #===Return value
268
+ #Returns the numeric handle of a window as a string.
269
+ #===Raises
270
+ #[Au3Error] Window not found.
271
+ #===Example
272
+ # p win.handle #=> "00070388"
273
+ #===Remarks
274
+ #You may use the handle for instead of passing a title to Window.new or directly for
275
+ #Win32API calls (make sure you call <tt>.to_i(16)</tt> on the string before).
183
276
  def handle
184
277
  Window.functions[__method__] ||= AU3_Function.new("WinGetHandle", 'SSPI')
185
278
  buffer = " " * AutoItX3::BUFFER_SIZE
@@ -189,8 +282,18 @@ module AutoItX3
189
282
  buffer.normal.strip
190
283
  end
191
284
 
285
+ #Gets a window's rectangle.
286
+ #===Return value
192
287
  #Returns the position and size of +self+ in a four-element array
193
- #of form <tt>[x, y, width, height]</tt>.
288
+ #of form <tt>[x, y, width, height]</tt>. If called on a minimized window,
289
+ #the X and Y values are nonsense, but +width+ and +height+ indicate the
290
+ #size of the window's bar in the taskbar.
291
+ #===Raises
292
+ #[Au3Error] Window not found.
293
+ #===Example
294
+ # p win.rect #=> [240, 191, 800, 600]
295
+ # #Called on a minimized window:
296
+ # p win.rect #=> [4294935296, 4294935296, 160, 25]
194
297
  def rect
195
298
  Window.functions[:xpos] ||= AU3_Function.new("WinGetPosX", 'SS', 'L')
196
299
  Window.functions[:ypos] ||= AU3_Function.new("WinGetPosY", 'SS', 'L')
@@ -210,8 +313,14 @@ module AutoItX3
210
313
  rect
211
314
  end
212
315
 
316
+ #Gets the PID of the process running a window.
317
+ #===Return value
213
318
  #Returns the process identification number of +self+'s window
214
319
  #procedure.
320
+ #===Raises
321
+ #[Au3Error] Window not found.
322
+ #===Example
323
+ # p win.pid #=> 3128
215
324
  def pid
216
325
  Window.functions[__method__] ||= AU3_Function.new("WinGetProcess", 'SSPI', 'L')
217
326
  buffer = " " * AutoItX3::BUFFER_SIZE
@@ -226,7 +335,10 @@ module AutoItX3
226
335
  end
227
336
  end
228
337
 
229
- #Returns the integer composition of the states
338
+ #Checks a window's state. You shouldn't use this function, use #exists?,
339
+ ##visible?, #enabled?, #active?, #minimized? and #maximized? instead.
340
+ #===Return value
341
+ #Returns the integer composition of the states:
230
342
  #- exists (1)
231
343
  #- visible (2)
232
344
  #- enabled (4)
@@ -234,8 +346,12 @@ module AutoItX3
234
346
  #- minimized (16)
235
347
  #- maximized (32)
236
348
  #Use the bit-wise AND operator & to check for a specific state.
237
- #Or just use one of the predefined methods #exists?, #visible?,
238
- ##enabled?, #active?, #minimized? and #maximized?.
349
+ #===Raises
350
+ #[Au3Error] Window not found.
351
+ #===Example
352
+ # #Check for visibility
353
+ # p(win.state & 2) #=> 2 #visible
354
+ # p(win.state & 2) #=> 0 #invisible
239
355
  def state
240
356
  Window.functions[__method__] ||= AU3_Function.new("WinGetState", 'SS', 'L')
241
357
  state = Window.functions[__method__].call(@title.wide, @text.wide)
@@ -243,28 +359,59 @@ module AutoItX3
243
359
  state
244
360
  end
245
361
 
246
- #Returns true if +self+ is shown on the screen.
362
+ #Checks wheather a window is visible or not.
363
+ #===Return value
364
+ #Returns true if +self+ is shown on the screen, false otherwise.
365
+ #===Raises
366
+ #[Au3Error] Window not found.
367
+ #===Example
368
+ # p win.visible? #=> true
247
369
  def visible?
248
370
  (state & 2) == 2
249
371
  end
250
372
 
251
- #Returns true if +self+ is enabled (i.e. it can receive input).
373
+ #Checks wheather a window can receive user input or not.
374
+ #===Return value
375
+ #Returns true if +self+ is enabled, false otherwise.
376
+ #===Raises
377
+ #[Au3Error] Window not found.
378
+ #===Example
379
+ # p win.enabled? #=> false
252
380
  def enabled?
253
381
  (state & 4) == 4
254
382
  end
255
383
 
256
- #Returns true if +self+ is minimized to the taskbar.
384
+ #Checks wheather or not a window is minimized to the taskbar.
385
+ #===Return value
386
+ #Returns true if +self+ is minimized to the taskbar, false otherwise.
387
+ #===Raises
388
+ #[Au3Error] Window not found.
389
+ #===Example
390
+ # p win.minimized? #=> true
257
391
  def minimized?
258
392
  (state & 16) == 16
259
393
  end
260
394
 
395
+ #Checks wheather or not this is a fullscreen window.
396
+ #===Return value
261
397
  #Returns true if +self+ is maximized to full screen size.
398
+ #===Raises
399
+ #[Au3Error] Window not found.
400
+ #===Example
401
+ # p win.maximized? #=> false
262
402
  def maximized?
263
403
  (state & 32) == 32
264
404
  end
265
405
 
266
406
  #Returns the text read from a window. This method doesn't query the @text instance
267
407
  #variable, rather it calls the AU3_WinGetText function.
408
+ #===Return value
409
+ #The window's text. It doesn't necassary make sense.
410
+ #===Example
411
+ # #Used on an explorer window:
412
+ # p win.text #=> "Navigationsleiste\nAdresse: C:\\Users\\marvin_g\\Desktop\\Automations\\au3\\trunk\\lib\nlib\nHostwrapper f├╝r gemeinsame Orte\nShellView\nFolderView\nMen├╝leiste"
413
+ # #Some windows just don't have any text.
414
+ # p win.text #=> ""
268
415
  def text
269
416
  Window.functions[__method__] ||= AU3_Function.new("WinGetText", 'SSPI')
270
417
  buffer = " " * AutoItX3::BUFFER_SIZE
@@ -277,6 +424,10 @@ module AutoItX3
277
424
  #affect or even use the value of @title, that means you can use
278
425
  #+title+ to retrieve titles from a window if you're working with the
279
426
  #advanced window mode.
427
+ #===Return value
428
+ #The window's title.
429
+ #===Example
430
+ # p win.title #=> "AutoItX Help"
280
431
  def title
281
432
  Window.functions[__method__] ||= AU3_Function.new("WinGetTitle", 'SSPI')
282
433
  buffer = " " * AutoItX3::BUFFER_SIZE
@@ -287,26 +438,64 @@ module AutoItX3
287
438
 
288
439
  #Kills +self+. This method forces a window to close if it doesn't close
289
440
  #quickly enough (in contrary to #close which waits for user actions
290
- #if neccessary). Some windows cannot be +kill+ed (notably
291
- #Windows Explorer windows).
441
+ #if neccessary).
442
+ #===Return value
443
+ #nil.
444
+ #===Example
445
+ # win.kill
446
+ # p win.exists? #=> false
447
+ #===Remarks
448
+ #Some windows cannot be +kill+ed (notably Windows Explorer windows).
292
449
  def kill
293
450
  Window.functions[__method__] ||= AU3_Function.new("WinKill", 'SS', 'L')
294
451
  Window.functions[__method__].call(@title.wide, @text.wide)
295
452
  nil
296
453
  end
297
454
 
298
- #Clicks the specified item in the specified menu. You may specify up to seven
299
- #submenus.
455
+ #Clicks a menu entry.
456
+ #===Parameters
457
+ #[+menu+] The name of the top menu, such as <tt>"File"</tt> (or rather <tt>"&File"</tt>; you have to prefix underlined letters with an ampersand sign &).
458
+ #[<tt>*items</tt>] Up to 7 submenus, use this in the same matter as +menu+.
459
+ #===Return value
460
+ #nil.
461
+ #===Raises
462
+ #[Au3Error] Window not found.
463
+ #===Example
464
+ # #Open the "Help" entry in SciTE's "Help" menu:
465
+ # win.select_menu_item("&Help", "&Help")
466
+ #===Remarks
467
+ #You can't open a menu with this method, the last submenu has to be associated with an action like opening a dialog window.
468
+ #
469
+ #If you experience troubles with entries containing three dots <tt>...</tt> you should check if those three dots aren't a
470
+ #Unicode character like Horizontal Ellipsis (<tt>…</tt>, U+2026). Just try that character instead of three dots.
300
471
  def select_menu_item(menu, *items)
301
- Window.functons[__method__] ||= AU3_Function.new("WinMenuSelectItem", 'SSSSSSSSSS', 'L')
472
+ Window.functions[__method__] ||= AU3_Function.new("WinMenuSelectItem", 'SSSSSSSSSS', 'L')
302
473
  raise(ArgumentError, "Wrong number of arguments, maximum is seven items!") if items.size > 7 #(menu is the 8th)
474
+ items[6] = nil if items.size < 7
475
+ items.map!{|item| item.nil? ? "" : item}
303
476
  result = Window.functions[__method__].call(@title.wide, @text.wide, menu.wide, *items.map{|item| item.wide})
304
477
  raise_unfound if result == 0
305
478
  nil
306
479
  end
307
480
 
308
- #Moves a window (and optionally resizes it). This does not work
309
- #with minimized windows.
481
+ #Moves a window (and optionally resizes it).
482
+ #===Parameters
483
+ #[+x+] The X coordinate to move the window to.
484
+ #[+y+] The Y coordinate to move the window to.
485
+ #[+width+] (<tt>-1</tt>) The window's new width.
486
+ #[+height+] (<tt>-1</tt>) The window's new width.
487
+ #===Return value
488
+ #nil.
489
+ #===Example
490
+ # #Move a window to (10|10):
491
+ # win.move(10, 10)
492
+ # #Moves a windot to (100|100) and resizes it to 500 x 500:
493
+ # win.move(100, 100, 500, 500)
494
+ # #Since you can't resize a window without moving it, use this to achieve
495
+ # #the same effect:
496
+ # win.move(win.rect[0], win.rect[1], 700, 700)
497
+ #===Remarks
498
+ #This does not work with minimized and maximized windows.
310
499
  def move(x, y, width = -1, height = -1)
311
500
  Window.functions[__method__] ||= AU3_Function.new("WinMove", 'SSLLLL', 'L')
312
501
  Window.functions[__method__].call(@title.wide, @text.wide, x, y, width, height)
@@ -314,23 +503,67 @@ module AutoItX3
314
503
  end
315
504
 
316
505
  #Turn the TOPMOST flag of +self+ on or off. If activated, the window
317
- #will stay on top above all other windows.
506
+ #will stay on top above all other windows.
507
+ #===Parameters
508
+ #[+val+] true or false.
509
+ #===Return value
510
+ #The argument passed.
511
+ #===Example
512
+ # win.set_on_top = true
318
513
  def set_on_top=(val)
319
514
  Window.functions[__method__] ||= AU3_Function.new("WinSetOnTop", 'SSL', 'L')
320
515
  Window.functions[__method__].call(@title.wide, @text.wide, !!val)
321
516
  val
322
517
  end
323
518
 
324
- #Sets +self+'s window state to one of the SW_* constants.
519
+ #Sets +self+ to a specific state like "maximized".
520
+ #===Parameters
521
+ #[+val+] The state the window should be set to. One of the SW_* constants of this class.
522
+ #===Return value
523
+ #The argument passed.
524
+ #===Example
525
+ # #Mimize a window
526
+ # win.state = AutoItX3::Window::SW_MINIMIZE
527
+ # #Make it fullscreen
528
+ # win.state = AutoItX3::Window::SW_MAXIMIZE
325
529
  def state=(val)
326
530
  Window.functions[__method__] ||= AU3_Function.new("WinSetState", 'SSL', 'L')
327
531
  Window.functions[__method__].call(@title.wide, @text.wide, val)
328
532
  val
329
533
  end
330
534
 
331
- #Renames +self+. This does not change the internal @title
332
- #instance variable, so you can use this with the
333
- #advanced window mode.
535
+ #Renames +self+.
536
+ #===Parameters
537
+ #[+val+] The new title.
538
+ #===Return value
539
+ #The argument passed.
540
+ #===Example
541
+ # win.title = "Use Ruby whenever you can"
542
+ #===Remarks
543
+ #This does not change the internal @title instance variable, so you can use this with the
544
+ #advanced window mode; this has another issue, though. If you aren't working in advanced
545
+ #window mode, you (pseudo) Ruby handle gets invalid, since it only references the window by title:
546
+ # irb(main):042:0> win.title = "xxx"
547
+ # => "xxx"
548
+ # irb(main):043:0> win
549
+ # AutoItX3::Au3Error: Unable to find a window with title 'lib' and text ''!
550
+ # from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
551
+ # .rb:265:in `handle'
552
+ # from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
553
+ # .rb:154:in `inspect'
554
+ # irb(main):044:0> win2 = AutoItX3::Window.new("xxx")
555
+ # => <Window: xxx (00070388)>
556
+ # irb(main):045:0> win2.title = "lib"
557
+ # => "lib"
558
+ # irb(main):046:0> win2
559
+ # AutoItX3::Au3Error: Unable to find a window with title 'xxx' and text ''!
560
+ # from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
561
+ # .rb:265:in `handle'
562
+ # from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
563
+ # .rb:154:in `inspect'
564
+ # irb(main):047:0> win
565
+ # => <Window: lib (00070388)>
566
+ # irb(main):048:0>
334
567
  def title=(val)
335
568
  Window.functions[__method__] ||= AU3_Function.new("WinSetTitle", 'SSS', 'L')
336
569
  Window.functions[__method__].call(@title.wide, @text.wide, val.wide)
@@ -341,8 +574,17 @@ module AutoItX3
341
574
  # AutoItX3::Window#trans = val ==> val
342
575
  # AutoItX3::Window#transparency = val ==> val
343
576
  #
344
- #Sets the transparency of +self+ or raises a NotImplementedError
345
- #if the OS is Windows Millenium or older.
577
+ #Sets a window's transparency.
578
+ #===Parameters
579
+ #[+val+] The opacity you want the window set to; a numeric value between 0 (compelety transparent) and 255 (opaque).
580
+ #===Return value
581
+ #The argument passed.
582
+ #===Raises
583
+ #[NotImplementedError] You are using Windows Millenium or older which don't support transparent windows.
584
+ #===Example
585
+ # win.trans = 100
586
+ #===Remarks
587
+ #Note that a window whose transparency is set to 0 doesn't cause #visible? to return false.
346
588
  def trans=(val)
347
589
  Window.functions[__method__] ||= AU3_Function.new("WinSetTrans", 'SSL', 'L')
348
590
  if Window.functions[__method__].call(@title.wide, @text.wide, val) == 0
@@ -352,31 +594,66 @@ module AutoItX3
352
594
  end
353
595
  alias transparency= trans=
354
596
 
355
- #Waits for +self+ to exist. This method calls Window's class
356
- #method wait, so see Window.wait for more information.
597
+ #Waits for +self+ to exist.
598
+ #===Parameters
599
+ #[+timeout+] (+0+) The time to wait for the window to appear, in seconds. If set to 0 (which is the default), waits infinitely.
600
+ #===Return value
601
+ #true if the window was found, false if +timeout+ was reached.
602
+ #===Example
603
+ # win.wait
604
+ # #Only for 10 seconds
605
+ # puts "Window doesn't exist" unless win.wait(10)
357
606
  def wait(timeout = 0)
358
607
  Window.wait(@title, @text, timeout)
359
608
  end
360
609
 
361
610
  #Waits for +self+ to be the active (that is, get the input focus).
611
+ #===Parameters
612
+ #[+timeout+] (+0+) The time to wait, in seconds. 0 means waiting infinitely.
613
+ #===Return value
614
+ #true if the window has been activated, false if +timeout+ was reached.
615
+ #===Example
616
+ # win.wait_active
617
+ # #Only for 10 seconds
618
+ # puts "YOU HAVE TO CLICK THE WINDOW!!!!!" unless win.wait_active(10)
362
619
  def wait_active(timeout = 0)
363
620
  Window.functions[__method__] ||= AU3_Function.new("WinWaitActive", 'SSL', 'L')
364
621
  Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
365
622
  end
366
623
 
367
624
  #Waits for +self+ to be closed.
625
+ #===Parameters
626
+ #[+timeout+] (+0+) The time to wait, in seconds. 0 means to wait till doomsday.
627
+ #===Return value
628
+ #true if the window was closed, false if +timeout+ was reached.
629
+ #===Example
630
+ # win.wait_close(10) #Wait for 10 seconds
368
631
  def wait_close(timeout = 0)
369
632
  Window.functions[__method__] ||= AU3_Function.new("WinWaitClose", 'SSL', 'L')
370
633
  Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
371
634
  end
372
635
 
373
636
  #Waits for +self+ to lose the input focus.
637
+ #===Parameters
638
+ #[+timeout+] (+0+) The time to wait, in seconds. 0 means waiting infinitely.
639
+ #===Return value
640
+ #true if the window has lost the input focus, false if +timeout+ was reached.
641
+ #===Example
642
+ # win.wait_not_active(10) #Wait for 10 seconds
374
643
  def wait_not_active(timeout = 0)
375
644
  Window.functions[__method__] ||= AU3_Function.new("WinWaitNotActive", 'SSL', 'L')
376
645
  Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
377
646
  end
378
647
 
379
- #Returns the actually focused control in +self+, a AutoItX3::Control object.
648
+ #Gets the actually focused control in +self+.
649
+ #===Return value
650
+ #A AutoItX3::Control object.
651
+ #===Example
652
+ # #For any control
653
+ # c = win.focused_control
654
+ # #If you're sure it's a textbox
655
+ # t = AutoItX3::Edit.from_control(win.focused_control)
656
+ #===Remarks
380
657
  #Note that if the owning window doesn't have the input focus, you'll get an
381
658
  #unusable Control object back.
382
659
  def focused_control
@@ -387,9 +664,17 @@ module AutoItX3
387
664
  AutoItX3::Control.new(@title, @text, buffer.normal.strip)
388
665
  end
389
666
 
390
- #Reads the text of the statusbar at position +part+. This method
391
- #raises an Au3Error if there's no statusbar, it's not a mscommon
392
- #statusbar or if you try to read a position out of range.
667
+ #Reads the statusbar's text(s).
668
+ #===Parameters
669
+ #[+part+] (+1+) The part of the statusbar to read, a 1-based index.
670
+ #===Return value
671
+ #The text read.
672
+ #===Raises
673
+ #[Au3Error] Couldn't read the statusbar's text. The window may doesn't have a statusbar, it's not a mscommon statusbar or you tried to read an index out of range.
674
+ #===Example
675
+ # p win.statusbar_text #=> "Loading..."
676
+ #===Remarks
677
+ #I couldn't get this method to work with whatever window I tried. Suggestions?
393
678
  def statusbar_text(part = 1)
394
679
  Window.functions[__method__] ||= AU3_Function.new("StatusbarGetText", 'SSLPI')
395
680
  buffer = " " * AutoItX3::BUFFER_SIZE