image.rb in watir-classic-3.4.0

- old
+ new
@@ -1,110 +1,104 @@
 module Watir
   
-  # This class is the means of accessing an image on a page.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#image method
-  #
-  # many of the methods available to this object are inherited from the Element class
-  #
+  # Returned by {Container#image}
   class Image < Element
     attr_ole :alt
     attr_ole :src
 
-    # this method produces the properties for an image as an array
-    def image_string_creator
-      n = []
-      n <<   "src:".ljust(TO_S_SIZE) + self.src.to_s
-      n <<   "file date:".ljust(TO_S_SIZE) + self.fileCreatedDate.to_s
-      n <<   "file size:".ljust(TO_S_SIZE) + self.fileSize.to_s
-      n <<   "width:".ljust(TO_S_SIZE) + self.width.to_s
-      n <<   "height:".ljust(TO_S_SIZE) + self.height.to_s
-      n <<   "alt:".ljust(TO_S_SIZE) + self.alt.to_s
-      return n
-    end
-    private :image_string_creator
-    
-    # returns a string representation of the object
-    def to_s
-      assert_exists
-      r = string_creator
-      r += image_string_creator
-      return r.join("\n")
-    end
-    
-    # this method returns the filesize of the image, as an int
+    # @return [Fixnum] file size of the image in bytes.
+    # @macro exists
     def file_size
       assert_exists
       @o.invoke("fileSize").to_i
     end
     
-    # returns the width in pixels of the image, as an int
+    # @return [Fixnum] width of the image in pixels.
+    # @macro exists
     def width
       assert_exists
       @o.invoke("width").to_i
     end
     
-    # returns the height in pixels of the image, as an int
+    # @return [Fixnum] height of the image in pixels.
+    # @macro exists
     def height
       assert_exists
       @o.invoke("height").to_i
     end
     
-    # This method attempts to find out if the image was actually loaded by the web browser.
-    # If the image was not loaded, the browser is unable to determine some of the properties.
-    # We look for these missing properties to see if the image is really there or not.
-    # If the Disk cache is full (tools menu -> Internet options -> Temporary Internet Files), it may produce incorrect responses.
+    # @return [Boolean] true if image is loaded by the browser, false otherwise.
+    # @macro exists
     def loaded?
       assert_exists
       file_size != -1
     end
     
-    # this method highlights the image (in fact it adds or removes a border around the image)
-    #  * set_or_clear   - symbol - :set to set the border, :clear to remove it
-    def highlight(set_or_clear)
-      if set_or_clear == :set
-        begin
-          @original_border = @o.border
-          @o.border = 1
-        rescue
-          @original_border = nil
-        end
-      else
-        begin
-          @o.border = @original_border
-          @original_border = nil
-        rescue
-          # we could be here for a number of reasons...
-        ensure
-          @original_border = nil
-        end
-      end
-    end
-    private :highlight
-    
-    # This method saves the image to the file path that is given.  The
-    # path must be in windows format (c:\\dirname\\somename.gif).  This method
-    # will not overwrite a previously existing image.  If an image already
-    # exists at the given path then a dialog will be displayed prompting
-    # for overwrite.
-    # path - directory path and file name of where image should be saved
+    # Save the image to the file.
+    #
+    # @example
+    #   browser.image.save("c:/foo/bar.jpg")
+    #
+    # @param [String] path path to the file.
+    #
+    # @note This method will not overwrite a previously existing image.
+    #   If an image already exists at the given path then a dialog
+    #   will be displayed prompting for overwrite.
+    #
+    # @todo it should raise an Exception if image already exists.
     def save(path)
       @container.goto(src)
       begin
         fill_save_image_dialog(path)
         @container.document.execCommand("SaveAs")
       ensure
         @container.back
       end
     end
-    
+
+    def to_s
+      assert_exists
+      r = string_creator
+      r += image_string_creator
+      return r.join("\n")
+    end
+
+    private
+
+    # this method produces the properties for an image as an array
+    def image_string_creator
+      n = []
+      n <<   "src:".ljust(TO_S_SIZE) + self.src.to_s
+      n <<   "file date:".ljust(TO_S_SIZE) + self.fileCreatedDate.to_s
+      n <<   "file size:".ljust(TO_S_SIZE) + self.fileSize.to_s
+      n <<   "width:".ljust(TO_S_SIZE) + self.width.to_s
+      n <<   "height:".ljust(TO_S_SIZE) + self.height.to_s
+      n <<   "alt:".ljust(TO_S_SIZE) + self.alt.to_s
+      return n
+    end
+
     def fill_save_image_dialog(path)
       command = "require 'rubygems';require 'rautomation';" <<
                 "window=::RAutomation::Window.new(:title => 'Save Picture');" <<
                 "window.text_field(:class => 'Edit', :index => 0).set('#{path.gsub(File::SEPARATOR, File::ALT_SEPARATOR)}');" <<
                 "window.button(:value => '&Save').click"
       IO.popen("ruby -e \"#{command}\"")
     end
-    private :fill_save_image_dialog
+
+    # Highlight the image (in fact it adds a border around the image).
+    def set_highlight
+      perform_highlight do
+        @original_border = @o.border
+        @o.border = 1
+      end
+    end
+
+    # Clear the highlight of the image (in fact it removes a border around the image).
+    def clear_highlight
+      perform_highlight do
+        @o.border = @original_border if @original_border
+      end
+    end
 
   end
   
 end