win_gui 0.2.17 → 0.2.18

data/HISTORY

@@ -73,3 +73,7 @@
 == 0.2.17 / 2010-10-18
 
 * Gemspec changed for Bundler
+
+== 0.2.18 / 2011-02-17
+
+* Full Regexp support for Window find operations

data/README.rdoc

@@ -7,7 +7,8 @@ url:: http://github.com/arvicco/win_gui
 WinGui is a module that provides higher-level abstractions/wrappers around GUI-related
 Win32 API functions. It uses Win gem as a basis, which in turn uses FFI.
 So (in theory) it should work for any Ruby implementation supporting FFI. In practice,
-it's only been tested under mingw and cygwin flavors of Ruby 1.9.1.
+it's only been tested under mingw and cygwin flavors of Ruby 1.9. Porting to JRuby is
+under way, waiting for its 1.9 compatibility to mature.
 
 == SUMMARY:
 
@@ -32,26 +33,24 @@ For example, here is how you deal with typical GUI-related tasks using Win:
   end
   close_window(window_handle)
 
-Ideally, there should be a thin wrapper class around window handle, and the code above should be more like this:
+This works fine, but such functional style is does not feel like object-oriented Ruby.
+Ideally, there should be a thin wrapper class around window handle, and the code above
+should be more like this:
+
   require 'win_gui'
   include WinGui
 
-  window = Window.find(:first, :class => 'WinClass')
+  window = Window.find(:title => /PartTitle/)
   puts window.handle, window.title, window.thread, window.process
-  window.each_child {|child| puts child.handle, child.title, child.thread, child.process }
+  window.children.each {|child| puts child.handle, child.title, child.thread, child.process }
   window.close
 
-This library will try to provide such wrappers and convenience methods that will make working with
-Windows GUI-related code much more fun than it is right now.
+WinGui library strives to provide such wrappers and convenience methods that will make
+working with Windows GUI-related code much more fun than it is right now.
 
 == REQUIREMENTS:
 
-Only works with Ruby 1.9.1+ compatible implementations since Win gem uses some of latest Ruby features.
-
-== FEATURES/PROBLEMS:
-
-This project is quite new, so it may be not suitable for production-quality systems yet.
-Contributors always welcome!
+Only works with Ruby 1.9 compatible implementations since Win gem uses some of latest Ruby features.
 
 == INSTALL:
 

data/VERSION

@@ -1 +1 @@
-0.2.17
+0.2.18

data/lib/win_gui/window.rb

@@ -14,7 +14,7 @@ module WinGui
       # Returns either Window instance (for a found handle) or nil if nothing found.
       # Private method to dry up other window lookup methods
       #
-      def lookup_window(opts) # :yields: index, position
+      def lookup_window opts # :yields: index, position
         # Need this to avoid handle considered local var in begin..end block
         handle = yield
         if opts[:timeout]
@@ -30,40 +30,63 @@ module WinGui
         Window.new(handle) if handle
       end
 
+      def lookup_window_in_collection opts, &collection_proc
+        class_name   = opts[:class]
+        title        = opts[:title]
+        id           = opts[:id]
+        class_regexp = class_name.is_a? Regexp
+        title_regexp = title.is_a? Regexp
+
+        lookup_window(opts) do
+          collection_proc.call.each do |handle|
+            win         = Window.new handle
+
+            id_match    = !id || win.id == id
+            title_match = !title || win.title == title ||
+                title_regexp && win.title =~ title
+            class_match = !class_name || win.class_name == class_name ||
+                class_regexp && win.class_name =~ class_name
+            return win if class_match && title_match && id_match
+          end
+          nil
+        end
+      end
+
       # Finds top level window by title/class, returns wrapped Window object or nil (raises exception if asked to).
       # If timeout option given, waits for window to appear within timeout, returns nil if it didn't.
       # Options:
-      # :title:: window title
-      # :class:: window class
+      # :title:: window title (String or Regexp)
+      # :class:: window class (String or Regexp)
       # :timeout:: timeout (seconds)
       # :raise:: raise this exception instead of returning nil if nothing found
       #
