vapir-common 1.7.2 → 1.8.0

data/lib/vapir-common/container.rb

@@ -34,14 +34,14 @@ module Vapir
         end
       end
       extra=extra_for_contained.merge(:index => index)
-      case other[:locate]
-      when :assert, true, false
-        element=klass.new(how, what, extra.merge(:locate => other[:locate]))
-      when :nil_unless_exists
+      extra.merge!(other[:extra]) if other[:extra]
+      if !other.key?(:locate)
+        element=klass.new(how, what, extra)
+      elsif other[:locate]==:nil_unless_exists
         element=klass.new(how, what, extra.merge(:locate => true))
         element.exists? ? element : nil
       else
-        raise ArgumentError, "Unrecognized value given for :locate: #{other[:locate].inspect} (#{other[:locate].class})"
+        element=klass.new(how, what, extra.merge(:locate => other[:locate]))
       end
     end
     
@@ -52,7 +52,11 @@ module Vapir
     def normalize_how_what_index(first, second, klass)
       case first
       when nil
-        raise Vapir::Exception::MissingWayOfFindingObjectException, "no first argument (how) was given!"
+        if second==nil
+          how, what, index = nil, nil, nil
+        else
+          raise Vapir::Exception::MissingWayOfFindingObjectException, "first argument ('how') was nil but second argument ('what') was given as #{second.inspect}"
+        end
       when Hash
         how=:attributes
         what=first.dup
@@ -74,8 +78,8 @@ module Vapir
             else
               raise Vapir::Exception::MissingWayOfFindingObjectException, "Cannot search using arguments #{first.inspect} (#{first.class}) and #{second.inspect} (#{second.class})"
             end
-          elsif first==:index # this is different because the index number doesn't go in the 'what'
-            how=first
+          elsif first==:index # index isn't a real 'how' 
+            how=nil
             what=nil
             index=second
           else
@@ -98,15 +102,9 @@ module Vapir
     # asserts that this element exists - optionally, takes a block, and other calls to assert_exists
     # over the course of the block will not cause redundant assertions. 
     def assert_exists(options={})
-      was_asserting_exists=@asserting_exists
-      if (!@asserting_exists || options[:force])
-        locate!
-      end
-      @asserting_exists=true
-      begin
-        if block_given?
-          result=yield
-        end
+      # yeah, this line is an unreadable mess, but I have to skip over it so many times debugging that it's worth just sticking it on one line 
+      (was_asserting_exists=@asserting_exists); (locate! if !@asserting_exists || options[:force]); (@asserting_exists=true)
+      begin; result=yield if block_given?
       ensure
         @asserting_exists=was_asserting_exists
       end
@@ -115,26 +113,42 @@ module Vapir
     public
     # catch exceptions that indicate some failure of something existing. 
     # 
-    # takes an option, :handle, which indicates how the method should handle an 
-    # encountered exception. 
-    # :handle may be one of:
-    # * :ignore (default) - the exception is ignored and nil is returned. 
-    # * :raise - the exception is raised (same as if this method weren't used at all). 
-    # * :return - returns the exception which was raised. 
-    # * Proc, Method - the proc or method is called with the exception as an argument. 
+    # takes an options hash:
+    # - :handle indicates how the method should handle an encountered exception. value may be:
+    #   - :ignore (default) - the exception is ignored and nil is returned. 
+    #   - :raise - the exception is raised (same as if this method weren't used at all). 
+    #   - :return - returns the exception which was raised. 
+    #   - Proc, Method - the proc or method is called with the exception as an argument. 
+    # - :assert_exists causes the method to check existence before yielding to the block. 
+    #   value may be:
+    #   - :force (default) - assert_exists(:force => true) is called so that existence is checked 
+    #     even if we're inside an assert_exists block already. this is the most common case, since
+    #     this method is generally used when the element may have recently stopped existing.
+    #   - true - assert_exists is called (without the :force option)
+    #   - false - assert_exists is not called. 
     #
     # If no exception was raised, then the result of the give block is returned. 
     #--
     # this may be overridden elsewhere to deal with any other stuff that indicates failure to exist, as it is
-    # to catch WIN32OLERuntimeErrors. 
+    # to catch WIN32OLERuntimeErrors for Vapir::IE. 
     def handling_existence_failure(options={})
-      options=handle_options(options, :handle => :ignore)
+      options=handle_options(options, {:assert_exists => :force}, [:handle])
       begin
+        case options[:assert_exists]
+        when true
+          assert_exists
+        when :force
+          assert_exists(:force => true)
+        when false, nil
+        else
+          raise ArgumentError, "option :assert_exists should be true, false, or :force; got #{options[:assert_exists].inspect}"
+        end
         yield
       rescue Vapir::Exception::ExistenceFailureException
-        handle_existence_failure($!, options)
+        handle_existence_failure($!, options.reject{|k,v| ![:handle].include?(k) })
       end
     end
+    alias base_handling_existence_failure handling_existence_failure # :nodoc:
     private
     # handles any errors encountered by #handling_existence_failure (either the
     # common one or a browser-specific one) 
@@ -155,13 +169,81 @@ module Vapir
     end
     public
     
-    def default_extra_for_contained
+    def base_extra_for_contained
       extra={:container => self}
       extra[:browser]= browser if respond_to?(:browser)
       extra[:page_container]= page_container if respond_to?(:page_container)
       extra
     end
