watir-classic 3.3.0 → 3.4.0

data/lib/watir-classic/link.rb

@@ -1,22 +1,21 @@
 module Watir  
   
-  # This class is the means of accessing a link on a page
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#link method
-  # many of the methods available to this object are inherited from the Element class
-  #
+  # Returned by {Container#link}.
   class Link < Element
     attr_ole :type
     attr_ole :href
     attr_ole :name
 
-    # if an image is used as part of the link, this will return true
+    # @deprecated Use "browser.link.imgs.length > 0" instead.
     def link_has_image
+      Kernel.warn "Deprecated(Link#link_has_image) - use \"browser.link.imgs.length > 0\" instead."
       assert_exists
       @o.getElementsByTagName("IMG").length > 0
     end
     
-    # this method returns the src of an image, if an image is used as part of the link
-    def src # BUG?
+    # @deprecated Use "browser.link.imgs.first.src rescue ''" instead.
+    def src
+      Kernel.warn "Deprecated(Link#link_has_image) - use \"browser.link.imgs.first.src rescue ''\" instead."
       assert_exists
       if @o.getElementsByTagName("IMG").length > 0
         return @o.getElementsByTagName("IMG")[0.to_s].src
@@ -24,7 +23,15 @@ module Watir
         return ""
       end
     end
+
+    def to_s
+      assert_exists
+      r = string_creator
+      r = r + link_string_creator
+      return r.join("\n")
+    end
     
+    # @private
     def link_string_creator
       n = []
       n <<   "href:".ljust(TO_S_SIZE) + self.href
@@ -33,14 +40,6 @@ module Watir
       return n
     end
     
-    # returns a textual description of the link
-    def to_s
-      assert_exists
-      r = string_creator
-      r = r + link_string_creator
-      return r.join("\n")
-    end
-
   end
   
 end

data/lib/watir-classic/locator.rb

@@ -1,4 +1,5 @@
 module Watir
+  # @private
   class Locator
     include Watir
     include Watir::Exception
@@ -6,7 +7,7 @@ module Watir
 
     def initialize container, specifiers, klass
       @container = container
-      @specifiers = {:index => Watir::IE.base_index}.merge(normalize_specifiers(specifiers))
+      @specifiers = {:index => 0}.merge(normalize_specifiers(specifiers))
       @tags = @specifiers.delete(:tag_name)
       @klass = klass
     end
@@ -131,6 +132,7 @@ module Watir
     end
   end
 
+  # @private
   class TaggedElementLocator < Locator
     def each_element(tag)
       document.getElementsByTagName(tag).each do |ole_object|
@@ -143,15 +145,16 @@ module Watir
       return el if el
       return locate_elements_by_xpath_css_ole[0] if has_excluding_specifiers?
 
-      count = Watir::IE.base_index - 1
+      count = 0
       each do |element|
-        count += 1
         return element.ole_object if count == @specifiers[:index]
+        count += 1
       end # elements
       nil
     end
   end
 
+  # @private
   class FrameLocator < TaggedElementLocator
     def each_element(tag)
       frames = @container.page_container.document.frames
@@ -165,10 +168,10 @@ module Watir
     end
 
     def locate
-      count = Watir::IE.base_index - 1
+      count = 0
       each do |frame|
-        count += 1
         return frame.ole_object, frame.document if count == @specifiers[:index]
+        count += 1
       end
     end
 
@@ -186,6 +189,7 @@ module Watir
     end
   end
 
+  # @private
   class FormLocator < TaggedElementLocator
     def each_element(tag)
       document.forms.each do |form|
@@ -194,6 +198,7 @@ module Watir
     end
   end
 
+  # @private
   class InputElementLocator < Locator
     def each_element
       elements = locate_by_name || @container.__ole_inner_elements
@@ -208,10 +213,10 @@ module Watir
       return el if el
       return locate_elements_by_xpath_css_ole[0] if has_excluding_specifiers?
 
-      count = Watir::IE.base_index - 1
+      count = 0
       each do |element|
-        count += 1
         return element.ole_object if count == @specifiers[:index]
