winwindow 0.4.0

data/lib/winwindow/ext.rb

@@ -0,0 +1,88 @@
+# extensions to the language which are external to what the WinWindow library itself does 
+
+class WinWindow # :nodoc:all
+  
+  # takes given options and default options, and optionally a list of additional allowed keys not specified in default options
+  # (this is useful when you want to pass options along to another function but don't want to specify a default that will
+  # clobber that function's default) 
+  # raises ArgumentError if the given options have an invalid key (defined as one not
+  # specified in default options or other_allowed_keys), and sets default values in given options where nothing is set.
+  def self.handle_options(given_options, default_options, other_allowed_keys=[]) # :nodoc:
+    given_options=given_options.dup
+    unless (unknown_keys=(given_options.keys-default_options.keys-other_allowed_keys)).empty?
+      raise ArgumentError, "Unknown options: #{(given_options.keys-default_options.keys).map(&:inspect).join(', ')}. Known options are #{(default_options.keys+other_allowed_keys).map(&:inspect).join(', ')}"
+    end
+    (default_options.keys-given_options.keys).each do |key|
+      given_options[key]=default_options[key]
+    end
+    given_options
+  end
+  
+  def handle_options(*args) # :nodoc:
+    self.class.handle_options(*args)
+  end
+  # Default exception class raised by Waiter when a timeuot is reached 
+  class WaiterError < StandardError # :nodoc:
+  end
+  module Waiter # :nodoc:all
+    # Tries for +time+ seconds to get the desired result from the given block. Stops when either:
+    # 1. The :condition option (which should be a proc) returns true (that is, not false or nil)
+    # 2. The block returns true (that is, anything but false or nil) if no :condition option is given
+    # 3. The specified amount of time has passed. By default a WaiterError is raised. 
+    #    If :exception option is given, then if it is nil, no exception is raised; otherwise it should be
+    #    an exception class or an exception instance which will be raised instead of WaiterError
+    #
+    # Returns the value of the block, which can be handy for things that return nil on failure and some 
+    # other object on success, like Enumerable#detect for example: 
+    #  found_thing=Waiter.try_for(30){ all_things().detect{|thing| thing.name=="Bill" } }
+    #
+    # Examples:
+    #  Waiter.try_for(30) do
+    #    Time.now.year == 2015
+    #  end
+    # Raises a WaiterError unless it is called between the last 30 seconds of December 31, 2014 and the end of 2015
+    #
+    #  Waiter.try_for(365*24*60*60, :interval => 0.1, :exception => nil, :condition => proc{ 2+2==5 }) do
+    #    STDERR.puts "any decisecond now ..."
+    #  end
+    # 
+    # Complains to STDERR for one year, every tenth of a second, as long as 2+2 does not equal 5. Does not 
+    # raise an exception if 2+2 does not become equal to 5. 
+    def self.try_for(time, options={})
+      unless time.is_a?(Numeric) && options.is_a?(Hash)
+        raise TypeError, "expected arguments are time (a numeric) and, optionally, options (a Hash). received arguments #{time.inspect} (#{time.class}), #{options.inspect} (#{options.class})"
+      end
+      options=WinWindow.handle_options(options, {:interval => 0.02, :condition => proc{|_ret| _ret}, :exception => WaiterError})
+      started=Time.now
+      begin
+        ret=yield
+        break if options[:condition].call(ret)
+        sleep options[:interval]
+      end while Time.now < started+time && !options[:condition].call(ret)
+      if options[:exception] && !options[:condition].call(ret)
+        ex=if options[:exception].is_a?(Class)
+          options[:exception].new("Waiter waited #{time} seconds and condition was not met")
+        else
+          options[:exception]
+        end
+        raise ex
+      end
+      ret
+    end
+  end
+end
+module Kernel # :nodoc:
+  # this is the Y-combinator, which allows anonymous recursive functions. for a simple example, 
+  # to define a recursive function to return the length of an array:
+  #
+  #  length = ycomb do |len|
+  #    proc{|list| list == [] ? 0 : len.call(list[1..-1]) }
+  #  end
+  #
+  # see https://secure.wikimedia.org/wikipedia/en/wiki/Fixed_point_combinator#Y_combinator
+  # and chapter 9 of the little schemer, available as the sample chapter at http://www.ccs.neu.edu/home/matthias/BTLS/
+  def ycomb
+    proc{|f| f.call(f) }.call(proc{|f| yield proc{|*x| f.call(f).call(*x) } })
+  end
+  module_function :ycomb
+end

