Class: AutoItX3::Window

Inherits:
Object
  • Object
show all
Defined in:
lib/AutoItX3/window.rb,
lib/AutoItX3/window/send_message.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).

Every window is clearly defined by two properties: The window’t title (or at least a part of it, see AutoItX3.opts) and it’s text. In most cases you can ignore the text, since a window’s title is usually enough to identify a window, but if you’re only using parts of titles, you may have to check texts as well, but be prepared that the “text” a window holds doesn’t have to correspond with the text you actually see on the window. If you set a method’s text parameter to an empty string (which is the default), a window will only be searched for by title.

Please also note that the handle a Window object holds gets invalid if the window it refers to is closed. This class doesn’t automatically notify you if that occures, so don’t wonder about “window not found” errors after a window was closed.

Defined Under Namespace

Modules: Messages

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.

Parameters

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.

text

The text of the window you want a reference to.

Return value

The newly created Window object.

Raises

Au3Error

No window with the given properties was found.

Example

win = AutoItX3::Window.new("Untitled - Notepad")

Raises:



145
146
147
148
149
 
# File 'lib/AutoItX3/window.rb', line 145

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 the position of the caret in the active window.

Return value

A two-element array of form [x , y], which are meant to be row and column, not pixel values.

Example

p AutoItX3::Window.caret_pos #=> [8, 28]

Remarks

This doesn’t work with every window. Many MDI windows, for example, use absolute coordinates and yet other always report static coordinates.

The caret is the blinking pipe cursor that is displayed when editing lines of text (it has nothing to do with the mouse cursor).

Raises:



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

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.

Parameters

title

The window’s title.

text

("") The window’s text.

Return value

true or false.

Example

p AutoItX3::Window.exists?("Untitled - notepad") #=> true
p AutoItX3::Window.exists?("Nonexistant") #=> false

Returns:

  • (Boolean) 


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

def exists?(title, text = "")
  @functions[__method__] ||= AU3_Function.new("WinExists", 'SS', 'L')
  @functions[__method__].call(title.wide, text.wide) == 1
end

.functions ⇒ Object 



55
56
57
 
# File 'lib/AutoItX3/window.rb', line 55

def functions
  @functions
end

.functions=(hsh) ⇒ Object 



59
60
61
 
# File 'lib/AutoItX3/window.rb', line 59

def functions=(hsh)
  @functions = hsh
end

.minimize_all ⇒ Object

Minimizes all available windows.

Return value

nil.

Example

AutoItX3::Window.minimize_all



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

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.

Return value

nil.

Example

AutoItX3::Window.minimize_all
sleep 3
AutoItX3::Window.undo_minimize_all



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

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.

Parameters

title

The title of the window to wait for.

text

("" The text of the window to wait for.

timeout

(0) The time to wait for, in seconds. Zero means to wait infinitely.

Return value

true if the window has been found, false if timeout was reached.

Example

AutoItX3::Window.wait("Untitled - Notepad") #| true
AutoItX3::Window.wait("Nonexistant", 3) #| false



128
129
130
131
 
# File 'lib/AutoItX3/window.rb', line 128

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).

Return value

true if the window is activated now, otherwise false.

Example

win.activate



182
183
184
185
186
 
# File 'lib/AutoItX3/window.rb', line 182

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.

Return value

true if the window is active, otherwise false.

Example

p win.active? #=> false
win.activate #| true
p win.active? #=> true

Returns:

  • (Boolean) 


195
196
197
198
 
# File 'lib/AutoItX3/window.rb', line 195

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

#class_list ⇒ Object

Returns an array of all used window classes of self.

Return value

An array containg all the window classes as strings.

Raises

Au3Error

Window not found.

Example

p win.class_list 
#=> ["SciTEWindowContent", "Scintilla", "Scintilla", "ToolbarWindow32", "SciTeTabCtrl", "msctls_statusbar32"]



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

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

Gets the size of a window’s client area.

Return value

A two-element array of form [ width , height ]. Returns [0, 0] on minimized windows.

Raises

Au3Error

Window not found.

Example

p win.client_size #=> [784, 564]
#Minimized: 
p win.client_size #=> [0, 0]



258
259
260
261
262
263
264
 
# File 'lib/AutoItX3/window.rb', line 258

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(@title.wide, @text.wide), Window.functions[:client_size_height].call(@title.wide, @text.wide)]
  raise_unfound if AutoItX3.last_error == 1
  size
end

#close ⇒ Object

Sends WM_CLOSE to self. This is like clicking on the [X] button on top of the window.

Return value

nil.

Example

win.close

Remarks

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.



