Class: RAutomation::Window

Inherits:
Object
  • Object
show all
Includes:
Adapter::Helper
Defined in:
lib/rautomation/window.rb

Constant Summary collapse

@@wait_timeout =

Timeout for waiting until object exists. If the timeout exceeds then an RAutomation::WaitHelper::TimeoutError is raised.

60

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(locators) ⇒ Window

Note:

Refer to all possible locators in each Adapter documentation.

Note:

This constructor doesn't check for window's existance.

Note:

Only visible windows are supported.

Note:

If given locators include :hwnd then every other possible locator is ignored.

Creates the window object.

Possible window locators may depend of the used platform and adapter, but following examples will use :title, :class and :hwnd.

locators may also include a key called :adapter to change default adapter, which is dependent of the platform, to automate windows and their controls.

It is also possible to change the default adapter by using environment variable called RAUTOMATION_ADAPTER

Examples:

Use window with some title:

RAutomation::Window.new(:title => "some title")

Use window with Regexp title:

RAutomation::Window.new(:title => /some title/i)

Use window with handle (hwnd):

RAutomation::Window.new(:hwnd => 123456)

Use multiple locators, every locator will be matched (AND-ed) to the window:

RAutomation::Window.new(:title => "some title", :class => "IEFrame")

Parameters:

  • locators (Hash)

    locators for the window.


65
66
67
68
# File 'lib/rautomation/window.rb', line 65

def initialize(locators)
  @adapter = locators.delete(:adapter) || ENV["RAUTOMATION_ADAPTER"] && ENV["RAUTOMATION_ADAPTER"].to_sym || default_adapter
  @window = Adapter.const_get(normalize(@adapter)).const_get(:Window).new(self, locators)
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args)

Allows to execute specific Adapter methods not part of the public API.


219
220
221
# File 'lib/rautomation/window.rb', line 219

def method_missing(name, *args)
  @window.send(name, *args)
end

Instance Attribute Details

#adapter (readonly)

Currently used Adapter.


34
35
36
# File 'lib/rautomation/window.rb', line 34

def adapter
  @adapter
end

Class Method Details

.wait_timeoutInteger

Retrieve current timeout in seconds to wait before RAutomation::WaitHelper::TimeoutError is raised.

Returns:

  • (Integer)

    timeout in seconds


82
83
84
# File 'lib/rautomation/window.rb', line 82

def wait_timeout
  @@wait_timeout
end

.wait_timeout=(timeout)

Change the timeout to wait before RAutomation::WaitHelper::TimeoutError is raised.

Parameters:

  • timeout (Integer)

    in seconds.


76
77
78
# File 'lib/rautomation/window.rb', line 76

def wait_timeout=(timeout)
  @@wait_timeout = timeout
end

.windows(locators = {}) ⇒ Windows

Returns all windows.

Parameters:

  • locators (Hash) (defaults to: {})

    locators for the window.

Returns:

  • (Windows)

    all windows.


20
21
22
# File 'lib/rautomation/window.rb', line 20

def windows(locators = {})
  Windows.new(nil, locators)
end

Instance Method Details

#activate

Activates the Window, e.g. brings it to the top of other windows.


117
118
119
# File 'lib/rautomation/window.rb', line 117

def activate
  @window.activate
end

#active?Boolean

Checks if the window is active, e.g. on the top of other windows.

Returns:

  • (Boolean)

    true if the window is active, false otherwise.


123
124
125
# File 'lib/rautomation/window.rb', line 123

def active?
  @window.active?
end

#button(locators = {})

Note:

Refer to specific Adapter documentation for possible locator parameters.

Retrieves Button on the window.

Parameters:

  • locators (Hash) (defaults to: {})

    for the Button.

Raises:


205
206
207
208
# File 'lib/rautomation/window.rb', line 205

def button(locators={})
  wait_until_present
  Button.new(@window, locators)
end

#class_namesArray<String>

Returns all RAutomation::Window class names in a sorted array.

Returns:

Raises:


111
112
113
114
# File 'lib/rautomation/window.rb', line 111

def class_names
  wait_until_present
  @window.class_names
end

#close

Closes the window if it exists.


196
197
198
199
# File 'lib/rautomation/window.rb', line 196

def close
  return unless @window.exists?
  @window.close