+        count += 1
       end
     end
 

data/lib/watir-classic/matches.rb

@@ -1,21 +1,25 @@
+# @private
 class String
   def matches(x)
-    return self == x
+    self == x
   end
 end
 
+# @private
 class Regexp
   def matches(x)
-    return self.match(x)
+    self.match(x)
   end
 end
 
+# @private
 class Integer
   def matches(x)
-    return self == x
+    self == x
   end
 end
 
+# @private
 class Object
   def matches(x)
     raise TypeError, "#{self.class} is not supported as a locator"

data/lib/watir-classic/modal_dialog.rb

@@ -1,4 +1,5 @@
 module Watir
+  # Returned by {Container#modal_dialog}.
   class ModalDialog
     include Container
     include PageContainer
@@ -6,9 +7,43 @@ module Watir
 
     def initialize(container)
       set_container container
-      @modal = ::RAutomation::Window.new(:hwnd=>@container.hwnd).child(:class => 'Internet Explorer_TridentDlgFrame')
+      @modal = ::RAutomation::Window.new(:hwnd => @container.hwnd).child(:class => 'Internet Explorer_TridentDlgFrame')
     end
 
+    # @return [String] title of the dialog.
+    def title
+      document.title
+    end
+
+    # Close the modal dialog.
+    #
+    # @param [Fixnum] timeout timeout in seconds to wait until modal dialog is
+    #   successfully closed.
+    def close(timeout=5)
+      return unless exists?
+      document.parentWindow.close
+      Watir::Wait.until(timeout) {!exists?} rescue nil
+      wait
+    end
+
+    # @return [Fixnum] window handle of the dialog.
+    def hwnd
+      @modal.hwnd
+    end
+
+    # @return [Boolean] true when modal window is active/in focus, false otherwise.
+    def active?
+      @modal.active?
+    end
+
+    # @return [Boolean] true when dialog exists, false otherwise.
+    def exists?
+      @modal.exists?
+    end
+
+    alias_method :exist?, :exists?
+
+    # @private
     def locate
       @modal.wait_until_present rescue raise NoMatchingWindowFoundException
 
@@ -29,38 +64,15 @@ module Watir
 
     alias_method :document, :locate
 
-    def title
-      document.title
-    end
-
-    def close(timeout=5)
-      return unless exists?
-      document.parentWindow.close
-      Watir::Wait.until(timeout) {!exists?} rescue nil
-      wait
-    end
-
+    # @private
     def attach_command
       "Watir::IE.find(:hwnd, #{@container.hwnd}).modal_dialog"
     end
 
+    # @private
     def wait(no_sleep=false)
       @container.page_container.wait unless exists?
     end
 
-    def hwnd
-      @modal.hwnd
-    end
-
-    def active?
-      @modal.active?
-    end
-
-    def exists?
-      @modal.exists?
-    end
-
-    alias_method :exist?, :exists?
-
   end
 end

data/lib/watir-classic/non_control_elements.rb

@@ -1,28 +1,37 @@
 module Watir
+  # Returned by the {Watir::Container#area}.
   class Area < Element
     attr_ole :alt
     attr_ole :type
     attr_ole :href
   end
 
+  # Returned by the {Watir::Container#audio}.
   class Audio < Element
     attr_ole :src
   end
 
+  # Returned by the {Watir::Container#base}.
   class Base < Element
     attr_ole :href
   end
 
+  # Returned by the {Watir::Container#command}.
   class Command < Element
     attr_ole :disabled?
     attr_ole :type
   end
 
+  # Returned by the {Watir::Container#data}.
   class Data < Element
     attr_ole :value
   end
 
+  # Returned by the {Watir::Container#dl}.
   class Dl < Element
+    # Returns Hash representation of dl element where each key-value pair consists of dt and dd element text.
+    #
+    # @return [Hash<String, String>] where key and value is dt and dd text respectively
     def to_hash
       dts.each_with_index.reduce({}) do |memo, item|
         dt, i = *item
@@ -33,92 +42,112 @@ module Watir
     end
   end
 