209
210
211
212
213
 
# File 'lib/AutoItX3/window.rb', line 209

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

#enabled? ⇒ Boolean

Checks wheather a window can receive user input or not.

Return value

Returns true if self is enabled, false otherwise.

Raises

Au3Error

Window not found.

Example

p win.enabled? #=> false

Returns:

  • (Boolean) 


380
381
382
 
# File 'lib/AutoItX3/window.rb', line 380

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.

Return value

true if this object refers to an existing window, false otherwise.

Example

p win.exists? #=> true
win.close
p win.exists? #=> false

Returns:

  • (Boolean) 


226
227
228
 
# File 'lib/AutoItX3/window.rb', line 226

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

#focused_control ⇒ Object

Gets the actually focused control in self.

Return value

A AutoItX3::Control object.

Example

#For any control
c = win.focused_control
#If you're sure it's a textbox
t = AutoItX3::Edit.from_control(win.focused_control)

Remarks

Note that if the owning window doesn’t have the input focus, you’ll get an unusable Control object back.



659
660
661
662
663
664
665
 
# File 'lib/AutoItX3/window.rb', line 659

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 handle of a window.

Return value

Returns the numeric handle of a window as a string.

Raises

Au3Error

Window not found.

Example

p win.handle #=> "00070388"

Remarks

You may use the handle for instead of passing a title to Window.new or directly for Win32API calls (make sure you call .to_i(16) on the string before).



276
277
278
279
280
281
282
283
 
# File 'lib/AutoItX3/window.rb', line 276

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.



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

def inspect # :nodoc:
  "<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).

Return value

nil.

Example

win.kill
p win.exists? #=> false

Remarks

Some windows cannot be killed (notably Windows Explorer windows).



449
450
451
452
453
 
# File 'lib/AutoItX3/window.rb', line 449

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

#maximized? ⇒ Boolean

Checks wheather or not this is a fullscreen window.

Return value

Returns true if self is maximized to full screen size.

Raises

Au3Error

Window not found.

Example

p win.maximized? #=> false

Returns:

  • (Boolean) 


402
403
404
 
# File 'lib/AutoItX3/window.rb', line 402

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

#minimized? ⇒ Boolean

Checks wheather or not a window is minimized to the taskbar.

Return value

Returns true if self is minimized to the taskbar, false otherwise.

Raises

Au3Error

Window not found.

Example

p win.minimized? #=> true

Returns:

  • (Boolean) 


391
392
393
 
# File 'lib/AutoItX3/window.rb', line 391

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

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

Moves a window (and optionally resizes it).

Parameters

x

The X coordinate to move the window to.

y

The Y coordinate to move the window to.

width

(-1) The window’s new width.

height

(-1) The window’s new width.

Return value

nil.

Example

#Move a window to (10|10): 
win.move(10, 10)
#Moves a windot to (100|100) and resizes it to 500 x 500: 
win.move(100, 100, 500, 500)
#Since you can't resize a window without moving it, use this to achieve 
#the same effect: 
win.move(win.rect[0], win.rect[1], 700, 700)

Remarks

This does not work with minimized and maximized windows.



499
500
501
502
503
 
# File 'lib/AutoItX3/window.rb', line 499

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

Gets the PID of the process running a window.

Return value

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

Raises

Au3Error

Window not found.

Example

p win.pid #=> 3128



324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/AutoItX3/window.rb', line 324

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

#post_message(msg, info1 = 0, info2 = 0) ⇒ Object

Puts a window message in self‘s message queue and immediately returns.

Parameters

msg

The message to send. Either a constant from the Window::Messages module, or a symbol formed off a such name. For example, for WM_QUIT you’d pass :quit.

info1

(0) Additional message-specific information (wParam value).

info2

(0) Additional message-specific information (lParam value).

Return value

The return value of the PostMessage() function.

Raises

Au3Error

Window not found.

Errno::EACCES

Windows’s security policy blocked the function call.

Example

win.post_message(:quit) #Request a window to exit. It doesn't have to obey, though.

Remarks

You can find the additional paramters needed for each message at the Windows API docs at MSDN. I recommand you to query the search function with something like “WM_PAINT” if you want to know more about WM_PAINT.



259
260
261
262
263
264
265
266
267
 
# File 'lib/AutoItX3/window/send_message.rb', line 259

def post_message(msg, info1 = 0, info2 = 0)
  Window.functions[__method__] ||= Win32::API.new("PostMessage", 'LILL', 'I', "user32")
  
  raise_unfound unless exists?
  msg = Messages.const_get(:"WM_#{msg.to_s.upcase}") if msg.kind_of? Symbol
  ret = Window.functions[__method__].call(self.to_i, msg, info1, info2)
  Kernel.raise(Errno::EACCES, "The Windows UIPI blocked your function call.") if Window.functions[:get_last_error].call == 5
  ret
