Class Watir::Element

  1. watir/lib/watir/element.rb
Parent: Object

Base class for html elements. This is not a class that users would normally access.

Included modules

  1. Watir::Exception
  2. Container
  3. Comparable

Constants

TO_S_SIZE = 14   number of spaces that separate the property from the value in the to_s method

External Aliases

disabled -> disabled?
< -> before?
  Return true if self is contained earlier in the html than other.
> -> after?
  Return true if self is contained later in the html than other.

Attributes

alt [R]
className [R] return the class name of the element raise an ObjectNotFound exception if the object cannot be found
class_name [R] return the class name of the element raise an ObjectNotFound exception if the object cannot be found
container [RW]
disabled [R] return whether the element is disabled
for [R] return the ID of the control that this label is associated with
href [R] return the url the link points to
html [R] Return the outer html of the object - see msdn.microsoft.com/workshop/author/dhtml/reference/properties/outerhtml.asp?frame=true
htmlFor [R] return the ID of the control that this label is associated with
id [R] return the id of the element
name [R] return the name of the element (as defined in html)
outerHTML [R] Return the outer html of the object - see msdn.microsoft.com/workshop/author/dhtml/reference/properties/outerhtml.asp?frame=true
src [R]
style [R] return the style of the element
title [R] return the title of the element
type [R] return the type of the element
uniqueNumber [R] return the unique COM number for the element
unique_number [R] return the unique COM number for the element
value [R] return the value of the element

Public class methods

new (ole_object)

ole_object - the ole object for the element being wrapped

[show source] 
# File watir/lib/watir/element.rb, line 13
    def initialize(ole_object)
      @o = ole_object
      @original_color = nil
    end

Public instance methods

<=> (other)
[show source] 
# File watir/lib/watir/element.rb, line 143
    def <=> other
      assert_exists
      other.assert_exists
      ole_object.sourceindex <=> other.ole_object.sourceindex
    end
activeObjectHighLightColor ()
[show source] 
# File watir/lib/watir/element.rb, line 161
    def activeObjectHighLightColor
      @container.activeObjectHighLightColor
    end
