sikuli 0.1.4 → 0.1.5

data/lib/sikuli.rb

@@ -2,6 +2,7 @@ require "sikuli/sikuli-script.jar"
 require "sikuli/version"
 
 require "sikuli/app"
+require "sikuli/exception"
 require "sikuli/region"
 require "sikuli/screen"
 require "sikuli/key_code"

data/lib/sikuli/app.rb

@@ -1,13 +1,31 @@
+# An App object represents a running app on the system.
+#
 module Sikuli
   class App
+
+    # Public: creates a new App instance
+    #
+    # app_name - String name of the app
+    #
+    # Examples
+    #
+    #   App.new("TextEdit")
+    #
+    # Returns the newly initialized App
     def initialize(app_name)
       @java_obj = org.sikuli.script::App.new(app_name)
     end
 
+    # Public: brings the App to focus
+    #
+    # Returns nothing
     def focus
       @java_obj.focus()
     end
 
+    # Public: the Region instance representing the app's window
+    #
+    # Returns the newly initialized Region
     def window
       Region.new(@java_obj.window())
     end

data/lib/sikuli/clickable.rb

@@ -1,5 +1,21 @@
+# The Clickable module defines interaction with the mouse. It is included in
+# the Region class.
+#
 module Sikuli
   module Clickable
+
+    # Public: Performs a single click on an image match or point (x, y)
+    #
+    # args - String representing filename of image to find and click
+    # args - Fixnum, Fixnum representing x and y coordinates within
+    # a Region (0,0) is the top left
+    #
+    # Examples
+    #
+    #   region.click('smile.png')
+    #   region.click(123, 432)
+    #
+    # Returns nothing
     def click(*args)
       case args.length
         when 1 then click_image(args[0])
@@ -8,15 +24,39 @@ module Sikuli
       end
     end
 
-    def doubleClick(*args)
+    # Public: Performs a double click on an image match or point (x, y)
+    #
+    # args - String representing filename of image to find and click
+    # args - Fixnum, Fixnum representing x and y coordinates within
+    # a Region (0,0) is the top left
+    #
+    # Examples
+    #
+    #   region.double_click('smile.png')
+    #   region.double_click(123, 432)
+    #
+    # Returns nothing
+    def double_click(*args)
       case args.length
-        when 1 then click_image(args[0], { :double => true })
-        when 2 then click_point(args[0], args[1], {:double => true })
+        when 1 then click_image(args[0], true)
+        when 2 then click_point(args[0], args[1], true)
         else raise ArgumentError
       end
     end
 