-      def top_level(opts={})
-        lookup_window(opts) { WinGui.find_window opts[:class], opts[:title] }
+      def top_level opts={}
+        if opts[:class].is_a?(Regexp) or opts[:title].is_a?(Regexp)
+          lookup_window_in_collection(opts) { WinGui.enum_windows }
+        else
+          lookup_window(opts) { WinGui.find_window opts[:class], opts[:title] }
+        end
       end
-      alias_method :find, :top_level
+
+      alias find top_level
     end
 
     # Finds child window (control) by either control ID or window class/title.
     # By default, only direct children are searched.
     # Options:
     # :id:: integer control id (such as IDOK, IDCANCEL, etc)
-    # :title:: window title
-    # :class:: window class
+    # :title:: window title (String or Regexp)
+    # :class:: window class (String or Regexp)
     # :indirect:: search all descendants, not only direct children
     # :timeout:: timeout (seconds)
     # :raise:: raise this exception instead of returning nil if nothing found
-    # TODO: add the ability to nail indirect children as well
     #
     def child(opts={})
       if opts[:indirect]
-        self.class.lookup_window opts do
-          found = children.find do |child|
-            (opts[:id] ? child.id == opts[:id] : true) &&
-                    (opts[:class] ? child.class_name == opts[:class] : true) &&
-                    (opts[:title] ? child.title == opts[:title] : true)
-          end
-          found.handle if found
+        self.class.lookup_window_in_collection(opts) { enum_child_windows }
+      elsif opts[:class].is_a?(Regexp) or opts[:title].is_a?(Regexp)
+        self.class.lookup_window_in_collection(opts) do
+          enum_child_windows.select { |handle| child? handle }
         end
       else
         self.class.lookup_window opts do
@@ -106,9 +129,9 @@ module WinGui
         WinGui.set_cursor_pos *point
 
         button = opts[:mouse_button] || opts[:mouse] || opts[:which]
-        down, up =  (button == :right) ?
-                [WinGui::MOUSEEVENTF_RIGHTDOWN, WinGui::MOUSEEVENTF_RIGHTUP] :
-                [WinGui::MOUSEEVENTF_LEFTDOWN, WinGui::MOUSEEVENTF_LEFTUP]
+        down, up = (button == :right) ?
+            [WinGui::MOUSEEVENTF_RIGHTDOWN, WinGui::MOUSEEVENTF_RIGHTUP] :
+            [WinGui::MOUSEEVENTF_LEFTDOWN, WinGui::MOUSEEVENTF_LEFTUP]
 
         WinGui.mouse_event down, 0, 0, 0, 0
         WinGui.mouse_event up, 0, 0, 0, 0
@@ -150,6 +173,8 @@ module WinGui
       get_window_thread_process_id.last
     end
 
+    alias pid process
+
     # Control ID associated with the window (only makes sense for controls)
     def id
       get_dlg_ctrl_id

data/spec/win_gui/window_spec.rb

@@ -1,5 +1,104 @@
 require "spec_helper.rb"
 