-    alias extra_for_contained default_extra_for_contained
+    alias extra_for_contained base_extra_for_contained
+
+    # returns an array of text nodes below this element in the DOM heirarchy which are visible - 
+    # that is, their parent element is visible. 
+    def visible_text_nodes
+      # TODO: needs tests 
+      assert_exists do
+        recurse_text_nodes=ycomb do |recurse|
+          proc do |node, parent_visibility|
+            case node.nodeType
+            when 1, 9 # TODO: name a constant ELEMENT_NODE, rather than magic number 
+              style= node.nodeType==1 ? base_element_class.element_object_style(node, document_object) : nil
+              our_visibility = style && (visibility=style.invoke('visibility'))
+              unless our_visibility && ['hidden', 'collapse', 'visible'].include?(our_visibility=our_visibility.strip.downcase)
+                our_visibility = parent_visibility
+              end
+              display = style && style.invoke('display')
+              if display && display.strip.downcase=='none'
+                []
+              else
+                Vapir::Element.object_collection_to_enumerable(node.childNodes).inject([]) do |result, child_node|
+                  result + recurse.call(child_node, our_visibility)
+                end
+              end
+            when 3 # TODO: name a constant TEXT_NODE, rather than magic number 
+              if parent_visibility && ['hidden','collapse'].include?(parent_visibility.downcase)
+                []
+              else
+                [node.data]
+              end
+            else
+              #Kernel.warn("ignoring node of type #{node.nodeType}")
+              []
+            end
+          end
+        end
+  
+        # determine the current visibility and display. TODO: this is copied/adapted from #visible?; should DRY 
+        element_to_check=containing_object
+        real_visibility=nil
+        while element_to_check #&& !element_to_check.instanceof(nsIDOMDocument)
+          if (style=base_element_class.element_object_style(element_to_check, document_object))
+            # only pay attention to the innermost definition that really defines visibility - one of 'hidden', 'collapse' (only for table elements), 
+            # or 'visible'. ignore 'inherit'; keep looking upward. 
+            # this makes it so that if we encounter an explicit 'visible', we don't pay attention to any 'hidden' further up. 
+            # this style is inherited - may be pointless for firefox, but IE uses the 'inherited' value. not sure if/when ff does.
+            if real_visibility==nil && (visibility=style.invoke('visibility'))
+              visibility=visibility.strip.downcase
+              if ['hidden', 'collapse', 'visible'].include?(visibility)
+                real_visibility=visibility
+              end
+            end
+            # check for display property. this is not inherited, and a parent with display of 'none' overrides an immediate visibility='visible' 
+            display=style.invoke('display')
+            if display && (display=display.strip.downcase)=='none'
+              # if display is none, then this element is not visible, and thus has no visible text nodes underneath. 
+              return []
+            end
+          end
+          element_to_check=element_to_check.parentNode
+        end
+        recurse_text_nodes.call(containing_object, real_visibility)
+      end
+    end
+    # returns an visible text inside this element by concatenating text nodes below this element in the DOM heirarchy which are visible.
+    def visible_text
+      # TODO: needs tests 
+      visible_text_nodes.join('')
+    end
 
     # Checks if this container's text includes the given regexp or string. 
     # Returns true if the container's #text matches the given String or Regexp; otherwise false. 
@@ -181,7 +263,29 @@ module Vapir
       end
     end
     alias contains_text contains_text?
+    
+    # this is defined on each class to reflect the browser's particular implementation. 
+    def element_object_style(element_object, document_object)
+      base_element_class.element_object_style(element_object, document_object)
+    end
+    private :element_object_style
 
+    # for a common module, such as a TextField, returns an elements-specific class (such as
+    # Firefox::TextField) that inherits from the base_element_class of self. That is, this returns
+    # a sibling class, as it were, of whatever class inheriting from Element is instantiated.
+    def element_class_for(common_module)
+      element_class=nil
+      ObjectSpace.each_object(Class) do |klass|
+        if klass < common_module && klass <= base_element_class && (!element_class || element_class < klass)
+          element_class= klass
+        end
+      end
+      unless element_class
+        raise RuntimeError, "No class found that inherits from both #{common_module} and #{base_element_class}"
+      end
+      element_class
+    end
+    
     # shows the available objects on the current container.
     # This is usually only used for debugging or writing new test scripts.
     # This is a nice feature to help find out what HTML objects are on a page
@@ -195,11 +299,37 @@ module Vapir
     def show_all_objects(write_to=$stdout)
       # this used to reject tagNames 'br', 'hr', 'doctype', 'meta', and elements with no tagName
       elements.map do |element| 
-        element=element.to_factory
+        element=element.to_subtype
         write_to.write element.to_s+"\n"
         write_to.write '-'*42+"\n"
         element
       end
     end
+    module WatirContainerConfigCompatibility
+      def type_keys
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #type_keys is deprecated; please use the new config framework with config.type_keys"
+        end
+        config.type_keys
+      end
+      def type_keys=(arg) # deprecate
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #type_keys= is deprecated; please use the new config framework with config.type_keys="
+        end
+        config.type_keys= arg
+      end
+      def typingspeed
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #typingspeed is deprecated; please use the new config framework with config.typing_interval"
+        end
+        config.typing_interval
+      end
+      def typingspeed=(arg)
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #typingspeed= is deprecated; please use the new config framework with config.typing_interval="
+        end
+        config.typing_interval=arg
+      end
+    end
   end
 end

data/lib/vapir-common/element.rb

@@ -1,394 +1,19 @@
 require 'vapir-common/element_collection'
 require 'set'
 require 'matrix'
+require 'vapir-common/element_class_and_module'
 
-class Module
-  def alias_deprecated(to, from)
-    define_method to do |*args|
-      Kernel.warn "DEPRECATION WARNING: #{self.class.name}\##{to} is deprecated. Please use #{self.class.name}\##{from}\n(called from #{caller.map{|c|"\n"+c}})"
-      send(from, *args)
-    end
-  end
-end
 module Vapir
