vapir-common 1.7.2 → 1.8.0

data/lib/vapir-common/elements/elements.rb

@@ -1,6 +1,6 @@
 require 'vapir-common/element'
 require 'vapir-common/container'
-
+require 'vapir-common/keycodes.rb'
 module Vapir
   module Frame
     extend ElementHelper
@@ -54,6 +54,23 @@ module Vapir
       !disabled
     end
     
+    module WatirInputElementConfigCompatibility
+      def requires_typing
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #requires_typing is deprecated; please use the new config framework with config.type_keys="
+        end
+        config.type_keys = true
+        self
+      end
+      def abhors_typing
+        if config.warn_deprecated
+          Kernel.warn_with_caller "WARNING: #abhors_typing is deprecated; please use the new config framework with config.type_keys="
+        end
+        config.type_keys = false
+        self
+      end
+    end
+    include WatirInputElementConfigCompatibility
   end
   module TextField
     extend ElementHelper
@@ -65,6 +82,8 @@ module Vapir
     container_single_method :text_field
     container_collection_method :text_fields
     
+    default_how :name
+    
     dom_attr :size, :maxLength => :maxlength
     alias_deprecated :getContents, :value
     
@@ -73,101 +92,138 @@ module Vapir
     # to be consistent with similar methods #set and #append, returns the new value, though this will always be a blank string. 
     # 
     # takes options: 
-    # :blur => true/false; whether or not to fire the onblur event when done.
-    # :highlight => true/false
+    # - :blur => true/false; whether or not to fire the onblur event when done.
+    # - :highlight => true/false
     #
-    #   Raises UnknownObjectException if the object can't be found
-    #   Raises ObjectDisabledException if the object is disabled
-    #   Raises ObjectReadOnlyException if the object is read only
+    # Raises UnknownObjectException if the object can't be found
+    # Raises ObjectDisabledException if the object is disabled
+    # Raises ObjectReadOnlyException if the object is read only
     def clear(options={})
       options={:blur => true, :change => true, :select => true, :focus => true}.merge(options)
       assert_enabled
       assert_not_readonly
       with_highlight(options) do
         if options[:focus]
+          assert_exists(:force => true)
           element_object.focus
           fire_event('onFocus')
-          assert_exists(:force => true)
         end
         if options[:select]
+          assert_exists(:force => true)
           element_object.select
           fire_event("onSelect")
-          assert_exists(:force => true)
         end
-        element_object.value = ''
-        fire_event :onKeyDown # TODO/fix - keyCode for 'delete' key 
-        assert_exists(:force => true)
-        fire_event :onKeyPress
-        assert_exists(:force => true)
-        fire_event :onKeyUp
-        assert_exists(:force => true)
+        handling_existence_failure do
+          with_key_down(:keyCode => KeyCodes[:delete]) do
+            assert_exists(:force => true)
+            element_object.value = ''
+          end
+        end
         if options[:change] && exists?
           fire_event("onChange")
         end
         if options[:blur] && exists?
           fire_event('onBlur')
         end
-        self.value
+        exists? ? self.value : nil
       end
     end
+    private
+    # todo: move to Element or something? this applies to hitting a key anywhere, really - not just TextFields. 
+    def with_key_down(fire_event_options={})
+      assert_exists(:force => true)
+      fire_event :onKeyDown, fire_event_options
+      yield if block_given?
+      assert_exists(:force => true)
+      fire_event :onKeyUp, fire_event_options
+    end
+    def type_key(key)
+      # the events created by the following are sort of wrong - for firefox, only one of keyCode 
+      # or charCode should ever be set. 
+      # for ie, keyCode is always set and charCode is ignored (there is no such property of IE events). 
+      # I could overload this method on a browser-specific basis, but having both set in ff seems to
+      # do no harm, so I will not do that for the moment. 
+      if PrintKeyCodes.key?(key)
+        with_key_down(:keyCode => PrintKeyCodes[key]) do
+          assert_exists(:force => true)
+          fire_event :onKeyPress, :keyCode => key.vapir_ord, :charCode => key.vapir_ord
+          yield if block_given?
+        end
+      elsif ShiftPrintKeyCodes.key?(key)
+        with_key_down(:keyCode => KeyCodes[:shift], :shiftKey => true) do
+          with_key_down(:keyCode => ShiftPrintKeyCodes[key], :shiftKey => true) do
+            assert_exists(:force => true)
+            fire_event :onKeyPress, :keyCode => key.vapir_ord, :charCode => key.vapir_ord, :shiftKey => true
+            yield if block_given?
+          end
+        end
+      else #?
+        with_key_down do
+          assert_exists(:force => true)
+          fire_event :onKeyPress, :keyCode => key.vapir_ord, :charCode => key.vapir_ord
+          yield if block_given?
+        end
+      end
+    end
+    public
     # Appends the specified string value to the contents of the text box.
     # 
     # returns the new value of the text field. this may not include all of what is given if there is a maxlength on the field. 
     #
     # takes options: 
