operawatir 0.4.1.pre5-jruby → 0.4.1.pre6-jruby

data/lib/operawatir/element.rb

@@ -35,9 +35,9 @@ class OperaWatir::Element
     !attr(name).nil?
   end
 
-  def method_missing(name, *args, &blk)
-    if !(block_given? || !args.empty?) && has_attribute?(name)
-      attr(name)
+  def method_missing(method, *args, &blk)
+    if !(block_given? || !args.empty?) && has_attribute?(method)
+      attr(method)
     else
       super
     end
@@ -59,6 +59,8 @@ class OperaWatir::Element
   def_delegator :node, :isEnabled, :enabled?
   def_delegator :node, :isSelected, :checked?
 
+  def_delegator :node, :setSelected, :select
+
   def_delegator :node, :isSelected, :selected?
 
   def_delegator :node, :toggle, :toggle_check!
@@ -66,8 +68,6 @@ class OperaWatir::Element
   def_delegator :node, :getText, :text
   def_delegator :node, :getHTML, :html
 
-  alias_method :to_s, :text
-
   def_delegator :node, :getElementName, :tag_name
   def_delegator :node, :clear, :clear
 
@@ -77,32 +77,54 @@ class OperaWatir::Element
   #
   # @return [String] Value of the element.
   def value
+=begin
     if tag_name =~ /input|textarea|select/i
-      node.getValue
+      node.getValue  #
+    elsif tag_name =~ /button/i
+      text           # getVisibleContents
     else
-      attr :value
+      attr :value    # attribute @value
     end
+=end
+
+    node.getValue
+  end
+
+  #
+  # Does the element exist in the DOM?
+  #
+  # @return [Boolean] True if element exists, false otherwise.
+  #
+
+  def exist?
+    !!!tag_name.empty?
   end
 
+  alias_method :exists?, :exist?  # LOL Ruby
+
   def disabled?
     !enabled?
   end
 
   def check!
-    if not selected?
-      node.toggle
-    end
+    node.toggle if not selected?
   end
 
   def uncheck!
-    if selected?
-      node.toggle
-    end
+    node.toggle if selected?
   end
 
 
   # Events
 
+  #
+  # Clicks on the top left of the element, or the given x,y offset
+  # relative to the element.
+  #
+  # @param [Integer] x The offset from the top left of the element.
+  # @param [Integer] y The offset from the top of the element.
+  #
+
   def click(x=0, y=0)
     node.click(x.to_i, y.to_i)
   end
@@ -138,9 +160,13 @@ class OperaWatir::Element
   def_delegator :node, :submit, :submit!
 
   def text=(input)
-    # Focus before typing
-    clear unless value.empty?
-    node.sendKeys(input.to_s.split('').to_java(:string))
+    if attr(:type) =~ /checkbox/i
+      toggle_check! unless checked?
+    else
+      # Focus before typing
+      clear unless value.empty?
+      node.sendKeys(input.to_s.split('').to_java(:string))
+    end
   end
 
   alias_method :set, :text=
@@ -150,6 +176,8 @@ class OperaWatir::Element
     raise Exceptions::NotImplementedException
   end
 
+  # FIXME: This should be migrated to using browserbot.js, as watir-webdriver
+  # is using.
   def fire_event(event, x = 0, y = 0)
     loc = location
     x += loc[:x]
@@ -162,19 +190,15 @@ class OperaWatir::Element
     event = $1 if $1
     event = event.downcase.to_sym
 
-    # TODO Should this be moved to OperaDriver instead?
     case event
-    when :abort, :blur, :change, :error, :focus, :load, :reset,
-      :resize, :scroll, :submit, :unload
+    when :abort, :blur, :change, :error, :focus, :load, :reset, :resize, :scroll, :submit, :unload
       type = 'HTMLEvents';
       init = "initEvent(\"#{event.to_s}\", true, true)"
-    when :click, :dblclick, :mousedown, :mousemove, :mouseout,
-      :mouseover, :mouseup
+    when :click, :dblclick, :mousedown, :mousemove, :mouseout, :mouseover, :mouseup
       type = 'MouseEvents'
       init = "initMouseEvent(\"#{event.to_s}\", true, true, window, 1, 0, 0, 0, 0, false, false, false, false, 0, null)"
     else