-  # this module is for methods that should go on both common element modules (ie, TextField) as well
-  # as browser-specific element classes (ie, Firefox::TextField). 
-  module ElementClassAndModuleMethods
-    # takes an element_object (JsshObject or WIN32OLE), and finds the most specific class 
-    # that is < self whose specifiers match it. Returns an instance of that class using the given
-    # element_object. 
-    #
-    # second argument, extra, is passed as the 'extra' argument to the Element constructor (see its documentation). 
-    #
-    # if you give a different how/what (third and fourth arguments, optional), then those are passed
-    # to the Element constructor. 
-    def factory(element_object, extra={}, how=nil, what=nil)
-      curr_klass=self
-      # since this gets included in the Element modules, too, check where we are 
-      unless self.is_a?(Class) && self < Vapir::Element
-        raise TypeError, "factory was called on #{self} (#{self.class}), which is not a Class that is < Element"
-      end
-      if how
-        # use how and what as given
-      elsif what
-        raise ArgumentError, "'what' was given as #{what.inspect} (#{what.class}) but how was not given"
-      else
-        how=:element_object
-        what=element_object
-      end
-      ObjectSpace.each_object(Class) do |klass|
-        if klass < curr_klass
-          Vapir::ElementObjectCandidates.match_candidates([element_object], klass.specifiers, klass.all_dom_attr_aliases) do |match|
-            curr_klass=klass
-            break
-          end
-        end
-      end
-      curr_klass.new(how, what, extra)
-    end
-    
-    # takes any number of arguments, where each argument is either:
-    # - a symbol or strings representing a method that is the same in ruby and on the dom
-    # - or a hash of key/value pairs where each key is a dom attribute, and each value
-    #   is a is a corresponding ruby method name or list of ruby method names.
-    def dom_attr(*dom_attrs)
-      dom_attrs.each do |arg|
-        hash=arg.is_a?(Hash) ? arg : arg.is_a?(Symbol) || arg.is_a?(String) ? {arg => arg} : raise(ArgumentError, "don't know what to do with arg #{arg.inspect} (#{arg.class})")
-        hash.each_pair do |dom_attr, ruby_method_names|
-          ruby_method_names= ruby_method_names.is_a?(Array) ? ruby_method_names : [ruby_method_names]
-          class_array_append 'dom_attrs', dom_attr
-          ruby_method_names.each do |ruby_method_name|
-            dom_attr_locate_alias(dom_attr, ruby_method_name)
-            define_method ruby_method_name do
-              method_from_element_object(dom_attr)
-            end
-          end
-        end
-      end
-    end
-    
-    # creates aliases for locating by 
-    def dom_attr_locate_alias(dom_attr, alias_name)
-      dom_attr_aliases=class_hash_get('dom_attr_aliases')
-      dom_attr_aliases[dom_attr] ||= Set.new
-      dom_attr_aliases[dom_attr] << alias_name
-    end
-    
-    # dom_function is about the same as dom_attr, but dom_attr doesn't take arguments. 
-    # also, dom_function methods call #wait; dom_attr ones don't. 
-    def dom_function(*dom_functions)
-      dom_functions.each do |arg|
-        hash=arg.is_a?(Hash) ? arg : arg.is_a?(Symbol) || arg.is_a?(String) ? {arg => arg} : raise(ArgumentError, "don't know what to do with arg #{arg.inspect} (#{arg.class})")
-        hash.each_pair do |dom_function, ruby_method_names|
-          ruby_method_names= ruby_method_names.is_a?(Array) ? ruby_method_names : [ruby_method_names]
-          class_array_append 'dom_functions', dom_function
-          ruby_method_names.each do |ruby_method_name|
-            define_method ruby_method_name do |*args|
-              result=method_from_element_object(dom_function, *args)
-              wait
-              result
-            end
-          end
-        end
-      end
-    end
-    
-    # dom_setter takes arguments in the same format as dom_attr, but sends the given setter method (plus = sign)
-    # to the element object. eg, 
-    # module TextField
-    #   dom_setter :value
-    #   dom_setter :maxLength => :maxlength
-    # end
-    # the #value= method in ruby will send to #value= on the element object
-    # the #maxlength= method in ruby will send to #maxLength= on the element object (note case difference). 
-    def dom_setter(*dom_setters)
-      dom_setters.each do |arg|
-        hash=arg.is_a?(Hash) ? arg : arg.is_a?(Symbol) || arg.is_a?(String) ? {arg => arg} : raise(ArgumentError, "don't know what to do with arg #{arg.inspect} (#{arg.class})")
-        hash.each_pair do |dom_setter, ruby_method_names|
-          ruby_method_names= ruby_method_names.is_a?(Array) ? ruby_method_names : [ruby_method_names]
-          class_array_append 'dom_setters', dom_setter
-          ruby_method_names.each do |ruby_method_name|
-            define_method(ruby_method_name.to_s+'=') do |value|
-              element_object.send(dom_setter.to_s+'=', value)
-            end
-          end
-        end
-      end
-    end
-    
-    # defines an element collection method on the given element - such as SelectList#options
-    # or Table#rows. takes the name of the dom method that returns a collection
-    # of element objects, a ruby method name, and an element class - actually this is
-    # generally an Element module; this method goes ahead and finds the browser-specific
-    # class that will actually be instantiated. the defined method returns an 
-    # ElementCollection. 
-    def element_collection(dom_attr, ruby_method_name, element_class)
-      define_method ruby_method_name do
-        assert_exists do
-          ElementCollection.new(self, element_class_for(element_class), extra_for_contained.merge(:candidates => dom_attr))
-        end
-      end
-    end
-
-    # notes the given arguments to be inspected by #inspect and #to_s on each inheriting element. 
-    # each argument may be a symbol, in which case the corresponding method is called on the element, or 
-    # a hash, with the following keys:
-    # - :label - how the the attribute is labeled in the string returned by #inspect or #to_s. 
-    #            should be a string or symbol (but anything works; #to_s is called on the label). 
-    # - :value - can be one of:
-    #   - String starting with '@' - assumes this is an instance variable; gets the value of that instance variable
-    #   - Symbol - assumes it is a method name, gives this to #send on the element. this is most commonly-used. 
-    #   - Proc - calls the proc, giving this element as an argument. should return a string. #to_s is called on its return value.
-    #   - anything else - just assumes that that is the value that is wanted in the string. 
-    #     (see Element#attributes_for_stringifying)
-    # - :if - if defined, should be a proc that returns false/nil if this should not be included in the 
-    #   string, or anything else (that is, any value considered 'true') if it should. this element is passed
-    #   as an argument to the proc. 
-    def inspect_these(*inspect_these)
-      inspect_these.each do |inspect_this|
-        attribute_to_inspect=case inspect_this
-        when Hash
-          inspect_this
-        when Symbol
-          {:label => inspect_this, :value => inspect_this}
-        else
-          raise ArgumentError, "unrecognized thing to inspect: #{inspect_this} (#{inspect_this.class})"
-        end
-        class_array_append 'attributes_to_inspect', attribute_to_inspect
-      end
-    end
-    alias inspect_this inspect_these
-    # inspect_this_if(inspect_this, &block) is shorthand for 
-    # inspect_this({:label => inspect_this, :value => inspect_this, :if => block)
-    # if a block isn't given, the :if proc is the result of sending the inspect_this symbol to the element.
-    # if inspect_this isn't a symbol, and no block is given, raises ArgumentError. 
-    def inspect_this_if inspect_this, &block
-      unless inspect_this.is_a?(Symbol) || block
-        raise ArgumentError, "Either give a block, or specify a symbol as the first argument, instead of #{inspect_this.inspect} (#{inspect_this.class})"
-      end
-      to_inspect={:label => inspect_this, :value => inspect_this}
-      to_inspect[:if]= block || proc {|element| element.send(inspect_this) }
-      class_array_append 'attributes_to_inspect', to_inspect
-    end
-    
-    def class_array_append(name, *elements)
-=begin
-      name='@@'+name.to_s
-      unless self.class_variable_defined?(name)
-        class_variable_set(name, [])
-      end
-      class_variable_get(name).push(*elements)
-=end
-      name=name.to_s.capitalize
-      unless self.const_defined?(name)
-        self.const_set(name, [])
-      end
-      self.const_get(name).push(*elements)
-    end
-
-    def class_array_get(name)
-      # just return the value of appending nothing
-      class_array_append(name) 
-    end
-    def class_hash_merge(name, hash)
-      name=name.to_s.capitalize
-      unless self.const_defined?(name)
-        self.const_set(name, {})
-      end
-      self.const_get(name).merge!(hash)
-    end
-    def class_hash_get(name)
-      class_hash_merge(name, {})
-    end
-    def set_or_get_class_var(class_var, *arg)
-      if arg.length==0
-        class_variable_defined?(class_var) ? class_variable_get(class_var) : nil
-      elsif arg.length==1
-        class_variable_set(class_var, arg.first)
-      else
-        raise ArgumentError, "#{arg.length} arguments given; expected one or two. arguments were #{arg.inspect}"
-      end
-    end
-    def default_how(*arg)
-      set_or_get_class_var('@@default_how', *arg)
-    end
-    def add_container_method_extra_args(*args)
-      class_array_append('container_method_extra_args', *args)
-    end
-    def container_method_extra_args
-      class_array_get('container_method_extra_args')
-    end
-    def specifiers
-      class_array_get 'specifiers'
-    end
-    def container_single_methods
-      class_array_get 'container_single_methods'
-    end
-    def container_collection_methods
-      class_array_get 'container_collection_methods'
-    end
-
-    def parent_element_module(*arg)
-      defined_parent=set_or_get_class_var('@@parent_element_module', *arg)
-      defined_parent || (self==Watir::Element ? nil : Watir::Element)
-    end
-    def all_dom_attrs
-      super_attrs= parent_element_module ? parent_element_module.all_dom_attrs : []
-      super_attrs + class_array_get('dom_attrs')
-    end
-    def all_dom_attr_aliases
-      aliases=class_hash_get('dom_attr_aliases').dup
-      super_aliases= parent_element_module ? parent_element_module.all_dom_attr_aliases : {}
-      super_aliases.each_pair do |attr, alias_list|
-        aliases[attr] = (aliases[attr] || Set.new) + alias_list
-      end
-      aliases
-    end
-  end
-  module ElementHelper
-    def add_specifier(specifier)
-      class_array_append 'specifiers', specifier
-    end
-
-    def container_single_method(*method_names)
-      class_array_append 'container_single_methods', *method_names
-      element_module=self
-      method_names.each do |method_name|
-        Vapir::Element.module_eval do
-          # these methods (Element#parent_table, Element#parent_div, etc)
-          # iterate through parent nodes looking for a parent of the specified
-          # type. if no element of that type is found which is a parent of
-          # self, returns nil. 
-          define_method("parent_#{method_name}") do
-            element_class=element_class_for(element_module)
-            parentNode=element_object
-            while true
-              parentNode=parentNode.parentNode
-              unless parentNode && parentNode != document_object # don't ascend up to the document. #TODO/Fix - for IE, comparing WIN32OLEs doesn't really work, this comparison is pointless. 
-                return nil
-              end
-              matched=Vapir::ElementObjectCandidates.match_candidates([parentNode], element_class.specifiers, element_class.all_dom_attr_aliases)
-              if matched.size > 0
-                return element_class.new(:element_object, parentNode, extra_for_contained) # this is a little weird, passing extra_for_contained so that this is the container of its parent. 
-              end
-            end
-          end
-        end
-      end
-    end
-    def container_collection_method(*method_names)
-      class_array_append 'container_collection_methods', *method_names
-    end
-
-    include ElementClassAndModuleMethods
-    
-    def included(including_class)
-      including_class.send :extend, ElementClassAndModuleMethods
-      
-      # get Container modules that the including_class includes (ie, Vapir::Firefox::TextField includes the Vapir::Firefox::Container Container module)
-      container_modules=including_class.included_modules.select do |mod|
-        mod.included_modules.include?(Vapir::Container)
-      end
-  
-      container_modules.each do |container_module|
-        class_array_get('container_single_methods').each do |container_single_method|
-          # define both bang-methods (like #text_field!) and not (#text_field) with corresponding :locate option for element_by_howwhat
-          [ {:method_name => container_single_method, :locate => true}, 
-            {:method_name => container_single_method.to_s+'!', :locate => :assert},
-            {:method_name => container_single_method.to_s+'?', :locate => :nil_unless_exists},
-          ].each do |method_hash|
-            unless container_module.method_defined?(method_hash[:method_name])
-              container_module.module_eval do
-                define_method(method_hash[:method_name]) do |how, *what_args| # can't take how, what as args because blocks don't do default values so it will want 2 args
-                  #locate! # make sure self is located before trying contained stuff 
-                  what=what_args.shift # what is the first what_arg
-                  other_attribute_keys=including_class.container_method_extra_args
-                  if what_args.size>other_attribute_keys.length
-                    raise ArgumentError, "\##{method_hash[:method_name]} takes 1 to #{2+other_attribute_keys.length} arguments! Got #{([how, what]+what_args).map{|a|a.inspect}.join(', ')}}"
-                  end
-                  if what_args.size == 0
-                    other_attributes= nil
-                  else
-                    other_attributes={}
-                    what_args.each_with_index do |arg, i|
-                      other_attributes[other_attribute_keys[i]]=arg
-                    end
-                  end
-                  element_by_howwhat(including_class, how, what, :locate => method_hash[:locate], :other_attributes => other_attributes)
-                end
-              end
-            end
-          end
-        end
-        class_array_get('container_collection_methods').each do |container_multiple_method|
-          container_module.module_eval do
-            # returns an ElementCollection of Elements that are instances of the including class 
-            define_method(container_multiple_method) do
-              ElementCollection.new(self, including_class, extra_for_contained)
-            end
-          end
-          container_module.module_eval do
-            define_method('child_'+container_multiple_method.to_s) do
-              ElementCollection.new(self, including_class, extra_for_contained.merge(:candidates => :childNodes))
-            end
-            define_method('show_'+container_multiple_method.to_s) do |*io|
-              io=io.first||$stdout # io is a *array so that you don't have to give an arg (since procs don't do default args)
-              element_collection=ElementCollection.new(self, including_class, extra_for_contained)
-              io.write("There are #{element_collection.length} #{container_multiple_method}\n")
-              element_collection.each do |element|
-                io.write(element.to_s)
-              end
-            end
-            alias_deprecated "show#{container_multiple_method.to_s.capitalize}", "show_"+container_multiple_method.to_s
-          end
-        end
-      end
-
-      # copy constants (like Specifiers) onto classes when inherited
-      # this is here to set the constants of the Element modules below onto the actual classes that instantiate 
-      # per-browser (Vapir::IE::TextField, Vapir::Firefox::TextField, etc) so that calling #const_defined? on those 
-      # returns true, and so that the constants defined here clobber any inherited stuff from superclasses
-      # which is unwanted. 
-      self.constants.each do |const| # copy all of its constants onto wherever it was included
-        to_copy=self.const_get(const)
-        to_copy=to_copy.dup if [Hash, Array, Set].any?{|klass| to_copy.is_a?(klass) }
-        including_class.const_set(const, to_copy)
-      end
-      
-      # now the constants (above) have switched away from constants to class variables, pretty much, so copy those.
-      self.class_variables.each do |class_var|
-        to_copy=class_variable_get(class_var)
-        to_copy=to_copy.dup if [Hash, Array, Set].any?{|klass| to_copy.is_a?(klass) }
-        including_class.send(:class_variable_set, class_var, to_copy)
-      end
-      
-      class << including_class
-        def attributes_to_inspect
-          super_attrs=superclass.respond_to?(:attributes_to_inspect) ? superclass.attributes_to_inspect : []
-          super_attrs + class_array_get('attributes_to_inspect')
-        end
-        def all_dom_attrs
-          super_attrs=superclass.respond_to?(:all_dom_attrs) ? superclass.all_dom_attrs : []
-          super_attrs + class_array_get('dom_attrs')
-        end
-        def all_dom_attr_aliases
-          aliases=class_hash_get('dom_attr_aliases').dup
-          super_aliases=superclass.respond_to?(:all_dom_attr_aliases) ? superclass.all_dom_attr_aliases : {}
-          super_aliases.each_pair do |attr, alias_list|
-            aliases[attr] = (aliases[attr] || Set.new) + alias_list
-          end
-          aliases
-        end
-      end
-    end
-    
-  end
-
   # this is included by every Element. it relies on the including class implementing a 
   # #element_object method 
   # some stuff assumes the element has a defined @container. 
   module Element
     extend ElementHelper
