Class: AutoItX3::Window

Inherits:
Object
  • Object
show all
Defined in:
lib/AutoItX3/window.rb

Overview

A Window object holds a (pseudo) reference to a window that may be shown on the screen or not. If you want to get a real handle to the window, call #handle on your Window object (but you won’t need that unless you want to use it for Win32 API calls).

Constant Summary collapse

DESKTOP_WINDOW =

A window describing the desktop.

"Program Manager"
ACTIVE_WINDOW =

A window describing the active (foreground) window.

""
SW_HIDE =

Hide the window.

0
SW_SHOW =

Show the window.

5
SW_MINIMIZE =

Minimize the window.

6
SW_MAXIMIZE =

Maximize the window.

3
SW_RESTORE =

Restore a minimized window.

9
SW_SHOWDEFAULT =

Uses the default SW_ value of the application.

10
SW_SHOWMINNOACTIVE =

Same as SW_MINIMIZE, but doesn’t activate the window.

7
SW_SHOWNA =

Same as SW_SHOW, but doesn’t activate the window.

8

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(title, text = "") ⇒ Window

Creates a new Window object. This method checks if a window with the given properties exists (via Window.exists?) and raises an Au3Error if it does not. Use Window::DESKTOP_WINDOW as the title to get a window describing the desktop. Use Window::ACTIVE_WINDOW as the title to get a window describing the active (foreground) window.

Raises:



100
101
102
103
104
 
# File 'lib/AutoItX3/window.rb', line 100

def initialize(title, text = "")
  @title = title
  @text = text
  raise(Au3Error, "Can't get a handle to a non-existing window!") unless Window.exists?(@title, @text)
end

Class Method Details

.caret_pos ⇒ Object

Returns a two-element array of form [x , y] reflecting the position of the caret in the active window. This doesn’t work with every window.

Raises:



63
64
65
66
67
68
69
 
# File 'lib/AutoItX3/window.rb', line 63

def caret_pos
  @functions[:caret_pos_x] ||= AU3_Function.new("WinGetCaretPosX", '', 'L')
  @functions[:caret_pos_y] ||= AU3_Function.new("WinGetCaretPosY", '', 'L')
  pos = [@functions[:caret_pos_x].call, @functions[:caret_pos_y].call]
  raise(Au3Error, "Unknown error occured while retrieving caret coordinates!") if AutoItX3.last_error == 1
  pos
end

.exists?(title, text = "") ⇒ Boolean

Checks if a window with the given properties exists.

Returns:

  • (Boolean) 


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

def exists?(title, text = "")
  @functions[__method__] ||= AU3_Function.new("WinExists", 'SS', 'L')
  if @functions[__method__].call(title.wide, text.wide) == 0
    return false;
  else
    return true;
  end
end

.functions ⇒ Object 



42
43
44
 
# File 'lib/AutoItX3/window.rb', line 42

def functions
  @functions
end

.functions=(hsh) ⇒ Object 



46
47
48
 
# File 'lib/AutoItX3/window.rb', line 46

def functions=(hsh)
  @functions = hsh
end

.minimize_all ⇒ Object

Minimizes all available windows.



72
73
74
75
76
 
# File 'lib/AutoItX3/window.rb', line 72

def minimize_all
  @functions[__method__] ||= AU3_Function.new("WinMinimizeAll", '')
  @functions[__method__].call
  nil
end

.undo_minimize_all ⇒ Object

Undoes a previous call to Window.minimize_all.



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

def undo_minimize_all
  @functions[__method__] ||= AU3_Function.new("WinMinimizeAllUndo", '')
  @functions[__method__].call
  nil
end

.wait(title, text = "", timeout = 0) ⇒ Object

Waits for a window with the given properties to exist. You may specify a timeout in seconds. wait normally returns true, but if the timeout is expired, it returns false.



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

def wait(title, text = "", timeout = 0)
  @functions[__method__] ||= AU3_Function.new("WinWait", 'SSL', 'L')
  @functions[__method__].call(title.wide, text.wide, timeout) != 0
end

Instance Method Details

#activate ⇒ Object