-    def dragDrop(start_x, start_y, end_x, end_y)
+    # Public: Performs a mouse down, drag, and mouse up
+    #
+    # start_x - Fixnum representing the x of the mouse down
+    # start_y - Fixnum representing the y of the mouse down
+    # end_x   - Fixnum representing the x of the mouse up
+    # end_y   - Fixnum representing the y of the mouse up
+    #
+    # Examples
+    #
+    #   region.drag_drop(20, 12, 23, 44)
+    #
+    # Returns nothing
+    def drag_drop(start_x, start_y, end_x, end_y)
       @java_obj.dragDrop(
         org.sikuli.script::Location.new(start_x, start_y).offset(x(), y()),
         org.sikuli.script::Location.new(end_x, end_y).offset(x(), y()),
@@ -26,20 +66,40 @@ module Sikuli
 
     private
 
-    def click_image(filename, opts = {})
+    # Private: clicks on a matched Region based on an image based search
+    #
+    # filename - A String representation of the filename of the region to
+    # match against
+    # is_double - (optional) Boolean determining if should be a double click
+    #
+    # Returns nothing
+    #
+    # Throws Sikuli::FileNotFound if the file could not be found on the system
+    # Throws Sikuli::ImageNotMatched if no matches are found within the region
+    def click_image(filename, is_double = false)
       begin
-        if opts[:double]
+        if is_double
           @java_obj.doubleClick(filename, 0)
         else
           @java_obj.click(filename, 0)
         end
-      rescue
-        raise "File Not Found: #{filename}"
+      rescue NativeException => e
+        raise_exception e, filename
       end
     end
 
-    def click_point(x, y, opts = {})
-      if opts[:double]
+    # Private: clicks on a point relative to a Region's top left corner
+    #
+    # x         - a Fixnum representing the x component of the point to click
+    # y         - a Fixnum representing the y component of the point to click
+    # is_double - (optional) Boolean determining if should be a double click
+    #
+    # Returns nothing
+    #
+    # Throws Sikuli::FileNotFound if the file could not be found on the system
+    # Throws Sikuli::ImageNotMatched if no matches are found within the region
+    def click_point(x, y, is_double = false)
+      if is_double
         @java_obj.doubleClick(org.sikuli.script::Location.new(x, y).offset(x(), y()), 0)
       else
         @java_obj.click(org.sikuli.script::Location.new(x, y).offset(x(), y()), 0)

data/lib/sikuli/config.rb

@@ -1,16 +1,42 @@
+# Config variables for the Sikuli driver
+#
 module Sikuli
   class Config
     class << self
+
+      # Public: the Boolean representing whether or not to perform a 1 second
+      # highlight when an image is matched through Searchable#find,
+      # Searchable#find_all. Defaults to false.
       attr_accessor :highlight_on_find
 
+      # Public: the absolute file path where Sikuli will look for images when
+      # a just a filename is passed to a search or click method
+      #
+      # Returns the String representation of the path
       def image_path
         java.lang.System.getProperty("SIKULI_IMAGE_PATH")
       end
 
+      # Public: the setter for the absolute file path where Sikuli will search
+      # for images with given a filename as an image
+      #
+      # Examples
+      #
+      #  Sikuli::Config.image_path = "/Users/clemley/sikuli/images/"
+      #
+      # Returns nothing
       def image_path=(path)
         java.lang.System.setProperty("SIKULI_IMAGE_PATH", path)
       end
 
+      # Public: turns stdout logging on and off for the Sikuli java classes.
+      # Defaults to true.
+      #
+      # Examples
+      #
+      #  Sikuli::Config.logging = false
+      #
+      # Returns nothing
       def logging=(boolean)
         return unless [TrueClass, FalseClass].include? boolean.class
         org.sikuli.script::Settings.InfoLogs = boolean
@@ -18,6 +44,18 @@ module Sikuli
         org.sikuli.script::Settings.DebugLogs = boolean
       end
 
+      # Public: convienence method for grouping the setting of config
+      # variables
+      #
+      # Examples
+      #
+      #   Sikuli::Config.run do |config|
+      #     config.logging = true
+      #     config.image_path = "/User/clemley/images"
+      #     config.highlight_on_find = true
+      #   end
+      #
+      # Returns nothing
       def run(*args)
         if block_given?
           yield self

data/lib/sikuli/exception.rb

@@ -0,0 +1,14 @@
+# Exception classes for Sikuli image searching and matching
+#
+module Sikuli
+
+  # Thrown when Sikuli is unable to find a match within the region for the
+  # file given.
+  #
+  class ImageNotFound < StandardError; end
+
+  # Thrown when a filename is given that is not found on disk in the image
+  # path. Image path can be configured using Sikuli::Config.image_path
+  #
+  class FileDoesNotExist < StandardError; end
+end

data/lib/sikuli/key_code.rb

@@ -1,14 +1,26 @@
+# These constants represent keyboard codes for interacting with the keyboard.
+# Keyboard interaction is defined in the Sikuli::Typeable module.
+#
 module Sikuli
+
+  # Command Key
   KEY_CMD   = java.awt.event.InputEvent::META_MASK
+
+  # Shift Key
   KEY_SHIFT = java.awt.event.InputEvent::SHIFT_MASK
+
+  # Control Key
   KEY_CTRL  = java.awt.event.InputEvent::CTRL_MASK
+
+  # Alt Key
   KEY_ALT   = java.awt.event.InputEvent::ALT_MASK
 
+  # Backspace Key
   KEY_BACKSPACE = "\u0008"
+
+  # Return Key
   KEY_RETURN    = "\n"
 
-  UP_ARROW      = nil
+  # Left Arrow Key
   LEFT_ARROW    = "\ue003"
-  DOWN_ARROW    = nil
-  RIGHT_ARROW   = nil
 end

data/lib/sikuli/region.rb

@@ -1,3 +1,7 @@
+# A Region represents a rectangle on screen. Regions are the main point of
+# interaction for Sikuli actions. Regions can receive actions from the mouse,
+# keyboard, and image search.
+#
 require "sikuli/clickable"
 require "sikuli/typeable"
 require "sikuli/searchable"
@@ -8,28 +12,68 @@ module Sikuli
     include Typeable
     include Searchable
 
+    # Public: creates a new Region object
+    #
+    # args - Array representing x (left bound), y (top), width, height
+    #        4 Fixnums left, top, width, height
+    #        An instance of an org.sikuli.script::Region
+    #
+    #   Examples
+    #
+    #     Region.new([10, 10, 200, 300])
+    #     Region.new(10, 10, 200, 300)
+    #     Region.new(another_region)
+    #
+    # Returns the newly initialized object
     def initialize(*args)
       @java_obj = org.sikuli.script::Region.new(*args)
     end
 
+    # Public: highlight the region with a ~ 5 pixel red border
+    #
+    # seconds - Fixnum length of time to show border
+    #
+    # Returns nothing
     def highlight(seconds = 1)
       @java_obj.highlight(seconds)
     end
 
+    # Public: the x component of the top, left corner of the Region
     def x
       @java_obj.x()
     end
 
+    # Public: the y component of the top, left corner of the Region
     def y
       @java_obj.y()
     end
 
+    # Public: the width in pixels of the Region
     def width
       @java_obj.w()
     end
 
+    # Public: the height in pixels of the Region
     def height
       @java_obj.h()
     end
+
+    private
+
+    # Private: interpret a java NativeException and raises a more descriptive
+    # exception
+    #
+    # exception - The original java exception thrown by the sikuli java_obj
+    # filename  - A string representing the filename to include in the
+    # exception message
+    #
+    # Returns nothing
+    def raise_exception(exception, filename)
+      if exception.message == "org.sikuli.script.FindFailed: File null not exists"
+        raise Sikuli::FileDoesNotExist, "The file '#{filename}' does not exist."
+      else
+        raise Sikuli::ImageNotFound, "The image '#{filename}' did not match in this region."
+      end
+    end
   end
 end

data/lib/sikuli/screen.rb

@@ -1,5 +1,18 @@
+# A Screen object defines a special type of Sikuli::Region that represents
+# the entire screen.
+#
+# TODO: Test the Screen object with multiple monitors attached.
+#
 module Sikuli
   class Screen < Region
+
+    # Public: creates a new Screen object
+    #
+    # Examples
+    #
+    #   screen = Sikuli::Screen.new
+    #
+    # Returns the newly initialized Screen object
     def initialize
       @java_obj = org.sikuli.script::Screen.new()
     end

data/lib/sikuli/searchable.rb

@@ -1,20 +1,109 @@
+# The Sikuli::Searchable module is the heart of Sikuli. It defines the
+# wrapper around Sikuli's on screen image searching and matching capability
+# It is implemented by the Region class.
+#
 module Sikuli
   module Searchable
+
+    # Public: search for an image within a Region
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Examples
+    #
+    #   region.find('needle.png')
+    #   region.find('needle.png', 0.5)
+    #
+    # Returns an instance of Region representing the best match
+    #
+    # Throws Sikuli::FileNotFound if the file could not be found on the system
+    # Throws Sikuli::ImageNotMatched if no matches are found within the region
     def find(filename, similarity = 0.9)
       begin
-        pattern = org.sikuli.script::Pattern.new(filename).similar(similarity)
+        pattern = build_pattern(filename, similarity)
         region = Region.new(@java_obj.find(pattern))
         region.highlight if Sikuli::Config.highlight_on_find
         return region
-      rescue
-        raise "File Not Found: #{filename}"
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    # Public: search for an image within a Region and return all matches
+    #
+    # TODO: Sort return results so they are always returned in the same order
+    # (top left to bottom right)
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Examples
+    #
+    #   region.find_all('needle.png')
+    #   region.find_all('needle.png', 0.5)
+    #
+    # Returns an array of Region objects that match the given file and
+    # threshold
+    #
+    # Throws Sikuli::FileNotFound if the file could not be found on the system
+    # Throws Sikuli::ImageNotMatched if no matches are found within the region
+    def find_all(filename, similarity = 0.9)
+      begin
+        pattern = build_pattern(filename, similarity)
+        matches = @java_obj.findAll(pattern)
+        regions = matches.collect do |r|
+          match = Region.new(r)
+          match.highlight if Sikuli::Config.highlight_on_find
+          match
+        end
+        return regions
+      rescue NativeException => e
+        raise_exception e, filename
       end
     end
 
+    # Public: check if an image is matched within a Region
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    # time       - time in seconds to search before returning false
+    #
+    # Examples
+    #
+    #   region.exists?('needle.png')
+    #   region.exists?('needle.png', 0.5)
+    #   region.exists?('needle.png', 0.5, 3)
+    #
+    # Returns a Boolean (true if match found, false if not)
     def exists?(filename, similarity = 0.9, time = 0.5)
-      pattern = org.sikuli.script::Pattern.new(filename).similar(similarity)
+      pattern = build_pattern(filename, similarity)
       @java_obj.exists(pattern, time)
     end
+
+    # Public: alias for exists?
+    #
+    # Returns a Boolean (true if match found, false if not)
     alias_method :contains?, :exists?
+
+    private
+
+    # Private: builds a java Pattern to check
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Returns a org.sikuli.script::Pattern object to match against
+    def build_pattern(filename, similarity)
+      org.sikuli.script::Pattern.new(filename).similar(similarity)
+    end
   end
-end
+end

data/lib/sikuli/typeable.rb

@@ -1,5 +1,21 @@
+# Defines interactions with the keyboard. Implemented in the Region class.
+#
 module Sikuli
   module Typeable
+
+    # Public: Types text as if it was being typed on the keyboard with an
+    # optional key modifier
+    #
+    # text - String representing text to be typed on keyboard
+    # modifier - (optional) Sikilu constant (defined in key_code.rb)
+    # representing key to hold while typing text
+    #
+    # Examples
+    #
+    #   region.type("Hello World")
+    #   region.type("s", Sikuli::KEY_CMD) # saves a file
+    #
+    # Returns nothing
     def type(text, modifier = 0)
       @java_obj.type(nil, text, modifier)
     end

data/lib/sikuli/version.rb

@@ -1,3 +1,3 @@
 module Sikuli
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

data/spec/sikuli/clickable_spec.rb

@@ -10,15 +10,15 @@ describe Sikuli::Region, "#Clickable" do
   end
 
   it "should perform a double click 10, 1040" do
-    lambda { @region.doubleClick(12, 491) }.should_not raise_error
+    lambda { @region.double_click(12, 491) }.should_not raise_error
   end
 
   it "should perform a double click on an image" do
-    lambda { @region.doubleClick("smiley_face.png") }.should_not raise_error
+    lambda { @region.double_click("smiley_face.png") }.should_not raise_error
   end
 
   it "should perform a drag and drop" do
-    lambda { @region.dragDrop(12, 12, 491, 491) }.should_not raise_error
+    lambda { @region.drag_drop(12, 12, 491, 491) }.should_not raise_error
   end
 
   it "should perform a click on an image" do
@@ -26,6 +26,7 @@ describe Sikuli::Region, "#Clickable" do
   end
 
   it "should not perform a click on an image that is outside of the region" do
-    lambda { @region.click("apple.png")}.should raise_error
+    lambda { @region.click("apple.png") }.should
+      # raise_error(Sikuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
   end
 end

data/spec/sikuli/searchable_spec.rb

@@ -13,8 +13,14 @@ describe Sikuli::Region, "#Searchable" do
     @region.find("smiley_face.png").should be_an_instance_of Sikuli::Region
   end
 
+  it "should raise an error if a file can not be found" do
+    lambda { @region.find("no_photo.png") }.should
+      raise_error(Sikuli::FileDoesNotExist, "The file 'no_photo.png' does not exist.")
+  end
+
   it "should not find an image that is not in the region" do
-    lambda { @region.find("apple.png") }.should raise_error
+    lambda { @region.find("apple.png") }.should
+      raise_error(Sikuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
   end
 
   it "should return true if the image is found" do
@@ -28,4 +34,33 @@ describe Sikuli::Region, "#Searchable" do
   it "should return false if the image is not found" do
     @region.exists?("apple.png").should be_false
   end
+
+  it "should return false if the file does not exist" do
+    @region.exists?("no_photo.png").should be_false
+  end
+
+  context "#find_all" do
+    before(:all) do
+      @matches = @region.find_all("green_apple.png")
+    end
+
+    it "should raise an error if no matches are found" do
+      lambda { @region.find_all("apple.png") }.should
+        raise_error(Sikuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
+    end
+
+    it "should return an array" do
+      @matches.should be_an_instance_of Array
+    end
+
+    it "should contain 4 matches" do
+      @matches.length.should == 4
+    end
+
+    it "should contain regions" do
+      @matches.each do |m|
+        m.should be_an_instance_of Sikuli::Region
+      end
+    end
+  end
 end

data/spec/sikuli/typeable_spec.rb

@@ -21,9 +21,6 @@ describe Sikuli::Region, "#Typeable" do
   context "unicode characters" do
     it("backspace")   { @region.type(Sikuli::KEY_BACKSPACE * 50) }
     it("return")      { @region.type(Sikuli::KEY_RETURN) }
-    xit("up arrow")   { @region.type(Sikuli::UP_ARROW) }
     it("left arrow")  { @region.type(Sikuli::LEFT_ARROW) }
-    it("down arrow")  { @region.type(Sikuli::DOWN_ARROW) }
-    it("right arrow") { @region.type(Sikuli::RIGHT_ARROW) }
   end
 end

metadata

@@ -2,7 +2,7 @@
 name: sikuli
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors: 
   - Chas Lemley
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-28 00:00:00 -04:00
+date: 2011-07-30 00:00:00 -04:00
 default_executable: 
 dependencies: 
   - !ruby/object:Gem::Dependency 
@@ -42,6 +42,7 @@ files:
   - lib/sikuli/app.rb
   - lib/sikuli/clickable.rb
   - lib/sikuli/config.rb
+  - lib/sikuli/exception.rb
   - lib/sikuli/key_code.rb
   - lib/sikuli/region.rb
   - lib/sikuli/screen.rb
@@ -59,6 +60,7 @@ files:
   - spec/sikuli/typeable_spec.rb
   - spec/spec_helper.rb
   - spec/support/images/apple.png
+  - spec/support/images/green_apple.png
   - spec/support/images/smiley_face.png
   - spec/support/images/test_area.jpg
 has_rdoc: true
@@ -99,5 +101,6 @@ test_files:
   - spec/sikuli/typeable_spec.rb
   - spec/spec_helper.rb
   - spec/support/images/apple.png
+  - spec/support/images/green_apple.png
   - spec/support/images/smiley_face.png
   - spec/support/images/test_area.jpg