+    include Configurable
+    def configuration_parent
+      @container ? @container.config : @browser ? @browser.config : browser_class.config
+    end
+
     add_specifier({}) # one specifier with no criteria - note that having no specifiers 
                       # would match no elements; having a specifier with no criteria matches any
                       # element.
@@ -456,9 +81,9 @@ module Vapir
     public
     
     dom_attr :id
-    inspect_this :how
+    inspect_this_if :how
     inspect_this_if(:what) do |element|
-      ![:element_object, :index].include?(element.how) # if how==:element_object, don't show the element object in inspect. if how==:index, what is nil. 
+      ![:element_object, nil].include?(element.how) # if how==:element_object, don't show the element object in inspect. if no how/what, don't show anything for them. 
     end
     inspect_this_if(:index) # uses the default 'if'; shows index if it's not nil 
     inspect_these :tag_name, :id
@@ -484,7 +109,6 @@ module Vapir
     attr_reader :index
     
     def html
-      Kernel.warn "#html is deprecated, please use #outer_html or #inner_html. #html currently returns #outer_html (note that it previously returned inner_html on firefox)\n(called from #{caller.map{|c|"\n"+c}})"
       outer_html
     end
 
@@ -496,7 +120,7 @@ module Vapir
     # after they've done their stuff
     def default_initialize(how, what, extra={})
       @how, @what=how, what