end

#rect ⇒ Object

Gets a window’s rectangle.

Return value

Returns the position and size of self in a four-element array of form [x, y, width, height]. If called on a minimized window, the X and Y values are nonsense, but width and height indicate the size of the window’s bar in the taskbar.

Raises

Au3Error

Window not found.

Example

p win.rect #=> [240, 191, 800, 600]
#Called on a minimized window: 
p win.rect #=> [4294935296, 4294935296, 160, 25]



297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/AutoItX3/window.rb', line 297

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 a menu entry.

Parameters

menu

The name of the top menu, such as "File" (or rather "&File"; you have to prefix underlined letters with an ampersand sign &).

*items

Up to 7 submenus, use this in the same matter as menu.

Return value

nil.

Raises

Au3Error

Window not found.

Example

#Open the "Help" entry in SciTE's "Help" menu: 
win.select_menu_item("&Help", "&Help")

Remarks

You can’t open a menu with this method, the last submenu has to be associated with an action like opening a dialog window.

If you experience troubles with entries containing three dots ... you should check if those three dots aren’t a Unicode character like Horizontal Ellipsis (…, U+2026). Just try that character instead of three dots.

Raises:

  • (ArgumentError) 


471
472
473
474
475
476
477
478
479
 
# File 'lib/AutoItX3/window.rb', line 471

def select_menu_item(menu, *items)
  Window.functions[__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)
  items[6] = nil if items.size < 7
  items.map!{|item| item.nil? ? "" : item}
  result = Window.functions[__method__].call(@title.wide, @text.wide, menu.wide, *items.map{|item| item.wide})
  raise_unfound if result == 0
  nil
end

#send_message(msg, info1 = 0, info2 = 0) ⇒ Object

Sends a window message to self and waits for the window to process it.

Parameters

msg

The message to send. Either a constant from the Window::Messages module, or a symbol formed off a such name. For example, for WM_DESTROY you’d pass :destroy.

info1

(0) Additional message-specific information (wParam value).

info2

(0) Additional message-specific information (lParam value).

Return value

The return value of the SendMessage() function.

Raises

Au3Error

Window not found.

Errno::EACCES

Windows’s security policy blocked the function call.

Example

win.send_message(:destroy) #Immediately destroys a window. No chance to save.

You can find the additional paramters needed for each message at the Windows API docs at MSDN. I recommand you to query the search function with something like “WM_PAINT” if you want to know more about WM_PAINT.



234
235
236
237
238
239
240
241
242
 
# File 'lib/AutoItX3/window/send_message.rb', line 234

def send_message(msg, info1 = 0, info2 = 0)
  Window.functions[__method__] ||= Win32::API.new("SendMessage", 'LILL', 'L', "user32")
  
  raise_unfound unless exists?
  msg = Messages.const_get(:"WM_#{msg.to_s.upcase}") if msg.kind_of? Symbol
  ret = Window.functions[__method__].call(self.to_i, msg, info1, info2)
  Kernel.raise(Errno::EACCES, "The Windows UIPI blocked your function call.") if Window.functions[:get_last_error].call == 5
  ret
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.

Parameters

val

true or false.

Return value

The argument passed.

Example

win.set_on_top = true



513
514
515
516
517
 
# File 'lib/AutoItX3/window.rb', line 513

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

Checks a window’s state. You shouldn’t use this function, use #exists?, visible?, #enabled?, #active?, #minimized? and #maximized? instead.

Return value

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.

Raises

Au3Error

Window not found.

Example

#Check for visibility
p(win.state & 2) #=> 2 #visible
p(win.state & 2) #=> 0 #invisible



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

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 to a specific state like “maximized”.

Parameters

val

The state the window should be set to. One of the SW_* constants of this class.

Return value

The argument passed.

Example

#Mimize a window
win.state = AutoItX3::Window::SW_MINIMIZE
#Make it fullscreen
win.state = AutoItX3::Window::SW_MAXIMIZE



529
530
531
532
533
 
# File 'lib/AutoItX3/window.rb', line 529

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 statusbar’s text(s).

Parameters

part

(1) The part of the statusbar to read, a 1-based index.

Return value

The text read.

Raises

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.

Example

p win.statusbar_text #=> "Loading..."

Remarks

I couldn’t get this method to work with whatever window I tried. Suggestions?

Raises:



678
679
680
681
682
683
684
685
 
