Class: AutoItX3::Control

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

Overview

This is the superclass for all controls. If you don’t find a subclass of Control that matches your specific control, you can use the Control class itself (and if you call Window#focused_control, you will have to use it, since that method retuns a Control and not a subclass).

Direct Known Subclasses

Button, Edit, ListBox, ListView, TabBook, TreeView

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(title, text, control_id) ⇒ Control

Creates a new Control object.

Parameters

title

The title of the window containing the control.

text

The text of the window containing the control Set to “” (empty string) if you don’t care about it.

control_id

The ID of the control. You can also use the name of the control in combination with the occurence number of it, like “Edit1” and “Edit2”.

Return value

A brand new Control instance.

Raises

Au3Error

The control or the window doesn’t exist.

Example

#Get the edit control of the "Run" dialog: 
ctrl = AutoItX3::Control.new("Run", "", "Edit1")



61
62
63
64
65
66
 
# File 'lib/AutoItX3/control.rb', line 61

def initialize(title, text, control_id)
  @title = title
  @text = text
  @c_id = control_id.to_s
  visible? #Raises an error if the control doesn't exist
end

Class Method Details

.from_control(ctrl) ⇒ Object

Generates a control by using another control.

Parameters

ctrl

The control to transform.

Return value

A new instance of a subclass of Control.

Remarks & Example

This function is meant to be used with subclasses of Control, so you can do things like this: 

#...
ctrl = window.focused_control #This returns a Control instance
#If you're sure it's an Edit, transform it into one: 
ctrl = AutoItX3::Edit.from_control(ctrl)
p ctrl.lines

Raises:

  • (ArgumentError) 


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

def from_control(ctrl)
  raise(ArgumentError, "Argument has to be a Control!") unless ctrl.kind_of? Control
  new(ctrl.instance_eval{@title}, ctrl.instance_eval{@text}, ctrl.instance_eval{@c_id})
end

.functions ⇒ Object

:nodoc:



21
22
23
 
# File 'lib/AutoItX3/control.rb', line 21

def functions # :nodoc:
  @functions
end

.functions=(hsh) ⇒ Object

:nodoc:



25
26
27
 
# File 'lib/AutoItX3/control.rb', line 25

def functions=(hsh) # :nodoc:
  @functions = hsh
end

Instance Method Details

#click(button = "Primary", clicks = 1, x = INTDEFAULT, y = INTDEFAULT) ⇒ Object

Clicks self with the given mouse button.

Parameters

button

("Primary")The button to click with.

clicks

(1) The number of clicks.

x

(INTDEFAULT) The X-coordinate to click at. Middle if left out.

y

(INTDEFAULT) The Y-coordinate to click at. Middle if left out.

Return value

nil.

Raises

Au3Error

Couldn’t click the control.

Example

#Click with the left (or if left-handed mouse, right) button
ctrl.click
#Click with the secondary button
ctrl.click("Secondary")
#Double click
ctrl.click("Primary", 2)



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

def click(button = "Primary", clicks = 1, x = INTDEFAULT, y = INTDEFAULT)
  Control.functions[__method__] ||= AU3_Function.new("ControlClick", 'SSSSLLL', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide, button.wide, clicks, x, y)
  if res == 0
    raise(Au3Error, "Could not click control '#{@c_id}' in '#{@title}' for some reason!")
  end
  nil
end

#disable ⇒ Object

Disables (“grays out”) self.

Return value

nil.

Raises

Au3Error

Failed to disable the control.

Example

ctrl.disable



101
102
103
104
105
106
107
108
 
# File 'lib/AutoItX3/control.rb', line 101

def disable
  Control.functions[__method__] ||= AU3_Function.new("ControlDisable", 'SSS', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide)
  if res == 0
    raise(Au3Error, "Could not disable control '#{@c_id}' in '#{@title}'!")
  end
  nil
end

#enable ⇒ Object

Enables self (i.e. make it accept user actions).

Return value

nil.

Raises

Au3Error

Couldn’t enable the control.

Example

ctrl.enable



117
118
119
120
121
122
123
124
 
# File 'lib/AutoItX3/control.rb', line 117

def enable
  Control.functions[__method__] ||= AU3_Function.new("ControlEnable", 'SSS', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide)
  if res == 0
    raise(Au3Error, "Could not enable control '#{@c_id}' in '#{@title}'!")
  end
  nil
end

#enabled? ⇒ Boolean

Returns true if a control can interact with the user (i.e. it’s not “grayed out”).

Return value

true or false.

Raises

Au3Error

Control or window not found.

Example

p ctrl.enabled? #=> true
ctrl.disable
p ctrl.enabled? #=> false
ctrl.enable
p ctrl.enabled? #=> true

Returns:

  • (Boolean) 


332
333
334
 
# File 'lib/AutoItX3/control.rb', line 332

def enabled?
  send_command_to_control("IsEnabled").to_i == 1
end

#focus ⇒ Object

Gives the input focus to self.

Return value

nil.

Raises

Au3Error

Couldn’t get the input focus.

Example

ctrl.focus



133
134
135
136
137
138
139
140
 
# File 'lib/AutoItX3/control.rb', line 133

def focus
  Control.functions[__method__] ||= AU3_Functino.new("ControlFocus", 'SSS', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide)
  if res == 0
    raise(Au3Error, "Could not focus control '#{@c_id}' in '#{@title}!")
  end
  nil
end

#handle ⇒ Object

Returns the internal window handle of self.

Return value

The handle of self as a hexadecimal string.

Example

hwnd = ctrl.handle.to_i(16)

Remarks

The handle can be used in advanced window mode or directly in Win32 API calls (but you have to call #to_i(16) on the string then).



151
152
153
154
155
156
157
158
 
# File 'lib/AutoItX3/control.rb', line 151

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

#hide ⇒ Object

Hides self.

Return value

nil.

Example

ctrl.hide

Remarks

“Hidings” means to make a control completely invisible. If you just want it to refuse user input, use #disable.



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

def hide
  Control.functions[__method__] ||= AU3_Function.new("ControlHide", 'SSS', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide)
  raise_unfound if res == 0
  nil
end

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

Moves a control and optionally resizes it.

Parameters

x

The goal X coordinate.

y

The goal Y coordinate.

width

(-1) The goal width.

height

(-1) The goal height.

Return value

nil.

Raises

Au3Error

Control or window not found.

Example

ctrl.move(100, 100)
#Move to (100|100) and resize
ctrl.move(100, 100, 500, 500)

Remarks

If you move or resize a control, the visually shown control may not change, but if you try to click on it after moving it away, you will get to know that it isn’t there anymore.



232
233
234
235
236
237
 
# File 'lib/AutoItX3/control.rb', line 232

def move(x, y, width = -1, height = -1)
  Control.functions[__method__] ||= AU3_Function.new("ControlMove", 'SSSLLLL', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide, x, y, width, height)
  raise_unfound if res == 0
  nil
end

#rect ⇒ Object

Gets the control’s bounding rectangle.

Return value

A 4-element array of form [ x , y , width , height ].

Raises

Au3Error

Control or window not found.

Example

p ctrl.rect #=> [66, 72, 297, 17]



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/AutoItX3/control.rb', line 167

def rect
  Control.functions[:c_x] ||= AU3_Function.new("ControlGetPosX", 'SSS', 'L')
  Control.functions[:c_y] ||= AU3_Function.new("ControlGetPosY", 'SSS', 'L')
  Control.functions[:c_width] ||= AU3_Function.new("ControlGetPosWidth", 'SSS', 'L')
  Control.functions[:c_height] ||= AU3_Function.new("ControlGetPosHeight", 'SSS', 'L')
  
  params = [@title.wide, @text.wide, @c_id.wide]
  rectangle = [
    Control.functions[:c_x].call(*params), 
    Control.functions[:c_y].call(*params), 
    Control.functions[:c_width].call(*params), 
    Control.functions[:c_height].call(*params)
  ]
  raise_unfound if AutoItX3.last_error == 1
  rectangle
end

#send_command_to_control(command, arg = "") ⇒ Object

Sends a command to a control. You won’t need to use this method, since all commands are wrapped into methods. It’s only used internally.



297
298
299
300
301
302
303
304
 
# File 'lib/AutoItX3/control.rb', line 297

def send_command_to_control(command, arg = "")
  Control.functions[__method__] ||= AU3_Function.new("ControlCommand", 'SSSSSPI')
  buffer = " " * BUFFER_SIZE
  buffer.wide!
  Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide, command.wide, arg.to_s.wide, buffer, BUFFER_SIZE - 1)
  raise_unfound if AutoItX3.last_error == 1
  buffer.normal.strip
end

#send_keys(str, flag = 0) ⇒ Object

Simulates user input to a control.

Parameters

str

The input string to simulate.

flag

(0) If set to 1, escape sequences in braces { and } are ignored.

Return value

nil.

Raises

Au3Error

Control or window not found.

Example

#Send some keystrokes
ctrl.send_keys("Abc")
#Send some keys with escape sequences
ctrl.send_keys("Ab{ESC}c")
#Ignore the escape sequences
ctrl.send_keys("Ab{ESC}c", 1)



254
255
256
257
258
259
 
# File 'lib/AutoItX3/control.rb', line 254

def send_keys(str, flag = 0)
  Control.functions[__method__] ||= AU3_Function.new("ControlSend", 'SSSSI', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide, str.wide, flag)
  raise_unfound if res == 0
  nil
end

#show ⇒ Object

Shows a hidden control.

Return value

nil.

Example

ctrl.show

Remarks

This doesn’t enable user input, use #enable for that purpose.



288
289
290
291
292
293
 
# File 'lib/AutoItX3/control.rb', line 288

def show
  Control.functions[__method__] ||= AU3_Function.new("ControlShow", 'SSS', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide)
  raise_unfound if res == 0
  nil
end

#text ⇒ Object

Returns the self‘s text.

Return value

The text value of self.

Raises

Au3Error

Control or window not found.

Example

puts ctrl.text #=> regedit



191
192
193
194
195
196
197
198
 
# File 'lib/AutoItX3/control.rb', line 191

def text
  Control.functions[__method__] ||= AU3_Function.new("ControlGetText", 'SSSPI')
  buffer = " " * BUFFER_SIZE
  buffer.wide!
  Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide, buffer, BUFFER_SIZE - 1)
  raise_unfound if AutoItX3.last_error == 1
  buffer.normal.strip
end

#text=(text) ⇒ Object

Sets the text of a control directly.

Parameters

text

The text to set.

Return value

The text argument.

Raises

Au3Error

Control or window not found.

Example

ctrl.text = "My awesome text"

Remarks

The difference to #send_keys is that some controls doesn’t allow the user to type text into (labels for example). These control’s text can be set by using this method, but note that escape sequences aren’t supported here.



274
275
276
277
278
279
 
# File 'lib/AutoItX3/control.rb', line 274

def text=(text)
  Control.functions[__method__] ||= AU3_Function.new("ControlSetText", 'SSSS', 'L')
  res = Control.functions[__method__].call(@title.wide, @text.wide, @c_id.wide, text.wide)
  raise_unfound if res == 0
  text
end

#visible? ⇒ Boolean

Returns wheather or not a control is visible.

Return value

true or false.

Raises

Au3Error

Control or window not found.

Example

p ctrl.visible? #=> true
ctrl.hide
p ctrl.visible? #=> false
ctrl.show
p ctrl.visible #=> true

Returns:

  • (Boolean) 


317
318
319
 
# File 'lib/AutoItX3/control.rb', line 317

def visible?
  send_command_to_control("IsVisible").to_i == 1
end