-      raise Exceptions::NotImplementedException,
-      "Event on#{event} is not a valid ECMAscript event for OperaWatir."
+      raise Exceptions::NotImplementedException, "Event on#{event} is not a valid ECMAscript event for OperaWatir."
     end
 
     script = "var event = document.createEvent(\"#{type}\"); " +
@@ -185,7 +209,7 @@ class OperaWatir::Element
   end
 
   def visible?
-    node.isVisible()
+    node.isVisible
   end
 
   # UI

data/lib/operawatir/keys.rb

@@ -7,42 +7,27 @@ class OperaWatir::Keys
     self.browser = browser
   end
 
-  # Holds down supplied arbitrary list of keys indefinitely.
   #
-  # @param [Symbol, String] *args Arbitrary list of symbols
-  #   (modification keys) or strings (regular keys) to be pressed
-  #   down.
+  # Holds down supplied arbitrary list of keys indefinitely.
   #
+  # @param [Symbol, String] *args  Arbitrary list of symbols (modification)
+  #                                keys or strings (regular keys) to be
+  #                                pressed down.
+  #                               
   # @example
+  #
   #   browser.keys.down 'a'
   #   browser.keys.down 'a', :right
-  #
+  #  
   # @seealso up
   # @seealso send
+  #
   
-  
-  
-=begin
-
-  Holds down supplied arbitrary list of keys indefinitely.
-  
-  @param [Symbol, String] *args  Arbitrary list of symbols (modification)
-                                 keys or strings (regular keys) to be
-                                 pressed down.
-                                 
-  @example
-  
-    browser.keys.down 'a'
-    browser.keys.down 'a', :right
-    
-  @seealso up
-  @seealso send
-  
-=end
   def down(*args)
     args.each { |key| driver.keyDown(key) }
   end
 
+  #
   # Depresses supplied arbitrary list of keys.
   #
   # @param [Symbol, String] *args Arbitrary list of symbols
@@ -52,19 +37,25 @@ class OperaWatir::Keys
   #   browser.keys.up 'a', :right
   #
   # @seealso release
+  #
+
   def up(*args)
     args.each { |key| driver.keyUp(key) }
   end
 
+  #
   # Releases all pressed down keys.
   #
   # @example
   #   browser.keys.down :control, :shift, 'a'
   #   browser.keys.release
+  #
+
   def release
     driver.releaseKeys
   end
 
+  #
   # Presses an arbitrary list of keys or key combinations.  Provided
   # arguments are performed in sequence.
   #
@@ -90,6 +81,8 @@ class OperaWatir::Keys
   #   browser.keys.send :control
   #   browser.keys.send [:control, 'a']
   #   browser.keys.send [:control, 'a'], :backspace
+  #
+
   def send(*list)  # TODO rename?
     list.each do |item|
       case item
@@ -102,9 +95,9 @@ class OperaWatir::Keys
             down key
           else
             key key
-            release
           end
         end
+        release
       when Symbol
         key item
       else

data/lib/operawatir/preferences.rb

@@ -1,13 +1,104 @@
 class String
+
+  #
+  # Translates an Opera preferences key string into a Ruby method name.
+  # It will remove tabs and spaces at beginning of string, replace
+  # further spaces with an underscore and make the string lower-case.
+  #
+  # The method extends the String object and can be called as a regular
+  # method on any string in Ruby.
+  #
+
   def methodize
     self.gsub(/^\\t(\s+)/, '').gsub(/\s+/, '_').downcase
   end
 