+  # Returned by the {Watir::Container#embed}.
   class Embed < Element
     attr_ole :src
     attr_ole :type
   end
 
+  # Returned by the {Watir::Container#fieldset}.
   class FieldSet < Element
     attr_ole :name
     attr_ole :disabled?
   end
 
+  # Returned by the {Watir::Container#font}.
   class Font < Element
     attr_ole :color
     attr_ole :face
     attr_ole :size
   end
 
+  # Returned by the {Watir::Container#keygen}.
   class Keygen < Element
     attr_ole :name
     attr_ole :disabled?
   end
 
+  # Returned by the {Watir::Container#label}.
   class Label < Element
     attr_ole :for, :htmlFor
   end
 
+  # Returned by the {Watir::Container#li}.
   class Li < Element
     attr_ole :value
   end
 
+  # Returned by the {Watir::Container#map}.
   class Map < Element
     attr_ole :name
   end
 
+  # Returned by the {Watir::Container#menu}.
   class Menu < Element
     attr_ole :type
   end
 
+  # Returned by the {Watir::Container#meta}.
   class Meta < Element
     attr_ole :http_equiv, :httpEquiv
     attr_ole :content
     attr_ole :name
   end
 
+  # Returned by the {Watir::Container#meter}.
   class Meter < Element
     attr_ole :value
   end
 
+  # Returned by the {Watir::Container#object}.
   class Object < Element
     attr_ole :name
     attr_ole :type
   end
 
+  # Returned by the {Watir::Container#optgroup}.
   class Optgroup < Element
     attr_ole :disabled?
   end
 
+  # Returned by the {Watir::Container#output}.
   class Output < Element
     attr_ole :name
   end
 
+  # Returned by the {Watir::Container#param}.
   class Param < Element
     attr_ole :name
     attr_ole :value
   end
 
+  # Returned by the {Watir::Container#progress}.
   class Progress < Element
     attr_ole :value
   end
 
+  # Returned by the {Watir::Container#script}.
   class Script < Element
     attr_ole :src
     attr_ole :type
   end
 
+  # Returned by the {Watir::Container#source}.
   class Source < Element
     attr_ole :type
   end
 
+  # Returned by the {Watir::Container#style}.
   class Style < Element
     attr_ole :type
   end
 
+  # Returned by the {Watir::Container#track}.
   class Track < Element
     attr_ole :src
   end
 
+  # Returned by the {Watir::Container#video}.
   class Video < Element
     attr_ole :src
   end

data/lib/watir-classic/options.rb

@@ -5,29 +5,24 @@ require 'rubygems'
 require 'user-choices'
 
 module Watir
-  @@options_file = nil
-  @@options = nil
   class << self
     # Specify the location of a yaml file containing Watir options. Must be
     # specified before the options are parsed.
-    def options_file= file
-      @@options_file = file
-    end
-    def options_file
-      @@options_file
-    end
-    def options= x
-      @@options = x
-    end
+    attr_accessor :options_file
+
+    attr_writer :options
+
     # Return the Watir options, as a hash. If they haven't been parsed yet,
     # they will be now.
     def options
-      @@options ||= Watir::WatirOptions.new.execute
+      @options ||= Watir::WatirOptions.new.execute
     end
   end
 
+  # @private
   class WatirOptions < UserChoices::Command
     include UserChoices
+
     def add_sources builder
       builder.add_source EnvironmentSource, :with_prefix, 'watir_'
       if Watir.options_file
@@ -35,6 +30,7 @@ module Watir
           Watir.options_file
       end
     end
+
     def add_choices builder
       builder.add_choice :browser, 
       :type => Watir::Browser.browser_names, 
@@ -44,13 +40,12 @@ module Watir
       :default => 'fast'
       builder.add_choice :visible,
       :type => :boolean
-      builder.add_choice :zero_based_indexing,
-      :type => :boolean,
-      :default => true
     end
+
     def execute 
       @user_choices[:speed] = @user_choices[:speed].to_sym
       @user_choices
     end 
+
   end
 end