-      raise ArgumentError, "how (first argument) should be a Symbol, not: #{how.inspect}" unless how.is_a?(Symbol)
+      raise ArgumentError, "how (first argument) should be a Symbol, not: #{how.inspect}" unless how.is_a?(Symbol) || how==nil
       @extra=extra
       @index=begin
         valid_symbols=[:first, :last]
@@ -562,41 +186,21 @@ module Vapir
     end
     public
     # locates the element object for this element 
-    # 
-    # takes options hash. currently the only option is
-    # - :relocate => nil, :recursive, true, false 
-    #   - nil or not set (default): this Element is only relocated if the browser is updated (in firefox) or the WIN32OLE stops existing (IE). 
-    #   - :recursive: this element and its containers are relocated, recursively up to the containing browser. 
-    #   - false: no relocating is done even if the browser is updated or the element_object stops existing. 
-    #   - true: this Element is relocated. the container is relocated only if the browser is updated or the element_object stops existing. 
-    def locate(options={})
-      if options[:relocate]==nil && @element_object # don't override if it is set to false; only if it's nil, and don't set :relocate there's no @element_object (that's an initial locate, not a relocate) 
-        if @browser && @updated_at && @browser.respond_to?(:updated_at) && @browser.updated_at > @updated_at # TODO: implement this for IE; only exists for Firefox now. 
-          options[:relocate]=:recursive
-        elsif !element_object_exists?
-          options[:relocate]=true
-        end
-      end
-      container_locate_options={}
-      if options[:relocate]==:recursive
-        container_locate_options[:relocate]= options[:relocate]
-      end
-      if options[:relocate]
-        @element_object=nil
+    def locate
+      if element_object_exists?
+        return @element_object
       end