data/test/winwindow_test.rb

@@ -0,0 +1,292 @@
+libdir = File.join(File.dirname(__FILE__), '..', 'lib')
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.any?{|p| File.expand_path(p) == File.expand_path(libdir) }
+
+require 'winwindow'
+
+require 'minitest/unit'
+MiniTest::Unit.autorun
+
+class TestWinWindow < MiniTest::Unit::TestCase
+  def setup
+    @ie_ole, @win = *new_ie_ole
+  end
+  
+  def teardown
+    @ie_ole.Quit
+  end
+  
+  # make a new IE win32ole window for testing. also send it to the given url (default is google) and wait for that to load. 
+  def new_ie_ole(url='http://google.com')
+    require 'win32ole'
+    ie_ole=nil
+    WinWindow::Waiter.try_for(32) do
+      begin
+        ie_ole = WIN32OLE.new('InternetExplorer.Application')
+        ie_ole.Visible=true
+        true
+      rescue WIN32OLERuntimeError, NoMethodError
+        false
+      end
+    end
+    ie_ole.Navigate url
+    WinWindow::Waiter.try_for(32, :exception => "The browser's readyState did not become ready for interaction") do
+      [3, 4].include?(ie_ole.readyState)
+    end
+    [ie_ole, WinWindow.new(ie_ole.HWND)]
+  end
+  
+  def with_ie(*args)
+    ie_ole, win = *new_ie_ole(*args)
+    begin
+      yield ie_ole, win
+    ensure
+      ie_ole.Quit
+    end
+  end
+  
+  def launch_popup(text="popup!", ie_ole=@ie_ole)
+    raise ArgumentError, "No double-quotes or backslashes, please" if text =~ /["\\]/
+    ie_ole.Navigate('javascript:alert("'+text+'")')
+    popup = WinWindow::Waiter.try_for(16, :exception => "No popup appeared on the browser!"){ WinWindow.new(@ie_ole.HWND).enabled_popup }
+  end
+  
+  def with_popup(text="popup!", ie_ole=@ie_ole)
+    popup = launch_popup(text, ie_ole)
+    begin
+      yield popup
+    ensure
+      popup.click_child_button_try_for!(//, 8)
+    end
+  end
+  
+  def assert_eventually(message=nil, options={}, &block)
+    options[:exception] ||= nil
+    timeout = options.delete(:timeout) || 16
+    result = WinWindow::Waiter.try_for(timeout, options, &block)
+    message ||= "Expected block to eventually yield true; after #{timeout} seconds it was #{result}"
+    assert result, message
+  end
+  
+  def test_hwnd
+    assert_equal @win.hwnd, @ie_ole.HWND
+  end
+  def test_inspect
+    assert_includes @win.inspect, @win.hwnd.to_s
+    assert_includes @win.inspect, @win.retrieve_text
+  end
+  def test_text
+    assert_match /google/i, @win.retrieve_text
+    assert_match /google/i, @win.text # might fail? it is not meant to retrieve text of a control in another application? well, it seems to work. 
+  end
+  def test_set_text
+    assert_eventually do
+      @win.set_text! 'foobar'
+      @win.text=='foobar'
+    end
+    assert_eventually do
+      @win.send_set_text! 'bazqux'
+      @win.retrieve_text=='bazqux'
+    end
+  end
+  def test_popup
+    text='popup!'
+    with_popup(text) do
+      assert_instance_of(WinWindow, @win.enabled_popup)
+      assert(@win.enabled_popup.children.any?{|child| child.text.include?(text) }, "Enabled popup should include the text #{text}")
+      assert_equal(@win.enabled_popup, @win.last_active_popup)
+    end
+  end
+  def test_owner_ancestors_parent_child
+    with_popup do |popup|
+      assert_equal(popup.owner, @win)
+      assert_equal(popup.ancestor_parent, WinWindow.desktop_window)
+      assert_equal(popup.ancestor_root, popup)
+      assert_equal(popup.ancestor_root_owner, @win)
+      assert_equal(popup.parent, @win)
+      button = popup.child_button(//)
+      assert_equal(button.owner, nil)
+      assert_equal(button.ancestor_parent, popup)
+      assert_equal(button.ancestor_root, popup)
+      assert_equal(button.ancestor_root_owner, @win)
+      assert_equal(button.parent, popup)
+      assert(button.child_of?(popup))
+    end
+  end
+  def test_set_parent
+    with_ie do |ie_ole2, win2|
+      with_popup do |popup|
+        assert_equal WinWindow.desktop_window, popup.ancestor_parent
+        popup.set_parent! win2
+        assert_equal win2, popup.ancestor_parent
+      end
+    end
+  end
+  def test_hung_app
+    assert !@win.hung_app?
+    # I don't know how to make IE freeze to test the true case (you wouldn't expect making IE freeze to be a diffult thing, would you?)
+  end
+  def test_class_name
+    with_popup do |popup|
+      assert popup.children.any?{|child| child.class_name=="Static"}
+      assert popup.children.any?{|child| child.class_name=="Button"}
+      assert popup.real_class_name == popup.class_name
+    end
+  end
+  def test_thread_id_process_id
+    # I don't know how to properly test this. just check that it looks id-like 
+    assert @win.thread_id.is_a?(Integer)
+    assert @win.thread_id > 0
+    assert @win.process_id.is_a?(Integer)
+    assert @win.process_id > 0
+  end
+  def test_exists
+    temp_ie, twin = *new_ie_ole
+    assert twin.exists?
+    temp_ie.Quit
+    assert_block do
+      WinWindow::Waiter.try_for(8) do
+        !twin.exists?
+      end
+    end
+  end
+  def test_visible
+    @ie_ole.Visible = true
+    assert @win.visible?
+    @ie_ole.Visible = false
+    assert !@win.visible?
+  end
+  def test_min_max_iconic_foreground
+    with_ie do |ie_ole2, win2|
+      @win.close! # this is actually minimize 
+      assert @win.iconic?
+      @win.really_set_foreground!
+      assert @win.foreground?
+      win2.really_set_foreground!
+      assert win2.foreground?
+      # I don't know what to do with the rest of these - no idea what the differenc
+      # is between most of them, and no real way to test their effects. 
+      # but there's not really much to screw up. 
+      # I'll just assume that if they don't error all is well. 
+      @win.set_foreground!
+      @win.switch_to!
+      @win.bring_to_top!
+      @win.hide!
+      @win.show_normal!
+      @win.show_minimized!
+      @win.show_maximized!
+      @win.maximize!
+      @win.show_no_activate!
+      @win.show!
+      @win.minimize!
+      @win.show_min_no_active!
+      @win.show_na!
+      @win.restore!
+      @win.show_default!
+      @win.force_minimize!
+    end
+  end
+  def test_end_close_destroy
+    @win.destroy! 
+    # no idea when this ever does anything, just seems to return false. will be content with it not erroring, I suppose. 
+    @ie_ole, @win = *new_ie_ole unless @win.exists?
+
+    assert_eventually do
+      @win.really_set_foreground!
+      @win.end_task!
+      !@win.exists?
+    end
+    @ie_ole, @win = *new_ie_ole unless @win.exists?
+    
+    assert_eventually do
+      @win.really_set_foreground!
+      @win.send_close!
+      !@win.exists?
+    end
+    @ie_ole, @win = *new_ie_ole unless @win.exists?
+  end
+  def test_click
+    # dismissing the popup relies on clicking; we'll use that to test. 
+    with_popup do
+      assert @win.enabled_popup
+    end
+    assert !@win.enabled_popup
+  end
+  def test_screen_capture
+    # writing to file tests all the screen capture functions (at least that they don't error)
+    filename = 'winwindow.bmp'
+    @win.capture_to_bmp_file filename
+    assert File.exists?(filename)
+    assert File.size(filename) > 0
+    # todo: check it's valid bmp with the right size (check #window_rect/#client_rect)? use rmagick? 
+    File.unlink filename
+  end
+  def test_children_and_all
+    assert @win.children.is_a?(Enumerable)
+    assert WinWindow::All.is_a?(Enumerable)
+    cwins=[]
+    @win.each_child do |cwin|
+      assert cwin.is_a?(WinWindow)
+      assert cwin.exists?
+      assert cwin.child_of?(@win)
+      cwins << cwin
+    end
+    assert_equal @win.children.to_a, cwins
+    assert cwins.size > 0
+    all_wins = []
+    WinWindow.each_window do |win|
+      assert win.is_a?(WinWindow)
+      assert win.exists?
+      all_wins << win
+    end
+    assert_equal WinWindow::All.to_a, all_wins
+    assert all_wins.size > 0
+  end
+  def test_children_recursive
+    cwins = []
+    @win.recurse_each_child do |cwin|
+      assert cwin.is_a?(WinWindow)
+      assert cwin.exists?
+      #assert cwin.child_of?(@win)
+      cwins << cwin
+    end
+    assert_equal @win.children_recursive.to_a, cwins
+    require 'set'
+    assert Set.new(@win.children).subset?(Set.new(@win.children_recursive))
+  end
+  def test_system_error
+    assert_raises(WinWindow::SystemError) do
+      begin
+        @win.recurse_each_child(:rescue_enum_child_windows => false) { nil }
+      rescue WinWindow::SystemError # not really rescuing, just checking info
+        assert_equal 'EnumChildWindows', $!.function
+        assert $!.code.is_a?(Integer)
+        raise
+      end
+    end
+  end
+  def test_finding
+    assert WinWindow.find_first_by_text(//).is_a?(WinWindow)
+    found_any = false
+    WinWindow.find_all_by_text(//).each do |win|
+      assert win.is_a?(WinWindow)
+      assert win.exists?
+      found_any = true
+    end
+    assert found_any
+    assert(WinWindow.find_only_by_text(@win.retrieve_text)==@win)
+    with_ie do
+      assert_raises(WinWindow::MatchError) do
+        WinWindow::Waiter.try_for(32) do # this doesn't always come up immediately, so give it a moment 
+          WinWindow.find_only_by_text(@win.retrieve_text)
+          false
+        end
+      end
+    end
+  end
+  def test_foreground_desktop
+    assert WinWindow.foreground_window.is_a?(WinWindow)
+    assert WinWindow.foreground_window.exists?
+    assert WinWindow.desktop_window.is_a?(WinWindow)
+    assert WinWindow.desktop_window.exists?
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: winwindow
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 4
+  - 0
+  version: 0.4.0
+platform: ruby
+authors: 
+- Ethan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-01 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ffi
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 4
+        version: 0.5.4
+  type: :runtime
+  version_requirements: *id001
+description: A Ruby library to wrap windows API calls relating to hWnd window handles.
+email: vapir@googlegroups.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/winwindow.rb
+- lib/winwindow/ext.rb
+has_rdoc: true
+homepage: http://winwindow.vapir.org/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset
+- UTF-8
+- --show-hash
+- --inline-source
+- --main
+- WinWindow
+- --title
+- WinWindow
+- --tab-width
+- "2"
+- lib/winwindow.rb
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: 
+- Microsoft Windows, probably with some sort of NT kernel
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A Ruby library to wrap windows API calls relating to hWnd window handles.
+test_files: 
+- test/winwindow_test.rb