+shared_examples_for 'normal window finder' do
+  it 'finds top-level window by title and wraps it in a Window object' do
+    window = Window.top_level(:title => title, timeout: 1)
+    window.handle.should == @win.handle
+  end
+
+  it 'finds top-level window by class and wraps it in a Window object' do
+    window = Window.top_level(:class => class_name, timeout: 1)
+    window.handle.should == @win.handle
+  end
+
+  it 'finds top-level window by both class and title' do
+    window = Window.top_level(:class => class_name, :title => title)
+    window.handle.should == @win.handle
+  end
+
+  it 'finds top-level window by both class and title' do
+    window = Window.top_level(:class => class_name, :title => title)
+    window.handle.should == @win.handle
+  end
+
+  it 'returns nil if either window title or class do not match' do
+    Window.top_level(:class => class_name, :title => impossible).should == nil
+    Window.top_level(:class => impossible, :title => title).should == nil
+  end
+
+  it 'returns nil immediately if top-level window not found' do
+    start = Time.now
+    Window.top_level(:title => impossible).should == nil
+    (Time.now - start).should be_within(0.05).of 0
+  end
+
+  it 'returns nil after timeout if top-level window not found' do
+    start = Time.now
+    Window.top_level(:title => impossible, :timeout => 0.3).should == nil
+    (Time.now - start).should be_within(0.05).of 0.3
+  end
+
+  it 'raises exception if asked to' do
+    expect { Window.top_level(:title => impossible, :raise => "Horror!") }.to raise_error "Horror!"
+  end
+end
+
+shared_examples_for 'child window finder' do
+
+  it 'finds ANY child window without specific args' do
+    use { @child = @win.child(opts) }
+    @child.should_not == nil
+    @win.child?(@child.handle).should == true
+  end
+
+  it 'returns nil immediately if specific child not found' do
+    start = Time.now
+    @win.child(opts.merge(:title => impossible)).should == nil
+    (Time.now - start).should be_within(0.05).of 0
+  end
+
+  it 'returns nil after timeout if specific child not found' do
+    start = Time.now
+    @win.child(opts.merge(:title => impossible, :timeout => 0.5)).should == nil
+    (Time.now - start).should be_within(0.05).of 0.5
+  end
+
+  it 'finds child window by class and returns it as a Window object (no timeout)' do
+    child = @win.child opts.merge(:class => class_name)
+    child.should_not == nil
+    @win.child?(child.handle).should == true
+  end
+
+  it 'finds child window by class and returns it as a Window object (with timeout)' do
+    child = @win.child opts.merge(:class => class_name, :timeout => 0.5)
+    child.should_not == nil
+    @win.child?(child.handle).should == true
+  end
+
+  it 'finds child with specific text and returns it as a Window object' do
+    with_dialog(:save) do |dialog|
+      child = dialog.child opts.merge(:title => cancel)
+      child.should_not == nil
+      dialog.child?(child.handle).should == true
+      child.get_dlg_ctrl_id.should == IDCANCEL
+
+      child = dialog.child opts.merge(:title => "&Save")
+      child.should_not == nil
+      dialog.child?(child.handle).should == true
+      child.get_dlg_ctrl_id.should == IDOK
+    end
+  end
+
+  it 'finds child control with a given ID and returns it as a Window object' do
+    with_dialog(:save) do |dialog|
+      child = dialog.child opts.merge(:id => IDCANCEL)
+      child.should_not == nil
+      dialog.child?(child.handle).should == true
+      child.text.should == "Cancel"
+    end
+  end
+end
+
 describe WinGui::Window do
   before(:each) { @win = launch_test_app.main_window }
   after(:each) { close_test_app }
@@ -51,18 +150,17 @@ describe WinGui::Window do
 
     it 'has class_name and text/title properties (derived from WinGui function calls)' do
       @win.class_name.should == WIN_CLASS
-      # text propery accessed by sending WM_GETTEXT directly to window (convenience method in WinGui)
+      # text property accessed by sending WM_GETTEXT directly to window (convenience method in WinGui)
       @win.text.should == WIN_TITLE
-      # window_text propery accessed via GetWindowText
+      # window_text property accessed via GetWindowText
       @win.window_text.should == WIN_TITLE
       # title property is just an alias for window_text
       @win.title.should == WIN_TITLE
     end
 
-    it 'has thread and process properties derived from get_window_thread_process_id' do
-      thread  = @win.thread
-      process = @win.process
-      [thread, process].should == get_window_thread_process_id(@win.handle)
+    it 'has thread and process(pid) properties derived from get_window_thread_process_id' do
+      [@win.thread, @win.process].should == get_window_thread_process_id(@win.handle)
+      @win.pid.should == @win.process
     end
 
     it 'has id property that only makes sense for controls' do
@@ -71,143 +169,79 @@ describe WinGui::Window do
   end
 
   describe '::top_level' do