Activates the window and returns true if it was successfully activated (using #active? to check).



124
125
126
127
128
 
# File 'lib/AutoItX3/window.rb', line 124

def activate
  Window.functions[__method__] ||= AU3_Function.new("WinActivate", 'SS')
  Window.functions[__method__].call(@title.wide, @text.wide)
  active?
end

#active? ⇒ Boolean

Checks wheather or not the window is active.

Returns:

  • (Boolean) 


131
132
133
134
135
136
137
138
 
# File 'lib/AutoItX3/window.rb', line 131

def active?
  Window.functions[__method__] ||= AU3_Function.new("WinActive", 'SS', 'L')
  if Window.functions[__method__].call(@title.wide, @text.wide) == 0
    return false
  else
    return true
  end
end

#class_list ⇒ Object

*Returns an array of all used window classes of self.



160
161
162
163
164
165
166
167
 
# File 'lib/AutoItX3/window.rb', line 160

def class_list
  Window.functions[__method__] ||= AU3_Function.new("WinGetClassList", 'SSPI')
  buffer = " " * AutoItX3::BUFFER_SIZE
  buffer.wide!
  Window.functions[__method__].call(@title.wide, @text.wide, buffer, AutoItX3::BUFFER_SIZE - 1)
  raise_unfound if AutoItX3.last_error == 1
  buffer.normal.split("\n").map{|str| str.strip.empty? ? nil : str.strip}.compact
end

#client_size ⇒ Object

Returns the client area size of self as a two-element array of form [ width , height ]. Returns [0, 0] on minimized windows.



172
173
174
175
176
177
178
 
# File 'lib/AutoItX3/window.rb', line 172

def client_size
  Window.functions[:client_size_width] ||= AU3_Function.new("WinGetClientSizeWidth", 'SS', 'L')
  Window.functions[:client_size_height] ||= AU3_Function.new("WinGetClientSizeHeight", 'SS', 'L')
  size = [Window.functions[:client_size_width].call, Window.functions[:client_size_height].call]
  raise_unfound if AutoItX3.last_error == 1
  size
end

#close ⇒ Object

Sends WM_CLOSE to self. WM_CLOSE may be processed by the window, it could, for example, ask to save or the like. If you want to kill a window without giving the ability to process your message, use the #kill method.



143
144
145
146
147
 
# File 'lib/AutoItX3/window.rb', line 143

def close
  Window.functions[__method__] ||= AU3_Function.new("WinClose", 'SS', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide)
  nil
end

#enabled? ⇒ Boolean

Returns true if self is enabled (i.e. it can receive input).

Returns:

  • (Boolean) 


252
253
254
 
# File 'lib/AutoItX3/window.rb', line 252

def enabled?
  (state & 4) == 4
end

#exists? ⇒ Boolean Also known as: valid?

call-seq: 

exists? ==> true or false
valid? ==> true or false

Calls the Window.exists? class method with the values given in Window.new.

Returns:

  • (Boolean) 


154
155
156
 
# File 'lib/AutoItX3/window.rb', line 154

def exists?
  Window.exists?(@title, @text)
end

#focused_control ⇒ Object

Returns the actually focused control in self, a AutoItX3::Control object. Note that if the owning window doesn’t have the input focus, you’ll get an unusable Control object back.



382
383
384
385
386
387
388
 
# File 'lib/AutoItX3/window.rb', line 382

def focused_control
  Window.functions[__method__] ||= AU3_Function.new("ControlGetFocus", 'SSPI')
  buffer = " " * AutoItX3::BUFFER_SIZE
  buffer.wide!
  Window.functions[__method__].call(@title.wide, @text.wide, buffer, AutoItX3::BUFFER_SIZE - 1)
  AutoItX3::Control.new(@title, @text, buffer.normal.strip)
end

#handle ⇒ Object

Returns the numeric handle of a window as a string. It can be used with the WinTitleMatchMode option set to advanced or for direct calls to the windows API (but you have to call .to_i(16) on the string then).



183
184
185
186
187
188
189
190
 
# File 'lib/AutoItX3/window.rb', line 183

def handle
  Window.functions[__method__] ||= AU3_Function.new("WinGetHandle", 'SSPI')
  buffer = " " * AutoItX3::BUFFER_SIZE
  buffer.wide!
  Window.functions[__method__].call(@title.wide, @text.wide, buffer, AutoItX3::BUFFER_SIZE - 1)
  raise_unfound if AutoItX3.last_error == 1
  buffer.normal.strip
end

#inspect ⇒ Object

Human-readable output of form "<Window: WINDOW_TITLE (WINDOW_HANDLE)>". The title is determined by calling #title.



108
109
110
 
# File 'lib/AutoItX3/window.rb', line 108

def inspect
  "<Window: #{title} (#{handle})>"
end

#kill ⇒ Object

Kills self. This method forces a window to close if it doesn’t close quickly enough (in contrary to #close which waits for user actions if neccessary). Some windows cannot be killed (notably Windows Explorer windows).



292
293
294
295
296
 
# File 'lib/AutoItX3/window.rb', line 292

def kill
  Window.functions[__method__] ||= AU3_Function.new("WinKill", 'SS', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide)
  nil
end

#maximized? ⇒ Boolean

Returns true if self is maximized to full screen size.

Returns:

  • (Boolean) 


262
263
264
 
# File 'lib/AutoItX3/window.rb', line 262

def maximized?
  (state & 32) == 32
end

#minimized? ⇒ Boolean

Returns true if self is minimized to the taskbar.

Returns:

  • (Boolean) 


257
258
259
 
# File 'lib/AutoItX3/window.rb', line 257

def minimized?
  (state & 16) == 16
end

#move(x, y, width = -1,, height = -1)) ⇒ Object

Moves a window (and optionally resizes it). This does not work with minimized windows.



310
311
312
313
314
 
# File 'lib/AutoItX3/window.rb', line 310

def move(x, y, width = -1, height = -1)
  Window.functions[__method__] ||= AU3_Function.new("WinMove", 'SSLLLL', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide, x, y, width, height)
  nil
end

#pid ⇒ Object

Returns the process identification number of self‘s window procedure.



215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/AutoItX3/window.rb', line 215

def pid
  Window.functions[__method__] ||= AU3_Function.new("WinGetProcess", 'SSPI', 'L')
  buffer = " " * AutoItX3::BUFFER_SIZE
  buffer.wide!
  Window.functions[__method__].call(@title.wide, @text.wide, buffer, AutoItX3::BUFFER_SIZE - 1)
  buffer.normal!
  buffer.strip!
  if buffer.empty?
    raise(Au3Error, "Unknown error occured while retrieving process ID. Does the window exist?")
  else
    buffer.to_i
  end
end

#rect ⇒ Object

Returns the position and size of self in a four-element array of form [x, y, width, height].



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/AutoItX3/window.rb', line 194

def rect
  Window.functions[:xpos] ||= AU3_Function.new("WinGetPosX", 'SS', 'L')
  Window.functions[:ypos] ||= AU3_Function.new("WinGetPosY", 'SS', 'L')
  Window.functions[:width] ||= AU3_Function.new("WinGetPosWidth", 'SS', 'L')
  Window.functions[:height] ||= AU3_Function.new("WinGetPosHeight", 'SS', 'L')
  
  title = @title.wide
  text = @text.wide
  
  rect = [
    Window.functions[:xpos].call(title, text), 
    Window.functions[:ypos].call(title, text), 
    Window.functions[:width].call(title, text), 
    Window.functions[:height].call(title, text)
  ]
  raise_unfound if AutoItX3.last_error == 1
  rect
end

#select_menu_item(menu, *items) ⇒ Object

Clicks the specified item in the specified menu. You may specify up to seven submenus.

Raises:

  • (ArgumentError) 


300
301
302
303
304
305
306
 
# File 'lib/AutoItX3/window.rb', line 300

def select_menu_item(menu, *items)
  Window.functons[__method__] ||= AU3_Function.new("WinMenuSelectItem", 'SSSSSSSSSS', 'L')
  raise(ArgumentError, "Wrong number of arguments, maximum is seven items!") if items.size > 7 #(menu is the 8th)
  result = Window.functions[__method__].call(@title.wide, @text.wide, menu.wide, *items.map{|item| item.wide})
  raise_unfound if result == 0
  nil
end

#set_on_top=(val) ⇒ Object

Turn the TOPMOST flag of self on or off. If activated, the window will stay on top above all other windows.



318
319
320
321
322
 
# File 'lib/AutoItX3/window.rb', line 318

def set_on_top=(val)
  Window.functions[__method__] ||= AU3_Function.new("WinSetOnTop", 'SSL', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide, !!val)
  val
end

#state ⇒ Object

Returns the integer composition of the states

  • exists (1)

  • visible (2)

  • enabled (4)

  • active (8)

  • minimized (16)

  • maximized (32)

Use the bit-wise AND operator & to check for a specific state. Or just use one of the predefined methods #exists?, #visible?, enabled?, #active?, #minimized? and #maximized?.



239
240
241
242
243
244
 
# File 'lib/AutoItX3/window.rb', line 239

def state
  Window.functions[__method__] ||= AU3_Function.new("WinGetState", 'SS', 'L')
  state = Window.functions[__method__].call(@title.wide, @text.wide)
  raise_unfound if AutoItX3.last_error == 1
  state
end

#state=(val) ⇒ Object

Sets self‘s window state to one of the SW_* constants.



325
326
327
328
329
 
# File 'lib/AutoItX3/window.rb', line 325

def state=(val)
  Window.functions[__method__] ||= AU3_Function.new("WinSetState", 'SSL', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide, val)
  val
end

#statusbar_text(part = 1) ⇒ Object

Reads the text of the statusbar at position part. This method raises an Au3Error if there’s no statusbar, it’s not a mscommon statusbar or if you try to read a position out of range.

Raises:



393
394
395
396
397
398
399
400
 
# File 'lib/AutoItX3/window.rb', line 393

def statusbar_text(part = 1)
  Window.functions[__method__] ||= AU3_Function.new("StatusbarGetText", 'SSLPI')
  buffer = " " * AutoItX3::BUFFER_SIZE
  buffer.wide!
  Window.functions[__method__].call(@title.wide, @text.wide, part, buffer, AutoItX3::BUFFER_SIZE - 1)
  raise(Au3Error, "Couldn't read statusbar text!") if AutoItX3.last_error == 1
  buffer.normal.strip
end

#text ⇒ Object

Returns the text read from a window. This method doesn’t query the @text instance variable, rather it calls the AU3_WinGetText function.



268
269
270
271
272
273
274
 
# File 'lib/AutoItX3/window.rb', line 268

def text
  Window.functions[__method__] ||= AU3_Function.new("WinGetText", 'SSPI')
  buffer = " " * AutoItX3::BUFFER_SIZE
  buffer.wide!
  Window.functions[__method__].call(@title.wide, @text.wide, buffer, AutoItX3::BUFFER_SIZE - 1)
  buffer.normal.strip
end

#title ⇒ Object

Returns the title read from a window. This method does not affect or even use the value of @title, that means you can use title to retrieve titles from a window if you’re working with the advanced window mode.



280
281
282
283
284
285
286
 
# File 'lib/AutoItX3/window.rb', line 280

def title
  Window.functions[__method__] ||= AU3_Function.new("WinGetTitle", 'SSPI')
  buffer = " " * AutoItX3::BUFFER_SIZE
  buffer.wide!
  Window.functions[__method__].call(@title.wide, @text.wide, buffer, AutoItX3::BUFFER_SIZE - 1)
  buffer.normal.strip
end

#title=(val) ⇒ Object

Renames self. This does not change the internal @title instance variable, so you can use this with the advanced window mode.



334
335
336
337
338
 
# File 'lib/AutoItX3/window.rb', line 334

def title=(val)
  Window.functions[__method__] ||= AU3_Function.new("WinSetTitle", 'SSS', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide, val.wide)
  val
end

#to_i ⇒ Object

Returns the handle of the window as an integer by calling .to_i(16) on the result of #handle.



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

def to_i
  handle.to_i(16)
end

#to_s ⇒ Object

Returns self‘s title by returning the value of @title.



113
114
115
 
# File 'lib/AutoItX3/window.rb', line 113

def to_s
  @title
end

#trans=(val) ⇒ Object Also known as: transparency=

call-seq: 

AutoItX3::Window#trans = val ==> val
AutoItX3::Window#transparency = val ==> val

Sets the transparency of self or raises a NotImplementedError if the OS is Windows Millenium or older.



346
347
348
349
350
351
352
 
# File 'lib/AutoItX3/window.rb', line 346

def trans=(val)
  Window.functions[__method__] ||= AU3_Function.new("WinSetTrans", 'SSL', 'L')
  if Window.functions[__method__].call(@title.wide, @text.wide, val) == 0
    raise(NotImplementedError, "The method trans= is only implemented in Win2000 and newer!")
  end
  val
end

#visible? ⇒ Boolean

Returns true if self is shown on the screen.

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/AutoItX3/window.rb', line 247

def visible?
  (state & 2) == 2
end

#wait(timeout = 0) ⇒ Object

Waits for self to exist. This method calls Window’s class method wait, so see Window.wait for more information.



357
358
359
 
# File 'lib/AutoItX3/window.rb', line 357

def wait(timeout = 0)
  Window.wait(@title, @text, timeout)
end

#wait_active(timeout = 0) ⇒ Object

Waits for self to be the active (that is, get the input focus).



362
363
364
365
 
# File 'lib/AutoItX3/window.rb', line 362

def wait_active(timeout = 0)
  Window.functions[__method__] ||= AU3_Function.new("WinWaitActive", 'SSL', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
end

#wait_close(timeout = 0) ⇒ Object

Waits for self to be closed.



368
369
370
371
 
# File 'lib/AutoItX3/window.rb', line 368

def wait_close(timeout = 0)
  Window.functions[__method__] ||= AU3_Function.new("WinWaitClose", 'SSL', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
end

#wait_not_active(timeout = 0) ⇒ Object

Waits for self to lose the input focus.



374
375
376
377
 
# File 'lib/AutoItX3/window.rb', line 374

def wait_not_active(timeout = 0)
  Window.functions[__method__] ||= AU3_Function.new("WinWaitNotActive", 'SSL', 'L')
  Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
end