# File 'lib/AutoItX3/window.rb', line 678

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.

Return value

The window’s text. It doesn’t necassary make sense.

Example

#Used on an explorer window: 
p win.text #=> "Navigationsleiste\nAdresse: C:\\Users\\marvin_g\\Desktop\\Automations\\au3\\trunk\\lib\nlib\nHostwrapper f├╝r gemeinsame Orte\nShellView\nFolderView\nMen├╝leiste"
#Some windows just don't have any text. 
p win.text #=> ""



415
416
417
418
419
420
421
 
# File 'lib/AutoItX3/window.rb', line 415

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.

Return value

The window’s title.

Example

p win.title #=> "AutoItX Help"



431
432
433
434
435
436
437
 
# File 'lib/AutoItX3/window.rb', line 431

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.

Parameters

val

The new title.

Return value

The argument passed.

Example

win.title = "Use Ruby whenever you can"

Remarks

This does not change the internal @title instance variable, so you can use this with the advanced window mode; this has another issue, though. If you aren’t working in advanced window mode, you (pseudo) Ruby handle gets invalid, since it only references the window by title: 

irb(main):042:0> win.title = "xxx"
=> "xxx"
irb(main):043:0> win
AutoItX3::Au3Error: Unable to find a window with title 'lib' and text ''!
        from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
.rb:265:in `handle'
        from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
.rb:154:in `inspect'
irb(main):044:0> win2 = AutoItX3::Window.new("xxx")
=> <Window: xxx (00070388)>
irb(main):045:0> win2.title = "lib"
=> "lib"
irb(main):046:0> win2
AutoItX3::Au3Error: Unable to find a window with title 'xxx' and text ''!
        from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
.rb:265:in `handle'
        from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
.rb:154:in `inspect'
irb(main):047:0> win
=> <Window: lib (00070388)>
irb(main):048:0>



567
568
569
570
571
 
# File 'lib/AutoItX3/window.rb', line 567

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 actual handle of the window.

Return value

The window’s handle as an integer.

Example

p win.handle #=> 721996

Remarks

See also #handle.



173
174
175
 
# File 'lib/AutoItX3/window.rb', line 173

def to_i
  handle.to_i(16)
end

#to_s ⇒ Object

Returns the window’s title.

Return value

self‘s title by (the value of @title).

Example

puts win.to_s #=> Untitled - Notepad



162
163
164
 
# File 'lib/AutoItX3/window.rb', line 162

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 a window’s transparency.

Parameters

val

The opacity you want the window set to; a numeric value between 0 (compelety transparent) and 255 (opaque).

Return value

The argument passed.

Raises

NotImplementedError

You are using Windows Millenium or older which don’t support transparent windows.

Example

win.trans = 100

Remarks

Note that a window whose transparency is set to 0 doesn’t cause #visible? to return false.



588
589
590
591
592
593
594
 
# File 'lib/AutoItX3/window.rb', line 588

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

Checks wheather a window is visible or not.

Return value

Returns true if self is shown on the screen, false otherwise.

Raises

Au3Error

Window not found.

Example

p win.visible? #=> true

Returns:

  • (Boolean) 


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

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

#wait(timeout = 0) ⇒ Object

Waits for self to exist.

Parameters

timeout

(0) The time to wait for the window to appear, in seconds. If set to 0 (which is the default), waits infinitely.

Return value

true if the window was found, false if timeout was reached.

Example

win.wait
#Only for 10 seconds
puts "Window doesn't exist" unless win.wait(10)



606
607
608
 
# File 'lib/AutoItX3/window.rb', line 606

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).

Parameters

timeout

(0) The time to wait, in seconds. 0 means waiting infinitely.

Return value

true if the window has been activated, false if timeout was reached.

Example

win.wait_active
#Only for 10 seconds
puts "YOU HAVE TO CLICK THE WINDOW!!!!!" unless win.wait_active(10)



619
620
621
622
 
# File 'lib/AutoItX3/window.rb', line 619

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.

Parameters

timeout

(0) The time to wait, in seconds. 0 means to wait till doomsday.

Return value

true if the window was closed, false if timeout was reached.

Example

win.wait_close(10) #Wait for 10 seconds



631
632
633
634
 
# File 'lib/AutoItX3/window.rb', line 631

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.

Parameters

timeout

(0) The time to wait, in seconds. 0 means waiting infinitely.

Return value

true if the window has lost the input focus, false if timeout was reached.

Example

win.wait_not_active(10) #Wait for 10 seconds



643
644
645
646
 
# File 'lib/AutoItX3/window.rb', line 643

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