-    it 'finds top-level window by title and wraps it in a Window object' do
-      window = Window.top_level(title: WIN_TITLE, timeout: 1)
-      window.handle.should == @win.handle
-    end
-
-    it 'finds top-level window by class and wraps it in a Window object' do
-      window = Window.top_level(class: WIN_CLASS, timeout: 1)
-      window.handle.should == @win.handle
-    end
-
     it 'finds ANY top-level window without args and wraps it in a Window object' do
       use { @window = Window.top_level() }
       @window.should be_a Window
     end
 
-    it 'returns nil immediately if top-level window with given title not found' do
-      start = Time.now
-      Window.top_level(title: IMPOSSIBLE).should == nil
-      (Time.now - start).should be_within(0.03).of 0
-    end
+    context 'with String arguments' do
+      let(:title) { WIN_TITLE }
+      let(:class_name) { WIN_CLASS }
+      let(:impossible) { IMPOSSIBLE }
 
-    it 'returns nil after timeout if top-level window with given title not found' do
-      start = Time.now
-      Window.top_level(title: IMPOSSIBLE, timeout: 0.3).should == nil
-      (Time.now - start).should be_within(0.03).of 0.3
+      it_should_behave_like 'normal window finder'
     end
 
-    it 'raises exception if asked to' do
-      expect { Window.top_level(title: IMPOSSIBLE, raise: "Horror!") }.to raise_error "Horror!"
-    end
+    context 'with Regexp arguments' do
+      let(:title) { Regexp.new WIN_TITLE[-6..-1] }
+      let(:class_name) { Regexp.new WIN_CLASS[-6..-1] }
+      let(:impossible) { Regexp.new IMPOSSIBLE }
 
-    it 'uses .find as alias for .top_level' do
-      use { @window = Window.find() }
-      @window.should be_a Window
+      it_should_behave_like 'normal window finder'
     end
-  end # describe .top_level
 
-  describe '#child' do
-    spec { use { @child = @win.child(title: "Title", class: "Class", id: 0) } }
+    context 'with mixed arguments' do
+      let(:title) { Regexp.new WIN_TITLE[-6..-1] }
+      let(:class_name) { WIN_CLASS }
+      let(:impossible) { IMPOSSIBLE }
 
-    it 'returns nil immediately if specific child not found' do
-      start = Time.now
-      @win.child(title: IMPOSSIBLE).should == nil
-      (Time.now - start).should be_within(0.03).of 0
-    end
-
-    it 'returns nil after timeout if specific child not found' do
-      start = Time.now
-      @win.child(title: IMPOSSIBLE, timeout: 0.5).should == nil
-      (Time.now - start).should be_within(0.03).of 0.5
+      it_should_behave_like 'normal window finder'
     end
 
-    it 'finds ANY child window without args' do
-      use { @child = @win.child() }
-      @child.should_not == nil
-      @win.child?(@child.handle).should == true
-    end
+  end # describe .top_level
 
-    it 'finds child window by class and returns it as a Window object (no timeout)' do
-      child = @win.child(class: TEXTAREA_CLASS)
-      child.should_not == nil
-      @win.child?(child.handle).should == true
-    end
+  describe '#child' do
+    spec { use { @child = @win.child(title: "Title", class: "Class", id: 0) } }
 
-    it 'finds child window by class and returns it as a Window object (with timeout)' do
-      child = @win.child(class: TEXTAREA_CLASS, timeout: 0.5)
-      child.should_not == nil
+    context 'direct children only' do
+      let(:opts) { {} }
 
-      @win.child?(child.handle).should == true
-      child = @win.child(class: STATUSBAR_CLASS, timeout: 0.5)
-      child.should_not == nil
-      @win.child?(child.handle).should == true
-    end
+      context 'with String arguments' do
+        let(:cancel) { 'Cancel' }
+        let(:class_name) { TEXTAREA_CLASS }
+        let(:impossible) { IMPOSSIBLE }
 
