win_gui 0.2.0 → 0.2.1

data/HISTORY

@@ -5,3 +5,7 @@
 == 0.2.0 / 2010-05-15
 
 * Window class extracted into a separate lib
+
+== 0.2.1 / 2010-05-31
+
+* Complex convenience methods (dialog

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/win_gui/convenience.rb

@@ -0,0 +1,67 @@
+require 'win/gui'
+
+module WinGui
+  include Win::Gui
+#    extend Win::Gui
+
+  # Delay between key commands/events (in sec)
+  KEY_DELAY = 0.00001
+  # Delay when sleeping (in sec)
+  SLEEP_DELAY = 0.001
+  # Timeout waiting for Window to be closed (in sec)
+  CLOSE_TIMEOUT = 1
+  # Default timeout for dialog operations (in sec)
+  LOOKUP_TIMEOUT = 3
+  DIALOG_WINDOW_CLASS = '#32770'
+
+  # Module defines convenience methods on top of straightforward Win32 API functions.
+
+  # Finds top-level dialog window by title and yields found dialog window to attached block.
+  # We work with dialog window in a block, and then we wait for it to close before proceeding.
+  # That is, unless your block returns nil, in which case dialog is ignored and method immediately returns nil
+  # If no block is given, method just returns found dialog window or nil
+  def dialog(title, timeout=LOOKUP_TIMEOUT)
+    dialog = Window.top_level(class: DIALOG_WINDOW_CLASS, title: title, timeout: timeout)
+    #set_foreground_window dialog.handle if dialog # TODO: Should be converted to d_w.s_f_g call!
+    wait = block_given? ? yield(dialog) : false
+    dialog.wait_for_close if dialog && wait
+    dialog
+  end
+
+  # Emulates combinations of (any amount of) keys pressed one after another (Ctrl+Alt+P) and then released
+  # *keys should be a sequence of a virtual-key codes. The codes must be a value in the range 1 to 254.
+  # For a complete list, see msdn:Virtual Key Codes.
+  def keystroke(*keys)
+    return if keys.empty?
+    keybd_event keys.first, 0, KEYEVENTF_KEYDOWN, 0
+    sleep KEY_DELAY
+    keystroke *keys[1..-1]
+    sleep KEY_DELAY
+    keybd_event keys.first, 0, KEYEVENTF_KEYUP, 0
+  end
+
+  # types text message into window holding the focus
+  def type_in(message)
+    message.scan(/./m) do |char|
+      keystroke(*char.to_vkeys)
+    end
+  end
+
+
+#  DialogWndClass = '#32770'
+#  def dialog(title, seconds=5)
+#    close, dlg = begin
+#      sleep 0.25
+#      w = Gui.top_level(title, seconds, DialogWndClass)
+#      Gui.set_foreground_window w.handle
+#      sleep 0.25
+#
+#      [yield(w), w]
+#    rescue TimeoutError
+#    end
+#
+#    dlg.wait_for_close if dlg && close
+#    return dlg
+#  end
+
+end

data/lib/win_gui/window.rb

@@ -1,79 +1,108 @@
-require 'win/gui'
-
 module WinGui
-  # Delay between key commands (events)
-  WG_KEY_DELAY = 0.00001
-  # Wait delay quant
-  WG_SLEEP_DELAY = 0.001
-  # Timeout waiting for Window to be closed
-  WG_CLOSE_TIMEOUT = 1
 
+  # This class is a wrapper around window handle
   class Window
-    include Win::Gui
-    extend Win::Gui
-    
+    # Make convenience methods from both WinGui and Win::Gui available as both class and instance methods
+    # Looks a bit circular though...
+    include WinGui
+    extend WinGui
+
     def initialize(handle)
       @handle = handle
     end
 
     attr_reader :handle
-    
-    # find top level window by title, return wrapped Window object
-    def self.top_level(title, seconds=3)
-      @handle = timeout(seconds) do
-        sleep WG_SLEEP_DELAY while (h = find_window nil, title) == nil; h
+
+    # Finds top level window by title/class, returns wrapped Window object or nil.
+    # If timeout option given, waits for window to appear within timeout, returns nil if it didn't
+    # Options:
+    # :title:: window title
+    # :class:: window class
+    # :timeout:: timeout (seconds)
+    def self.top_level(opts={})
+      window_title = opts[:title]
+      window_class = opts[:class]
+      timeout = opts[:timeout] # || LOOKUP_TIMEOUT
+
+      if timeout
+        begin
+          timeout(timeout) do
+            sleep SLEEP_DELAY while (@handle = find_window window_class, window_title) == nil
+          end
+        rescue TimeoutError
+          nil
+        end
+      else
+        @handle = find_window window_class, window_title
       end
-      Window.new @handle
-    end  
-    
+      Window.new(@handle) if @handle
+    end
+
+#    def self.top_level(title, seconds=10, wnd_class = nil)
+#       @handle = timeout(seconds) do
+#         loop do
+#           h = find_window wnd_class, title
+#           break h if h > 0
+#           sleep 0.3
+#         end
+#       end
+#
+#       Gui.new @handle
+#     end
+#   end
+
     # find child window (control) by title, window class, or control ID:
     def child(id)
       result = case id
         when String
-        by_title = find_window_ex @handle, 0, nil, id.gsub('_' , '&' )
-        by_class = find_window_ex @handle, 0, id, nil
-        by_title ? by_title : by_class
+          by_title = find_window_ex @handle, 0, nil, id.gsub('_', '&' )
+          by_class = find_window_ex @handle, 0, id, nil
+          by_title ? by_title : by_class
         when Fixnum
-        get_dlg_item @handle, id
+          get_dlg_item @handle, id
         when nil
-        find_window_ex @handle, 0, nil, nil
-      else
-        nil
+          find_window_ex @handle, 0, nil, nil
+        else
+          nil
       end
       raise "Control '#{id}' not found" unless result
       Window.new result
     end
 
+    # returns array of Windows that are descendants (not only DIRECTchildren) of a given Window
     def children
       enum_child_windows(@handle).map{|child_handle| Window.new child_handle}
     end
 
     # emulate click of the control identified by id
     def click(id)
-      h = child(id).handle
-      rectangle = [0, 0, 0, 0].pack 'LLLL'
-      get_window_rect h, rectangle
-      left, top, right, bottom = rectangle.unpack 'LLLL'
+      left, top, right, bottom = get_window_rect child(id).handle
       center = [(left + right) / 2, (top + bottom) / 2]
       set_cursor_pos *center
       mouse_event MOUSEEVENTF_LEFTDOWN, 0, 0, 0, 0
       mouse_event MOUSEEVENTF_LEFTUP, 0, 0, 0, 0
     end
-    
+
     def close
       post_message @handle, WM_SYSCOMMAND, SC_CLOSE, nil
     end
-    
+
     def wait_for_close
-      timeout(WG_CLOSE_TIMEOUT) do
-        sleep WG_SLEEP_DELAY while window_visible?(@handle) 
+      timeout(CLOSE_TIMEOUT) do
+        sleep SLEEP_DELAY while window_visible?(@handle)
       end
     end
-    
+
+    # Window class name property - static (not changing)
+    def class_name
+      @class_name ||= get_class_name @handle
+    end
+
+    # Window text/title property - dynamic (changing)
     def text
-      buffer = "\x0" * 2048
-      length = send_message @handle, WM_GETTEXT, buffer.length, buffer
-      length == 0 ? '' : buffer[0..length - 1]
+      buffer = FFI::MemoryPointer.from_string("\x0" * 2048)
+      num_chars = send_message @handle, WM_GETTEXT, buffer.size, buffer # length?
+      num_chars == 0 ? '' : buffer.read_string
     end
   end
 end

data/spec/spec_helper.rb

@@ -22,7 +22,8 @@ end
 Spec::Runner.configure { |config| config.extend(SpecMacros) }
 
 module WinGuiTest
-  include Win::Gui
+  include Win::Gui  # This is a namespace from win gem.
+  include WinGui    # This is our own main namespace. TODO: looks confusing... better names?
 
   # Test related Constants:
   TIMEOUT = 0.001
@@ -30,9 +31,8 @@ module WinGuiTest
   SLEEP_DELAY = 0.01
   APP_PATH = File.join(File.dirname(__FILE__), "../misc/locknote/LockNote.exe" )
   APP_START = RUBY_PLATFORM =~ /cygwin/ ? "cmd /c start `cygpath -w #{APP_PATH}`" : "start #{APP_PATH}"
-#          end
-#
-#          'start "" "' + APP_PATH + '"'
+  #          'start "" "' + APP_PATH + '"'
+  DIALOG_TITLE = "Save As"
   WIN_TITLE = 'LockNote - Steganos LockNote'
   WIN_CLASS = 'ATL:00434098'
   WIN_RECT = [710, 400, 1210, 800]
@@ -49,7 +49,6 @@ module WinGuiTest
   end
 
   def any_handle
-    WinGui.def_api 'FindWindow', 'PP', 'L' unless respond_to? :find_window
     find_window(nil, nil)
   end
 
@@ -65,6 +64,12 @@ module WinGuiTest
     system APP_START
     sleep SLEEP_DELAY until (handle = find_window(nil, WIN_TITLE))
     @launched_test_app = Window.new handle
+
+    def @launched_test_app.textarea #define singleton method retrieving app's text area
+      Window.new find_window_ex(self.handle, 0, TEXTAREA_CLASS, nil)
+    end
+
+    @launched_test_app
   end
 
   def close_test_app(app = @launched_test_app)
@@ -79,10 +84,6 @@ module WinGuiTest
   def test_app
     app = launch_test_app
 
-    def app.textarea #define singleton method retrieving app's text area
-      Window.new find_window_ex(self.handle, 0, TEXTAREA_CLASS, nil)
-    end
-
     yield app
     close_test_app
   end

data/spec/win_gui/convenience_spec.rb

@@ -0,0 +1,68 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper" )
+
+module WinGuiTest
+
+  describe 'Convenience methods' do
+    before(:each){ @app = launch_test_app }
+    after(:each) { close_test_app }
+
+    describe '#dialog' do
+      before(:each){ keystroke(VK_ALT, 'F'.ord, 'A'.ord) }
+      after(:each) { keystroke(VK_ESCAPE) }
+
+      it 'returns top-level dialog window with given title if no block attached' do
+        dialog_window = dialog(DIALOG_TITLE, 0.1)
+        dialog_window.should_not == nil
+        dialog_window.should be_a Window
+        dialog_window.text.should == DIALOG_TITLE
+      end
+
+      it 'yields found dialog window to block if block is attached' do
+        dialog(DIALOG_TITLE, 0.1) do |dialog_window|
+          dialog_window.should_not == nil
+          dialog_window.should be_a Window
+          dialog_window.text.should == DIALOG_TITLE
+        end
+      end
+
+      it 'returns nil if there is no dialog with given title' do
+        dialog(IMPOSSIBLE, 0.1).should == nil
+      end
+
+      it 'yields nil to attached block if no dialog found' do
+        dialog(IMPOSSIBLE, 0.1) do |dialog_window|
+          dialog_window.should == nil
+        end
+      end
+
+      it 'considers timeout argument optional' do
+        dialog_window = dialog(DIALOG_TITLE)
+        dialog_window.text.should == DIALOG_TITLE
+      end
+    end # describe dialog
+
+    describe 'convenience input methods on top of Windows API' do
+      describe '#keystroke' do
+        spec{ use{ keystroke( vkey = 30, vkey = 30) }}
+
+        it 'emulates combinations of keys pressed (Ctrl+Alt+P+M, etc)' do
+          keystroke(VK_CONTROL, 'A'.ord)
+          keystroke(VK_SPACE)
+          @app.textarea.text.should.should == ' '
+          2.times {keystroke(VK_CONTROL, 'Z'.ord)} # rolling back changes to allow window closing without dialog!
+        end
+      end # describe '#keystroke'
+
+      describe '#type_in' do
+        it 'types text message into the window holding the focus' do
+          text = '12 34'
+          type_in(text)
+          @app.textarea.text.should =~ Regexp.new(text)
+          5.times {keystroke(VK_CONTROL, 'Z'.ord)} # rolling back changes to allow window closing without dialog!
+        end
+      end # describe '#type_in'
+
+    end # Input methods
+
+  end
+end

data/spec/win_gui/window_spec.rb

@@ -1,27 +1,29 @@
-require File.join(File.dirname(__FILE__), ".." , "spec_helper" )
+require File.join(File.dirname(__FILE__), "..", "spec_helper" )
 
 module WinGuiTest
-  include WinGui
 
   describe Window do
     before(:each) { @app = launch_test_app }
     after(:each){ close_test_app }
-    
+
     context 'initializing' do
       it 'can be wrapped around any existing window' do
         any_handle = find_window(nil, nil)
         use{ Window.new any_handle }
       end
     end
-    
+
     context 'manipulating' do
-      
+
       it 'has handle property equal to underlying window handle' do
-        any_handle = find_window(nil, nil)
         any = Window.new any_handle
         any.handle.should == any_handle
       end
-      
+
+      it 'has class_name property' do
+        @app.class_name.should == WIN_CLASS
+      end
+
       it 'has text property equal to underlying window text(title)' do
         @app.text.should == WIN_TITLE
       end
@@ -31,39 +33,57 @@ module WinGuiTest
         sleep SLEEP_DELAY # needed to ensure window had enough time to close down
         find_window(nil, WIN_TITLE).should == nil
       end
-      
-      it 'waits f0r window to disappear (NB: this happens before handle is released!)' do 
-        start = Time.now 
+
+      it 'waits for window to disappear (NB: this happens before handle is released!)' do
+        start = Time.now
         @app.close
         @app.wait_for_close
-         (Time.now - start).should be <= WG_CLOSE_TIMEOUT
+        (Time.now - start).should be <= CLOSE_TIMEOUT
         window_visible?(@app.handle).should be false
+        window?(@app.handle).should be false
       end
     end
-    
-    context '.top_level class method' do
-      it 'finds any top-level window (title = nil) and wraps it in a Window object' do
-        use { @win = Window.top_level(title = nil, timeout_sec = 3) }
-        Window.should === @win
-      end
-      
+
+    describe '.top_level' do
       it 'finds top-level window by title and wraps it in a Window object' do
-        win = Window.top_level( WIN_TITLE, 1)
+        win = Window.top_level( title: WIN_TITLE, timeout: 1)
         win.handle.should == @app.handle
       end
+
+      it 'finds top-level window by class and wraps it in a Window object' do
+        win = Window.top_level( class: WIN_CLASS, timeout: 1)
+        win.handle.should == @app.handle
+      end
+
+      it 'finds ANY top-level window without args and wraps it in a Window object' do
+        use { @win = Window.top_level() }
+        Window.should === @win
+      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_close 0, 0.02
+      end
+
+      it 'returns nil after timeout if top-level window with given title not found' do
+        start = Time.now
+        Window.top_level( title: IMPOSSIBLE, timeout: 1).should == nil
+        (Time.now - start).should be_close 1, 0.02
+      end
     end
-    
-    context '#child' do
-      spec { use { @control = @app.child(title_class_id = nil)  }} 
+
+    describe '#child' do
+      spec { use { @control = @app.child(title_class_id = nil)  }}
 
       it 'finds any child window(control) if given nil' do
         @app.child(nil).should_not == nil
       end
-      
+
       it 'finds child window(control) by class' do
         @app.child(TEXTAREA_CLASS).should_not == nil
       end
-      
+
       it 'finds child window(control) by name' do
         pending 'Need to find control with short name'
         @app.child(TEXTAREA_TEXT).should_not == nil
@@ -73,22 +93,18 @@ module WinGuiTest
         pending 'Need to find some control ID'
         @app.child(TEXTAREA_ID).should_not == nil
       end
-      
+
       it 'raises error if wrong control is given' do
         expect { @app.child('Impossible Control')}.to raise_error "Control 'Impossible Control' not found"
       end
-      it 'substitutes & for _ when searching by title ("&Yes" type controls)'
-      
+
+      it 'substitutes & for _ when searching by title ("&Yes" type controls)' # Why?
     end
-    
-    context '#children' do
-      spec { use { children = @app.children  }}
 
-      it 'returns an array' do
-        @app.children.should be_a_kind_of(Array)
-      end
+    describe '#children' do
+      spec { use { children = @app.children  }}
 
-      it 'returns an array of all child windows to the given window ' do
+      it 'returns an array of Windows that are descendants (not only DIRECTchildren) of a given Window' do
         children = @app.children
         children.should be_a_kind_of Array
         children.should_not be_empty
@@ -111,7 +127,7 @@ module WinGuiTest
 #        expect { @app.child('Impossible Control')}.to raise_error "Control 'Impossible Control' not found"
 #      end
 #      it 'substitutes & for _ when searching by title ("&Yes" type controls)'
-      
+
     end
 
     context '#click' do

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - arvicco
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-15 00:00:00 +04:00
+date: 2010-05-31 00:00:00 +04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -69,10 +69,12 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - lib/version.rb
+- lib/win_gui/convenience.rb
 - lib/win_gui/window.rb
 - lib/win_gui.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+- spec/win_gui/convenience_spec.rb
 - spec/win_gui/window_spec.rb
 - features/step_definitions/win_gui_steps.rb
 - features/support/env.rb
@@ -127,4 +129,5 @@ summary: Abstractions/wrappers around GUI-related Win32 API functions
 test_files: 
 - spec/spec.opts
 - spec/spec_helper.rb
+- spec/win_gui/convenience_spec.rb
 - spec/win_gui/window_spec.rb