-      element_object_existed=!!@element_object
-      @element_object||= begin
+      new_element_object= begin
         case @how
         when :element_object
           assert_no_index
-          @element_object=@what # this is needed for checking its existence 
-          if options[:relocate] && !element_object_exists?
-            raise Vapir::Exception::UnableToRelocateException, "This #{self.class.name} was specified using #{how.inspect} and cannot be relocated."
+          if @element_object # if @element_object is already set, it must not exist, since we check #element_object_exists? above. 
+            raise Vapir::Exception::UnableToRelocateException, "This #{self.class.name} has stopped existing. Tried to relocate it, but it was specified using #{how.inspect} and cannot be relocated."
+          else
+            @what
           end
-          @what
         when :xpath
-          assert_container
-          @container.locate!(container_locate_options)
+          assert_container_exists
           unless @container.respond_to?(:element_object_by_xpath)
             raise Vapir::Exception::MissingWayOfFindingObjectException, "Locating by xpath is not supported on the container #{@container.inspect}"
           end
@@ -604,33 +208,41 @@ module Vapir
           assert_no_index
           by_xpath=@container.element_object_by_xpath(@what)
           match_candidates(by_xpath ? [by_xpath] : [], self.class.specifiers, self.class.all_dom_attr_aliases).first
+        when :css
+          assert_container_exists
+          candidate_match_at_index(@index, method(:match_candidates), @container.containing_object.querySelectorAll(@what), self.class.specifiers, self.class.all_dom_attr_aliases)
         when :label
           assert_no_index
           unless document_object
             raise "No document object found for this #{self.inspect} - needed to search by id for label from #{@container.inspect}"
           end
-          unless what.is_a?(Label)
-            raise "how=:label specified on this #{self.class}, but 'what' is not a Label! what=#{what.inspect} (#{what.class})"
+          label_element = case @what
+          when Label
+            @what.locate!
+            @what
+          when String, Regexp
+            page_container.label(:text, @what)
+          else
+            raise Vapir::Exception::MissingWayOfFindingObjectException, "This #{self.class} was specified as 'how'=:label; 'what' was expected to be a Label element or a String or Regexp to match label text. Given 'what'=#{@what.inspect} (#{@what.class})"
+          end
+          if label_element.exists?
+            by_label=document_object.getElementById(label_element.for)
           end
-          what.locate!(container_locate_options) # 'what' is not the container; our container is the label's container, but the options for locating should be the same. 
-          by_label=document_object.getElementById(what.for)
           match_candidates(by_label ? [by_label] : [], self.class.specifiers, self.class.all_dom_attr_aliases).first
         when :attributes
-          assert_container
-          @container.locate!(container_locate_options)
+          assert_container_exists
           specified_attributes=@what
           specifiers=self.class.specifiers.map{|spec| spec.merge(specified_attributes)}
           
           candidate_match_at_index(@index, method(:matched_candidates), specifiers, self.class.all_dom_attr_aliases)
-        when :index
+        when nil
+          assert_container_exists
           unless @what.nil?
-            raise ArgumentError, "'what' was specified, but when 'how'=:index, no 'what' is used (just extra[:index])"
-          end
-          unless @index
-            raise ArgumentError, "'how' was given as :index but no index was given"
+            raise ArgumentError, "'what' was specified, but 'how' was not given (is nil)"
           end
           candidate_match_at_index(@index, method(:matched_candidates), self.class.specifiers, self.class.all_dom_attr_aliases)
         when :custom