end

#exists?Boolean Also known as: exist?

Checks if the window exists (does have to be visible).

Returns:

  • (Boolean)

    true if the window exists, false otherwise.


137
138
139
# File 'lib/rautomation/window.rb', line 137

def exists?
  @window.exists?
end

#hwndInteger

Returns handle of the window which is used internally for other methods.

Returns:

  • (Integer)

    handle of the window which is used internally for other methods.

Raises:


90
91
92
93
# File 'lib/rautomation/window.rb', line 90

def hwnd
  wait_until_present
  @window.hwnd
end

#maximize

Maximizes the window.

Raises:


160
161
162
163
# File 'lib/rautomation/window.rb', line 160

def maximize
  wait_until_present
  @window.maximize
end

#minimize

Minimizes the window.

Raises:


167
168
169
170
# File 'lib/rautomation/window.rb', line 167

def minimize
  wait_until_present
  @window.minimize
end

#minimized?Boolean

Checks if window is minimized.

Returns:

  • (Boolean)

    true if window is minimized, false otherwise.

Raises:


175
176
177
178
# File 'lib/rautomation/window.rb', line 175

def minimized?
  wait_until_present
  @window.minimized?
end

#pidInteger

Returns process identifier (PID) of the window.

Returns:

  • (Integer)

    process identifier (PID) of the window.

Raises:


97
98
99
100
# File 'lib/rautomation/window.rb', line 97

def pid
  wait_until_present
  @window.pid
end

#present?Boolean

Checks if the window exists and is visible.

Returns:

  • (Boolean)

    true if window exists and is visible, false otherwise


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

def present?
  exists? && visible?
end

#restore

Note:

If the window is minimized, makes it visible again.

Restores the window size and position.

Raises:


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

def restore
  wait_until_present
  @window.restore
end

#send_keys(*keys)

Sends keyboard keys to the window. Refer to specific Adapter documentation for all possible values.

Raises:


190
191
192
193
# File 'lib/rautomation/window.rb', line 190

def send_keys(*keys)
  wait_until_present
  @window.send_keys(keys)
end

#textString

Returns visible text of the Window.

Returns:

  • (String)

    visible text of the window.

Raises:


130
131
132
133
# File 'lib/rautomation/window.rb', line 130

def text
  wait_until_present
  @window.text
end

#text_field(locators = {})

Note:

Refer to specific Adapter documentation for possible locators parameters.

Retrieves TextField on the window.

Raises:


213
214
215
216
# File 'lib/rautomation/window.rb', line 213

def text_field(locators={})
  wait_until_present
  TextField.new(@window, locators)
end

#titleString

Returns title of the window.

Returns:

  • (String)

    title of the window.

Raises:


104
105
106
107
# File 'lib/rautomation/window.rb', line 104

def title
  wait_until_present
  @window.title
end

#visible?Boolean

Note:

Window is also visible, if it is behind other windows or minimized.

Checks if window is visible.

Returns:

  • (Boolean)

    true if window is visible, false otherwise.

Raises:


147
148
149
150
# File 'lib/rautomation/window.rb', line 147

def visible?
  wait_until_exists
  @window.visible?
end

#wait_until_exists


229
230
231
232
233
# File 'lib/rautomation/window.rb', line 229

def wait_until_exists
  WaitHelper.wait_until {exists?}
rescue WaitHelper::TimeoutError
  raise UnknownWindowException, "Window with locator #{@window.locators.inspect} doesn't exist!"
end

#wait_until_present


223
224
225
226
227
# File 'lib/rautomation/window.rb', line 223

def wait_until_present
  WaitHelper.wait_until {present?}
rescue WaitHelper::TimeoutError
  raise UnknownWindowException, "Window with locator #{@window.locators.inspect} doesn't exist or is not visible!"
end

#windows(locators = @window.locators) ⇒ Windows

Retrieves all windows with similar locators to the current window.

Parameters:

  • locators (Hash) (defaults to: @window.locators)

    locators for the window.

Returns:

  • (Windows)

    all windows matching current window's locators if no explicit locators specified or windows matching the specified locators.


29
30
31
# File 'lib/rautomation/window.rb', line 29

def windows(locators = @window.locators)
  Windows.new(nil, locators)
end