-    # :blur => true/false; whether or not to file the onblur event when done.
-    # :highlight => true/false
+    # - :blur => true/false; whether or not to file the onblur event when done.
+    # - :highlight => true/false
     #
-    #   Raises UnknownObjectException if the object cant be found
-    #   Raises ObjectDisabledException if the object is disabled
-    #   Raises ObjectReadOnlyException if the object is read only
+    # Raises UnknownObjectException if the object cant be found
+    # Raises ObjectDisabledException if the object is disabled
+    # Raises ObjectReadOnlyException if the object is read only
     def append(value, options={})
       options={:blur => true, :change => true, :select => true, :focus => true}.merge(options)
       assert_enabled
       assert_not_readonly
       
       with_highlight(options) do
-        existing_value_chars=element_object.value.split(//)
-        new_value_chars=existing_value_chars+value.split(//)
-        #value_chars=value.split(//) # split on blank regexp (rather than iterating over each byte) for multibyte chars
+        existing_value_chars=element_object.value.split(//u)
+        new_value_chars=existing_value_chars+value.split(//u) # IE treats the string value is set to as utf8, and this is consistent with String#ord defined in core_ext 
         if self.type.downcase=='text' && maxlength && maxlength >= 0 && new_value_chars.length > maxlength
           new_value_chars=new_value_chars[0...maxlength]
         end
         element_object.scrollIntoView
-        type_keys=respond_to?(:type_keys) ? self.type_keys : true # TODO: FIX
-        typingspeed=respond_to?(:typingspeed) ? self.typingspeed : 0 # TODO: FIX
-        if type_keys
-          if options[:focus]
-            element_object.focus
-            fire_event('onFocus')
-            assert_exists(:force => true)
-          end
-          if options[:select]
-            element_object.select
-            fire_event("onSelect")
-            assert_exists(:force => true)
+        if options[:focus]
+          assert_exists(:force => true)
+          element_object.focus
+          fire_event('onFocus')
+        end
+        if options[:select]
+          assert_exists(:force => true)
+          element_object.select
+          fire_event("onSelect")
+        end
+        if config.type_keys
+          (existing_value_chars.length...new_value_chars.length).each do |i|
+            last_key = (i == new_value_chars.length - 1)
+            handling_existence_failure(:handle => (last_key ? :ignore : :raise)) do
+              type_key(new_value_chars[i]) do
+                assert_exists(:force => true)
+                element_object.value = new_value_chars[0..i].join('')
+              end
+            end
+            sleep config.typing_interval
           end
-          ((existing_value_chars.length)...new_value_chars.length).each do |i|
-#            sleep typingspeed # TODO/FIX
-            element_object.value = new_value_chars[0..i].join('')
-            fire_event :onKeyDown # TODO/fix - keyCode for character typed 
-            assert_exists(:force => true)
-            fire_event :onKeyPress
-            assert_exists(:force => true)
-            fire_event :onKeyUp
+        else
+          with_key_down do # simulate at least one keypress
             assert_exists(:force => true)
+            element_object.value = new_value_chars.join('')
           end
-          if options[:change] && exists?
-            fire_event("onChange")
-          end
-          if options[:blur] && exists?
-            fire_event('onBlur')
-          end
-        else
-          element_object.value = element_object.value + value
+        end
+        if options[:change] && exists?
+          handling_existence_failure { fire_event("onChange") }
+        end
+        if options[:blur] && exists?
+          handling_existence_failure { fire_event('onBlur') }
         end
         wait
-        self.value
+        exists? ? self.value : nil
       end
     end
     # Sets the contents of the text field to the given value
@@ -175,18 +231,16 @@ module Vapir
     # returns the new value of the text field. this may be shorter than what is given if there is a maxlength on the field. 
     # 
     # takes options: 
-    # :blur => true/false; whether or not to file the onblur event when done.
-    # :highlight => true/false
+    # - :blur => true/false; whether or not to file the onblur event when done.
+    # - :highlight => true/false
     #
-    #   Raises UnknownObjectException if the object cant be found
-    #   Raises ObjectDisabledException if the object is disabled
-    #   Raises ObjectReadOnlyException if the object is read only
+    # Raises UnknownObjectException if the object cant be found
+    # Raises ObjectDisabledException if the object is disabled
+    # Raises ObjectReadOnlyException if the object is read only
     def set(value, options={})
       with_highlight(options) do
         clear(options.merge(:blur => false, :change => false))
-        assert_exists(:force => true)
         append(value, options.merge(:focus => false, :select => false))
-        self.value
       end
     end
   end
@@ -256,7 +310,7 @@ module Vapir
       method_options={:highlight => true, :wait => true}.merge(method_options)
       with_highlight(method_options) do
         state_was=element_object.selected
-        element_object.selected=state
+        element_object.selected=state # TODO: if state is false and this isn't an option of a multiple select list, should this error? 
         if @extra[:select_list] && state_was != state
           @extra[:select_list].fire_event(:onchange, method_options)
         end
@@ -545,10 +599,95 @@ module Vapir
     end
   end
   module HasRowsAndColumns
+    # returns a TableRow which is a row of this of this Table or TBody (not in a nested table). 
+    # takes the usual arguments for specifying what you want - see http://github.com/vapir/vapir/wiki/Locators
+    def row(first=nil, second=nil)
+      element_by_howwhat(element_class_for(Vapir::TableRow), first, second, :extra => {:candidates => :rows})
+    end
+    
+    # returns a TableCell which is a cell of this of this Table or TBody (not in a nested table). 
+    # takes the usual arguments for specifying what you want - see http://github.com/vapir/vapir/wiki/Locators
+    def cell(first=nil, second=nil)
+      element_by_howwhat(element_class_for(Vapir::TableCell), first, second, :extra => {:candidates => proc do |container|
+        container_object=container.element_object
+        object_collection_to_enumerable(container_object.rows).inject([]) do |candidates, row|
+          candidates+object_collection_to_enumerable(row.cells).to_a
+        end
+      end})
+    end
+    
     # Returns a 2 dimensional array of text contents of each row and column of the table or tbody.
     def to_a
       rows.map{|row| row.cells.map{|cell| cell.text.strip}}
     end
+    
+    # Returns an array of hashes representing this table. This assumes that the table has one row 
+    # with header information and any number of rows with data. Each element of the array is a hash 
+    # whose keys are the header values (every hash has the same keys), and whose values correspond 
+    # to the current row. 
+    #
+    #  +--------------+---------------+
+    #  | First Header | Second Header |
+    #  | First Data 1 | Second Data 1 |
+    #  | First Data 2 | Second Data 2 |
+    #  +--------------+---------------+
+    #
+    # Given the above table, #to_hashes will return 
+    #  [{'First Header' => 'First Data 1', 'Second Header' => 'Second Data 1'}, {'First Header' => 'First Data 2', 'Second Header' => 'Second Data 2'}]
+    #
+    # This method will correctly account for colSpans and return text from all cells underneath a 
+    # given header on one row. However, this method makes no attempt to deal with any rowSpans and 
+    # will probably not work with any table with rowSpans in either the header row or data rows. 
+    #
+    # options:
+    # - :header_count (default 1) - the number of rows before the table data start. 
+    # - :header_index (default whatever :header_count is) - the index of the row that contains 
+    #   header data which will be the keys of the hashes returned. (1-indexed) 
+    # - :footer_count (default 0) - the number of rows to discard from the end, being footer 
+    #   information and not table data. 
+    # - :separator (default ' ') - used to join cells when there is more than one cell 
+    #   underneath a header. 
+    def to_hashes(options={})
+      options=handle_options(options, {:header_count => 1, :footer_count => 0, :separator => ' '}, [:header_index])
+      options[:header_index]||=options[:header_count]
+      
+      col_headings=rows[options[:header_index]].cells.map do |cell|
+        {:colSpan => cell.colSpan || 1, :text => cell.text.strip}
+      end
+      
+      body_range=(options[:header_count]+1 .. self.row_count-options[:footer_count])
+      return body_range.map do |row_index|
+        row=rows[row_index]
+        # cells_by_heading will contain an array of arrays of table cells 
+        # underneath the col_heading corresponding to cells_by_heading's array index. 
+        # if cells do not line up underneath the column heading, exception is raised. 
+        cells_by_heading=[]
+        curr_heading_index=0
+        cols_in_curr_heading=0
+        row.cells.each do |cell|
+          curr_heading=col_headings[curr_heading_index]
+          cells_by_heading[curr_heading_index] ||= []
+          cells_by_heading[curr_heading_index] << cell
+          cols_in_curr_heading += cell.colSpan || 1
+          if cols_in_curr_heading == curr_heading[:colSpan]
+            curr_heading_index+=1
+            cols_in_curr_heading=0
+          elsif cols_in_curr_heading > curr_heading[:colSpan]
+            raise "Cells underneath heading #{curr_heading[:text].inspect} do not line up!"
+          end # else, we haven't got all the cells under the current heading; keep going
+        end
+        if curr_heading_index > col_headings.length
+          raise "Too many cells for the headings!"
+        elsif curr_heading_index < col_headings.length
+          raise "Too few cells for the headings!"
+        end
+        
+        col_headings.zip(cells_by_heading).inject({}) do |row_hash, (heading, cells)|
+          cell_texts=cells.map(&:text).join(options[:separator]).strip
+          row_hash.merge(heading[:text] => cell_texts)
+        end
+      end
+    end
 
     # iterates through the rows in the table. Yields a TableRow object
     def each_row
@@ -603,6 +742,7 @@ module Vapir
         nil
       end
     end
+    #--
     # I was going to define #cell_count(index=nil) here as an alternative to #column_count
     # but it seems confusing; to me #cell_count on a Table would count up all the cells in
     # all rows, so going to avoid confusion and not do it. 
@@ -617,6 +757,7 @@ module Vapir
     
     # Returns an array containing the text of the cell in the specified index in each row. 
     def column_texts_at(column_index)
+      # TODO: since this is named as 'column', not 'cell', shouldn't it return cell_at_column? 
       rows.map do |row|
         row.cells[column_index].text
       end
@@ -641,7 +782,13 @@ module Vapir
     # Returns an ElementCollection of cells in the row 
     element_collection :cells, :cells, TableCell
     
-    #   Iterate over each cell in the row.
+    # returns a TableCell which is a cell of this of this row (not in a nested table). 
+    # takes the usual arguments for specifying what you want - see http://github.com/vapir/vapir/wiki/Locators
+    def cell(first=nil, second=nil)
+      element_by_howwhat(element_class_for(Vapir::TableCell), first, second, :extra => {:candidates => :cells})
+    end
+
+    # Iterate over each cell in the row. same as #cells.each. 
     def each_cell
       cells.each do |cell|
         yield cell
@@ -654,24 +801,51 @@ module Vapir
       cells[index]
     end
     
+    # the number of columns in this row, accounting for cells with a colspan attribute greater than 1 
     def column_count
       cells.inject(0) do |count, cell|
         count+ (cell.colSpan || 1)
       end
     end
+    
+    # the number of cells in this row 
     def cell_count
       cells.length
     end
     
-    # returns the cell of the current row at the given column index (starting from 1), taking
+    # returns the column index (starting at 0), taking into account colspans, of the table cell for which the given block returns true. 
+    #
+    # if nothing matches the block, returns nil. 
+    def column_count_where # :yields: table_cell
+      cells.inject(0) do |count, cell|
+        if yield cell
+          return count
+        end
+        count+(cell.colSpan || 1)
+      end
+      nil
+    end
+    
+    # returns the cell of the current row at the given column index (starting from 0), taking
     # into account conSpans of other cells. 
     #
     # returns nil if index is greater than the number of columns of this row. 
-    def cell_at_colum(index)
-      cells.detect do |cell|
+    def cell_at_column(index)
+      #TODO: test
+      cells.each_by_index do |cell|
         index=index-(cell.colSpan || 1)
-        index <= 0
+        return cell if index < 0
       end
+      nil
+    end
+    
+    # returns the cell of the current row at the given column index (starting from 0), taking
+    # into account conSpans of other cells. 
+    #
+    # raises exception if the cell does not exist (that is, index is greater than the number of columns of this row). 
+    def cell_at_column!(index)
+      #TODO: test
+      cell_at_column(index) || raise(Vapir::Exception::UnknownObjectException, "Unable to locate cell at column #{index}. Column count is #{column_count}\non container: #{@container.inspect}")
     end
   end
   module TBody
@@ -687,7 +861,9 @@ module Vapir
   end
   module Table
     def self.create_from_element(container, element)
-      Kernel.warn "DEPRECATION WARNING: create_from_element is deprecated. Please use (element).parent_table (element being the second argument to this function)\n(called from #{caller.map{|c|"\n"+c}})"
+      if config.warn_deprecated
+        Kernel.warn_with_caller "DEPRECATION WARNING: create_from_element is deprecated. Please use (element).parent_table (element being the second argument to this function)"
+      end
       element.parent_table
     end