-    it 'finds child with specific text and returns it as a Window object' do
-      with_dialog(:save) do |dialog|
-        child = dialog.child(title: "Cancel")
-        child.should_not == nil
-        dialog.child?(child.handle).should == true
-        child.get_dlg_ctrl_id.should == IDCANCEL
-
-        child = dialog.child(title: "&Save")
-        child.should_not == nil
-        dialog.child?(child.handle).should == true
-        child.get_dlg_ctrl_id.should == IDOK
+        it_should_behave_like 'child window finder'
       end
-    end
 
-    it 'finds child control with a given ID and returns it as a Window object' do
-      with_dialog(:save) do |dialog|
-        child = dialog.child(id: IDCANCEL)
-        child.should_not == nil
-        dialog.child?(child.handle).should == true
-        child.text.should == "Cancel"
+      context 'with Regexp arguments' do
+        let(:cancel) { /Cancel/ }
+        let(:class_name) { Regexp.new TEXTAREA_CLASS[-6..-1] }
+        let(:impossible) { Regexp.new IMPOSSIBLE }
+
+        it_should_behave_like 'child window finder'
       end
     end
 
-    context 'indirect child' do
-      it 'returns nil if specified child not found' do
-        @win.child(title: IMPOSSIBLE, indirect: true).should == nil
-      end
+    context 'indirect children' do
+      let(:opts) { {:indirect => true} }
 
-      it 'finds ANY child window without other args' do
-        use { @child = @win.child(indirect: true) }
-        @child.should_not == nil
-        @win.child?(@child.handle).should == true
-      end
+      context 'with String arguments' do
+        let(:cancel) { 'Cancel' }
+        let(:class_name) { TEXTAREA_CLASS }
+        let(:impossible) { IMPOSSIBLE }
 
-      it 'finds child window by class' do
-        child = @win.child(class: TEXTAREA_CLASS, indirect: true)
-        child.should_not == nil
-        @win.child?(child.handle).should == true
+        it_should_behave_like 'child window finder'
       end
 
-      it 'finds child with specific text' do
-        with_dialog(:save) do |dialog|
-          child = dialog.child(title: "Cancel", indirect: true)
-          child.should_not == nil
-          dialog.child?(child.handle).should == true
-          child.id.should == IDCANCEL
-
-          child = dialog.child(title: "&Save", indirect: true)
-          child.should_not == nil
-          dialog.child?(child.handle).should == true
-          child.id.should == IDOK
-        end
-      end
+      context 'with Regexp arguments' do
+        let(:cancel) { /Cancel/ }
+        let(:class_name) { Regexp.new TEXTAREA_CLASS[-6..-1] }
+        let(:impossible) { Regexp.new IMPOSSIBLE }
 
-      it 'finds child control with a given ID ' do
-        with_dialog(:save) do |dialog|
-          child = dialog.child(id: IDCANCEL, indirect: true)
-          child.should_not == nil
-          dialog.child?(child.handle).should == true
-          child.text.should == "Cancel"
-        end
+        it_should_behave_like 'child window finder'
       end
-    end # context indirect
+    end
   end # describe child
 
   describe '#children' do

metadata

@@ -2,7 +2,7 @@
 name: win_gui
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.17
+  version: 0.2.18
 platform: ruby
 authors: 
 - arvicco
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-16 00:00:00 +03:00
+date: 2011-02-17 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -46,7 +46,7 @@ dependencies:
         version: 0.3.1
   type: :runtime
   version_requirements: *id003
-description: Abstractions/wrappers around GUI-related Win32 API functions
+description: Work with Windows GUI in an object-oriented way. Abstractions/wrappers around GUI-related Win32 API functions
 email: arvitallian@gmail.com
 executables: []
 
@@ -115,7 +115,7 @@ rubyforge_project:
 rubygems_version: 1.5.0
 signing_key: 
 specification_version: 3
-summary: Abstractions/wrappers around GUI-related Win32 API functions
+summary: Work with Windows GUI in an object-oriented way
 test_files: 
 - spec/extension_spec.rb
 - spec/spec_helper.rb