after_text (

return the text after the element

[show source] 
# File watir/lib/watir/element.rb, line 107
    def after_text # label only
      assert_exists
      begin
        ole_object.getAdjacentText("beforeBegin").strip
      rescue
                ''
      end
    end
assert_enabled ()
[show source] 
# File watir/lib/watir/element.rb, line 59
    def assert_enabled
      unless enabled?
        raise ObjectDisabledException, "object #{@how} and #{@what} is disabled"
      end
    end
assert_exists ()
[show source] 
# File watir/lib/watir/element.rb, line 52
    def assert_exists
      locate if respond_to?(:locate)
      unless ole_object
        raise UnknownObjectException.new(
          Watir::Exception.message_for_unable_to_locate(@how, @what))
      end
    end
attribute_value (attribute_name)

Get attribute value for any attribute of the element. Returns null if attribute doesn’t exist.

[show source] 
# File watir/lib/watir/element.rb, line 321
    def attribute_value(attribute_name)
      assert_exists
      return ole_object.getAttribute(attribute_name)
    end
before_text (

return the text before the element

[show source] 
# File watir/lib/watir/element.rb, line 97
    def before_text # label only
      assert_exists
      begin
        ole_object.getAdjacentText("afterEnd").strip
      rescue
                ''
      end
    end
click ()

This method clicks the active element. raises: UnknownObjectException if the object is not found ObjectDisabledException if the object is currently disabled

[show source] 
# File watir/lib/watir/element.rb, line 218
    def click
      click!
      @container.wait
    end
click! ()
[show source] 
# File watir/lib/watir/element.rb, line 232
    def click!
      assert_enabled
      
      highlight(:set)
      ole_object.click
      highlight(:clear)
    end
click_no_wait ()
[show source] 
# File watir/lib/watir/element.rb, line 223
    def click_no_wait
      assert_enabled
      
      highlight(:set)
      object = "#{self.class}.new(self, :unique_number, #{self.unique_number})"
      @page_container.eval_in_spawned_process(object + ".click!")
      highlight(:clear)
    end
document ()
[show source] 
# File watir/lib/watir/element.rb, line 129
    def document
      assert_exists
      return ole_object
    end
enabled? ()

Returns true if the element is enabled, false if it isn’t. 

raises: UnknownObjectException  if the object is not found
[show source] 
# File watir/lib/watir/element.rb, line 287
    def enabled?
      assert_exists
      return ! disabled
    end
exist? ()

Alias for exists?

exists? ()

Returns whether this element actually exists.

[show source] 
# File watir/lib/watir/element.rb, line 275
    def exists?
      begin
        locate if defined?(locate)
      rescue WIN32OLERuntimeError
        @o = nil
      end
      @o ? true: false
    end
fire_event (event)

Executes a user defined “fireEvent” for objects with JavaScript events tied to them such as DHTML menus. 

usage: allows a generic way to fire javascript events on page objects such as "onMouseOver", "onClick", etc.
raises: UnknownObjectException  if the object is not found
        ObjectDisabledException if the object is currently disabled
[show source] 
# File watir/lib/watir/element.rb, line 257
    def fire_event(event)
      assert_enabled
      
      highlight(:set)
      ole_object.fireEvent(event)
      @container.wait
      highlight(:clear)
    end
flash (number=10)

Flash the element the specified number of times. Defaults to 10 flashes.

[show source] 
# File watir/lib/watir/element.rb, line 242
    def flash number=10
      assert_exists
      number.times do
        highlight(:set)
        sleep 0.05
        highlight(:clear)
        sleep 0.05
      end
      nil
    end
focus ()

This method sets focus on the active element. 

raises: UnknownObjectException  if the object is not found
        ObjectDisabledException if the object is currently disabled
[show source] 
# File watir/lib/watir/element.rb, line 269
    def focus
      assert_enabled
      ole_object.focus
    end
inspect ()
[show source] 
# File watir/lib/watir/element.rb, line 26
    def inspect
      '#<%s:0x%x located=%s how=%s what=%s>' % [self.class, hash*2, !!ole_object, @how.inspect, @what.inspect]
    end
ole_object (

Return the ole object, allowing any methods of the DOM that Watir doesn’t support to be used.

[show source] 
# File watir/lib/watir/element.rb, line 19
    def ole_object # BUG: should use an attribute reader and rename the instance variable
      return @o
    end
ole_object= (o)
[show source] 
# File watir/lib/watir/element.rb, line 22
    def ole_object=(o)
      @o = o
    end
parent ()

Return the element immediately containing self.

[show source] 
# File watir/lib/watir/element.rb, line 135
    def parent
      assert_exists
      result = Element.new(ole_object.parentelement)
      result.set_container self
      result
    end
text ()

Return the innerText of the object Raise an ObjectNotFound exception if the object cannot be found

[show source] 
# File watir/lib/watir/element.rb, line 118
    def text
      assert_exists
      return ole_object.innerText.strip
    end
to_s ()

Display basic details about the object. Sample output for a button is shown. Raises UnknownObjectException if the object is not found. 

name      b4
type      button
id         b5
value      Disabled Button
disabled   true
[show source] 
# File watir/lib/watir/element.rb, line 184
    def to_s
      assert_exists
      return string_creator.join("\n")
    end
type_keys ()
[show source] 
# File watir/lib/watir/element.rb, line 157
                def type_keys
                        return @container.type_keys if @type_keys.nil? 
                        @type_keys
                end
typingspeed ()
[show source] 
# File watir/lib/watir/element.rb, line 154
    def typingspeed
      @container.typingspeed
    end
visible? ()

If any parent element isn’t visible then we cannot write to the element. The only realiable way to determine this is to iterate up the DOM element tree checking every element to make sure it’s visible.

[show source] 
# File watir/lib/watir/element.rb, line 296
    def visible?
      # Now iterate up the DOM element tree and return false if any
      # parent element isn't visible or is disabled.
      assert_exists
      object = @o
      while object
        begin
          if object.currentstyle.invoke('visibility') =~ /^hidden$/i
            return false
          end
          if object.currentstyle.invoke('display') =~ /^none$/i
            return false
          end
          if object.invoke('isDisabled')
            return false
          end
        rescue WIN32OLERuntimeError
        end
        object = object.parentElement
      end
      true
    end