+          assert_container_exists
           # this allows a proc to be given as 'what', which is called yielding candidates, each being 
           # an instanted Element of this class. this might seem a bit odd - instantiating a bunch 
           # of elements in order to figure out which element_object to use in locating this one. 
@@ -638,29 +250,22 @@ module Vapir
           # the Elements that are yielded are instantiated by :element object which cannot be 
           # relocated. 
           #
-          # the alternative to this would be for the calling code to loop over the element collection
-          # for this class on the container - that is, instead of:
-          #   found_div=frame.divs.detect{|div| weird_criteria_for(div) }
-          # which can't be relocated - since element collections use :element object - you'd do
-          #   found_div=frame.div(:custom, proc{|div| weird_criteria_for(div) })
-          # this way, found_div can be relocated. yay! 
+          # this integrates with ElementCollection, where Enumerable methods #detect,
+          # #select, and #reject are overridden to use it. 
           # 
           # the proc should return true (that is, not false or nil) when it likes the given Element - 
           # when it matches what it expects of this Element. 
           candidate_match_at_index(@index, method(:matched_candidates), self.class.specifiers, self.class.all_dom_attr_aliases) do |candidate|
-            what.call(self.class.new(:element_object, candidate, @extra))
+            what.call(self.class.new(:element_object, candidate, @container.extra_for_contained))
           end
         else
           raise Vapir::Exception::MissingWayOfFindingObjectException, "Unknown 'how' given: #{@how.inspect} (#{@how.class}). 'what' was #{@what.inspect} (#{@what.class})"
         end
       end
-      if !element_object_existed && @element_object
-        @updated_at=Time.now
-      end
-      @element_object
+      @element_object=new_element_object
     end
-    def locate!(options={})
-      locate(options) || begin
+    def locate!
+      locate || begin
         klass=self.is_a?(Frame) ? Vapir::Exception::UnknownFrameException : Vapir::Exception::UnknownObjectException
         message="Unable to locate #{self.class}, using #{@how}"+(@what ? ": "+@what.inspect : '')+(@index ? ", index #{@index}" : "")
         message+="\non container: #{@container.inspect}" if @container
@@ -671,7 +276,7 @@ module Vapir
     public
     # Returns whether this element actually exists.
     def exists?
-      handling_existence_failure(:handle => proc { return false }) do
+      handling_existence_failure(:handle => proc { return false }, :assert_exists => false) do
         return !!locate
       end
     end
@@ -702,45 +307,40 @@ module Vapir
     #
     # For example, if we have a table, get its first element, and call #to_factory on it:
     #
-    # a_table=browser.tables.first
-    # => #<Vapir::IE::Table:0x071bc70c how=:index index=:first tagName="TABLE">
-    # a_element=a_table.elements.first
-    # => #<Vapir::IE::Element:0x071b856c how=:index index=:first tagName="TBODY" id="">
-    # a_element.to_factory
-    # => #<Vapir::IE::TableBody:0x071af78c how=:index index=:first tagName="TBODY" id="">
+    #  a_table=browser.tables.first
+    #  => #<Vapir::IE::Table:0x071bc70c index=:first tagName="TABLE">
+    #  a_element=a_table.elements.first
+    #  => #<Vapir::IE::Element:0x071b856c index=:first tagName="TBODY" id="">
+    #  a_element.to_factory
+    #  => #<Vapir::IE::TableBody:0x071af78c index=:first tagName="TBODY" id="">
     #
     # we get back a Vapir::TableBody. 
-    def to_factory
+    def to_subtype
       self.class.factory(element_object, @extra, @how, @what)
     end
+    alias to_factory to_subtype
 
     # takes a block. sets highlight on this element; calls the block; clears the highlight.
     # the clear is in an ensure block so that you can call return from the given block. 
-    # doesn't actually perform the highlighting if argument do_highlight is false. 
+    #
+    # takes an options hash; every argument is ignored except :highlight, which defaults to true; 
+    # if set to false then the highlighting won't actually happen, the block will just be called
+    # and its value returned. 
     #
     # also, you can nest these safely; it checks if you're already highlighting before trying
     # to set and subsequently clear the highlight. 
     #
-    # the block is called within an assert_exists block, so for methods that highlight, the
-    # assert_exists can generally be omitted from there. 
+    # the block is called within an #assert_exists block, so methods that highlight don't need to 
+    # also check existence as that'd be redundant. 
     def with_highlight(options={})
-      highlight_option_keys=[:color]
-      #options=handle_options(options, {:highlight => true}, highlight_option_keys)
-      options={:highlight => true}.merge(options)
-      highlight_options=options.reject{|(k,v)| !highlight_option_keys.include?(k) }
       assert_exists do
-        was_highlighting=@highlighting
-        if (!@highlighting && options[:highlight])
-          set_highlight(highlight_options)
-        end
-        @highlighting=true
-        begin
-          result=yield
+        # yeah, this line is an unreadable mess, but I have to skip over it so many times debugging that it's worth just sticking it on one line 
+        (options={:highlight => true}.merge(options)); (was_highlighting=@highlighting); (set_highlight(options) if !@highlighting && options[:highlight]); (@highlighting=true)
+        begin; result=yield
         ensure
           @highlighting=was_highlighting
           if !@highlighting && options[:highlight]
             handling_existence_failure do
-              assert_exists :force => true
               clear_highlight(options)
             end
           end
@@ -750,9 +350,6 @@ module Vapir
     end
     
     private