+  #
+  # Translates a previously keyized Opera preferences method string into
+  # an Opera preferences key string.  This is done by replacing
+  # underscores with spaces and capitalizing each word in the string.
+  #
+  # The method extends the String object and can be called as a regular
+  # method on any string in Ruby.
+  #
+
   def keyize
     self.gsub(/_/, ' ').gsub(/\b('?[a-z])/) { $1.capitalize }
   end
 end
 
+#
+# OperaWatir::Preferences enables you to access the browser preferences
+# in the Opera web browser.
+#
+# @example
+#
+#   The Preferences object is created automatically when creating a new
+#   Browser object and is exposed as an interface on that object:
+#
+#     browser.preferences
+#     => <OperaWatir::Preferences>
+#
+#   You can interact with this object as you would with any Ruby object.
+#   Sections and entries are exposed as Rubyized method names, which
+#   means that you can access them like this:
+#
+#     browser.preferences.interface_colors             # a section
+#     browser.preferences.interface_colors.background  # an entry
+#
+#   Over the preference object itself or over a section you can also use
+#   built-in Ruby convenience methods such as:
+#
+#     browser.preferences.first             # first section
+#     browser.preferences.interface_colors  # first entry in section
+#     browser.preferences.size              # number of sections
+#
+#   This is a full list of available convenience methods:
+#
+#     * []
+#     * each
+#     * length
+#     * size
+#     * first
+#     * last
+#     * empty?
+#
+#   Essentially, the preference and section objects are collections
+#   (kind of like arrays) that allows you to also iterate over them:
+#
+#     browser.preferences.each_with_index do |section, index|
+#       puts "Section No. #{index} is called `#{section.key}'"
+#     end
+#
+#     browser.preferences.interface_colors.each { |e| e.value = '#cccccc' }
+#
+#     browser.preferences.interface_colors[5].value
+#     => '#cccccc'
+#
+#   On each section, the follow getters are available in addition to the
+#   convenience methods mentioned above:
+#
+#     * section?  # Returns true/false based on whether it's a section
+#     * exists?   # Returns true/false based on whether it exists
+#
+#   On each entry, the following getters and setters are available in
+#   addition to the convenience methods mentioned above:
+#
+#     * value     # Returns current preference's value
+#     * value=    # Sets current preference's value to provided string
+#     * default   # Returns current preference's default
+#     * default!  # Sets current preference to its default
+#
+#   This means you can do crazy stuff like resetting all the preferences
+#   in `opera:config` to their standard value like this:
+#
+#     browser.preferences.each do |section|
+#       section.each do |entry|
+#         entry.default!
+#       end
+#     end
+#
+
 class OperaWatir::Preferences
   extend Forwardable
   include Enumerable
@@ -27,10 +118,40 @@ class OperaWatir::Preferences
               'User Agent', 'User Display Mode', 'User Prefs', 'Visited Link',
               'Visited Link', 'Web Server', 'Widgets', 'Workspace']
 
+  #
+  # The OperaWatir::Preferences object is created automatically when you
+  # create an OperaWatir::Browser object, and is available as
+  # Browser#prefrences.
+  #
+  # @example
+  #
+  #   browser.preferences.method_name
+  #
+  # @param [Object] browser  An OperaWatir::Browser object.
+  #
+
   def initialize(browser)
     self.browser, self.driver = browser, browser.driver
   end
 
+  #
+  # When calling Preferences#any_method_name, the `any_method_name` will
+  # be caught by this method.
+  #
+  # This is the standard way of looking up sections.  `any_method_name`
+  # should be replaced by a methodized version of the section as it
+  # appears in the Opera preferences list which you can find at
+  # `opera:config`.
+  #
+  # @example
+  #
+  #   browser.preferences.interface_colors
+  #   # will return section “Interface Colors”
+  #
+  # @param           section  Method to look up in preferences.
+  # @return [Object]          A Preferences::Entry (section) object.
+  #
+
   def method_missing(section)
     if _prefs.any? { |s| s.method == section.to_s }
       _prefs.find { |s| s.method == section.to_s }
@@ -48,6 +169,15 @@ class OperaWatir::Preferences
                           :last,
                           :empty?
 
+  #
+  # Retrieves a human-readable list of Opera preferences available.
+  # This is used for convenience and should never be parsed.  Consider
+  # using the built-in Ruby iterator #each (with friends) or
+  # Preferences#to_a for that.
+  #
+  # @return [String]          List of preferences.
+  #
+
   def to_s
     text = ''
 
@@ -65,10 +195,26 @@ class OperaWatir::Preferences
     text
   end
 
+  #
+  # Returns a list of all preferences in array form.  This can be used
+  # for external parsing.  If you wish to manipulate or iterate through
+  # the list of preferences consider using the built-in Ruby iterator
+  # #each (with friends).
+  #
+  # @return [Array]           List of preferences.
+  #
+
   def to_a
     _prefs.dup
   end
 
+  #
+  # Checks if any preferences exists in your Opera build.  If true,
+  # there are preferences available, false otherwise.
+  #
+  # @return [Boolean]         Whether any preferences exists.
+  #
+
   def exists?
     !_prefs.empty?
   end
@@ -88,6 +234,16 @@ private
 
     attr_accessor :parent, :method, :key, :value, :type, :default, :driver
 
+    #
+    # OperaWatir::Preferences::Entry is the object that represents
+    # either a section or a section's entry.
+    #
+    # It's created automatically when you query for entries using the
+    # Preference object itself.
+    #
+    # @return [Object] An OperaWatir::Preferences::Entry object.
+    #
+
     def initialize(parent, method, key=nil, type=nil)
       self.parent = parent
       self.method = method.to_s
@@ -96,22 +252,54 @@ private
       self.driver = parent.driver
     end
 
-    def method_missing(key)
-      key = key.to_s
+    #
+    # When calling Preferences::Entry#any_method_name, the
+    # `any_method_name` will be caught by this method.
+    #
+    # This is the standard way of looking up preference entries.
+    # `any_method_name` should be replaced by a methodized version of
+    # the entry as it appears in the Opera preferences list which you
+    # can find at `opera:config`.
+    #
+    # @example
+    #
+    #   browser.preferences.interface_colors.background
+    #   # will return the “Background” entry in section “Interface Colors”
+    #
+    # @param           method  Method to look up in section.
+    # @return [Object]         A Preferences::Entry (entry) object.
+    #
+
+    def method_missing(method)
+      method = method.to_s
       
-      if _keys.any? { |k| k.method == key }
-        _keys.find { |k| k.method == key }
+      if _keys.any? { |k| k.method == method }
+        _keys.find { |k| k.method == method }
       else
-        _keys << Entry.new(self, key)
+        _keys << Entry.new(self, method)
         _keys.last
       end
     end
 
+    #
+    # Returns the value of an entry in a section.  Note that it's not
+    # possible to retrieve the value for sections.
+    #
+    # @return [String] Value of the entry.
+    #
+
     def value
       raise OperaWatir::Exceptions::PreferencesException, 'Sections do not have values' if section?
       @value ||= driver.getPref(parent.key, key)
     end
 
+    #
+    # Sets the entry's value to the specified string.  Note that it's
+    # not possible to set a section's value.
+    #
+    # @param [String] value  Value you wish to set for the entry.
+    #
+
     def value=(value)
       raise OperaWatir::Exceptions::PreferencesException, 'Sections cannot have values' if section?
       value = value.truthy? ? '1' : '0' if type.include?('Boolean')
@@ -119,19 +307,48 @@ private
       @value = value
     end
 
+    #
+    # Returns entry's default value.  Note that it's not possible to
+    # return a section's default value.
+    #
+    # @return [String]       The default value of the entry.
+    #
+
     def default
       raise OperaWatir::Exceptions::PreferencesException, 'Sections do not have defaults' if section?
       @default ||= driver.getDefaultPref parent.key, key
     end
 
+    #
+    # Returns and sets the default value of the entry.  Note that it's
+    # not possible to return and set a section's default value.
+    #
+    # @return [String]       The default value of the entry.
+    #
+
     def default!
       self.value=(default)  # WTF?  Bug in Ruby?
     end
 
+    #
+    # Is the current node a section?
+    #
+    # @return [Boolean]      True/false based on whether you're
+    #                        interacting with a section or entry.
+    #
+
     def section?
       parent.kind_of? OperaWatir::Preferences
     end
 
+    #
+    # Does this entry/section exist?
+    #
+    # @return [Boolean]      True/false based on whether the method you
+    #                        are attempting to access exists as a
+    #                        preference entry/section.
+    #
+
     def exists?
       section? ? SECTIONS.include?(key) : !type.empty?
     end
@@ -165,7 +382,7 @@ private
         p = p.to_s
         
         p =~ /^key: \"([a-zA-Z0-9\(\)\\\.\-\s]*)\"$/
-        key = $1
+        key = $1.to_s
         
         p =~ /^type: ([A-Z]+)$/
         type = $1.to_s.capitalize