-    # The default color for highlighting objects as they are accessed.
-    DEFAULT_HIGHLIGHT_COLOR = "yellow"
-
     # Sets or clears the colored highlighting on the currently active element.
     # set_or_clear - should be 
     # :set - To set highlight
@@ -770,8 +367,7 @@ module Vapir
     end
 
     def set_highlight_color(options={})
-      #options=handle_options(options, :color => DEFAULT_HIGHLIGHT_COLOR)
-      options={:color => DEFAULT_HIGHLIGHT_COLOR}.merge(options)
+      options={:color => config.highlight_color}.merge(options)
       assert_exists do
         @original_color=element_object.style.backgroundColor
         element_object.style.backgroundColor=options[:color]
@@ -814,7 +410,9 @@ module Vapir
     def flash(options={})
       if options.is_a?(Fixnum)
         options={:count => options}
-        Kernel.warn "DEPRECATION WARNING: #{self.class.name}\#flash takes an options hash - passing a number is deprecated. Please use #{self.class.name}\#flash(:count => #{options[:count]})\n(called from #{caller.map{|c|"\n"+c}})"
+        if config.warn_deprecated
+          Kernel.warn_with_caller "DEPRECATION WARNING: #{self.class.name}\#flash takes an options hash - passing a number is deprecated. Please use #{self.class.name}\#flash(:count => #{options[:count]})"
+        end
       end
       options={:count => 10, :sleep => 0.05}.merge(options)
       #options=handle_options(options, {:count => 10, :sleep => 0.05}, [:color])
@@ -879,12 +477,6 @@ module Vapir
       end
       return true
     end
-    private
-    # this is defined on each class to reflect the browser's particular implementation. 
-    def element_object_style(element_object, document_object)
-      self.class.element_object_style(element_object, document_object)
-    end
-    public
     
     # returns an array of all text nodes below this element in the DOM heirarchy 
     def text_nodes
@@ -906,72 +498,6 @@ module Vapir
         recurse_text_nodes.call(recurse_text_nodes, element_object)
       end
     end
-    # returns an array of text nodes below this element in the DOM heirarchy which are visible - 
-    # that is, their parent element is visible. 
-    def visible_text_nodes
-      # TODO: needs tests 
-      assert_exists do
-        # define a nice recursive function to iterate down through the children 
-        recurse_text_nodes=proc do |rproc, e_obj, parent_visibility|
-          case e_obj.nodeType
-          when 1 # TODO: name a constant ELEMENT_NODE, rather than magic number 
-            style=element_object_style(e_obj, document_object)
-            our_visibility = style && (visibility=style.invoke('visibility'))
-            unless our_visibility && ['hidden', 'collapse', 'visible'].include?(our_visibility=our_visibility.strip.downcase)
-              our_visibility = parent_visibility
-            end
-            if (display=style.invoke('display')) && display.strip.downcase=='none'
-              []
-            else
-              object_collection_to_enumerable(e_obj.childNodes).inject([]) do |result, c_obj|
-                result + rproc.call(rproc, c_obj, our_visibility)
-              end
-            end
-          when 3 # TODO: name a constant TEXT_NODE, rather than magic number 
-            if ['hidden','collapse'].include?(parent_visibility)
-              []
-            else
-              [e_obj.data]
-            end
-          else
-            #Kernel.warn("ignoring node of type #{e_obj.nodeType}")
-            []
-          end
-        end
-  
-        # determine the current visibility and display. TODO: this is copied/adapted from #visible?; should DRY 
-        element_to_check=element_object
-        real_visibility=nil
-        while element_to_check #&& !element_to_check.instanceof(nsIDOMDocument)
-          if (style=element_object_style(element_to_check, document_object))
-            # only pay attention to the innermost definition that really defines visibility - one of 'hidden', 'collapse' (only for table elements), 
-            # or 'visible'. ignore 'inherit'; keep looking upward. 
-            # this makes it so that if we encounter an explicit 'visible', we don't pay attention to any 'hidden' further up. 
-            # this style is inherited - may be pointless for firefox, but IE uses the 'inherited' value. not sure if/when ff does.
-            if real_visibility==nil && (visibility=style.invoke('visibility'))
-              visibility=visibility.strip.downcase
-              if ['hidden', 'collapse', 'visible'].include?(visibility)
-                real_visibility=visibility
-              end
-            end
-            # check for display property. this is not inherited, and a parent with display of 'none' overrides an immediate visibility='visible' 
-            display=style.invoke('display')
-            if display && (display=display.strip.downcase)=='none'
-              # if display is none, then this element is not visible, and thus has no visible text nodes underneath. 
-              return []
-            end
-          end
-          element_to_check=element_to_check.parentNode
-        end
-        recurse_text_nodes.call(recurse_text_nodes, element_object, real_visibility)
-      end
-    end
-    # returns an visible text inside this element by concatenating text nodes below this element in the DOM heirarchy which are visible.
-    def visible_text
-      # TODO: needs tests 
-      visible_text_nodes.join('')
-    end
-
     # returns a Vector with two elements, the x,y 
     # coordinates of this element (its top left point)
     # from the top left edge of the window
@@ -1117,22 +643,6 @@ module Vapir
       end
     end
 
-    # for a common module, such as a TextField, returns an elements-specific class (such as
-    # Firefox::TextField) that inherits from the base_element_class of self. That is, this returns
-    # a sibling class, as it were, of whatever class inheriting from Element is instantiated.
-    def element_class_for(common_module)
-      element_class=nil
-      ObjectSpace.each_object(Class) do |klass|
-        if klass < common_module && klass < base_element_class
-          element_class= klass
-        end
-      end
-      unless element_class
-        raise RuntimeError, "No class found that inherits from both #{common_module} and #{base_element_class}"
-      end
-      element_class
-    end
-    
     module_function
     def object_collection_to_enumerable(object)
       if object.is_a?(Enumerable)