win_gui 0.2.1 → 0.2.3

data/HISTORY

@@ -9,3 +9,11 @@
 == 0.2.1 / 2010-05-31
 
 * Complex convenience methods (dialog
+
+== 0.2.2 / 2010-06-03
+
+* WinGui functions can be used as instance methods on Window (with handle implicit first arg)
+
+== 0.2.3 / 2010-06-03
+
+* Minor cleanup/refactoring

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.3

data/lib/extension.rb

@@ -0,0 +1,31 @@
+class String
+  # converts one-char string into keyboard-scan 'Virtual key' code
+  # TODO: only letters and numbers convertible so far, need to extend further
+  def to_key
+    unless size == 1
+      raise "Can't convert but a single character: #{self}"
+    end
+    ascii = upcase.unpack('C')[0]
+#    puts "I'm here with #{self}->#{ascii}"
+    case self
+      when 'a'..'z', '0'..'9', ' '
+        [ascii]
+      when 'A'..'Z'
+        [WinGui.const_get(:VK_SHIFT), ascii]
+      when ','
+        [WinGui.const_get(:VK_OEM_COMMA)]
+      when '.'
+        [WinGui.const_get(:VK_OEM_PERIOD)]
+      when ':'
+        [:VK_SHIFT, :VK_OEM_1].map {|s| WinGui.const_get s}
+      when "\\"
+        [WinGui.const_get(:VK_OEM_102)]
+      else
+        raise "Can't convert unknown character: #{self}"
+    end
+  end
+
+  def to_print
+    force_encoding('cp1251').encode(Encoding.default_external, :undef => :replace)
+  end
+end

data/lib/win_gui/convenience.rb

@@ -2,7 +2,7 @@ require 'win/gui'
 
 module WinGui
   include Win::Gui
-#    extend Win::Gui
+  extend Win::Gui
 
   # Delay between key commands/events (in sec)
   KEY_DELAY = 0.00001
@@ -12,38 +12,42 @@ module WinGui
   CLOSE_TIMEOUT = 1
   # Default timeout for dialog operations (in sec)
   LOOKUP_TIMEOUT = 3
+
+  # Window class identifying standard modal dialog window
   DIALOG_WINDOW_CLASS = '#32770'
 
-  # Module defines convenience methods on top of straightforward Win32 API functions.
+  # 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!
+  # If no block is given, method just returns found dialog window (or nil if dialog is not found)
+  def dialog(opts={})
+    dialog = Window.top_level( {class: DIALOG_WINDOW_CLASS, timeout: LOOKUP_TIMEOUT}.merge opts )
+    dialog.set_foreground_window if dialog
     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.
+  # *keys should be a sequence of a virtual-key codes. These codes must be a value in the range 1 to 254.
   # For a complete list, see msdn:Virtual Key Codes.
+  # If alphanumerical char is given instead of virtual key code, only lowercase letters result (no VK_SHIFT!).
   def keystroke(*keys)
     return if keys.empty?
-    keybd_event keys.first, 0, KEYEVENTF_KEYDOWN, 0
+    key = String === keys.first ? keys.first.upcase.ord : keys.first.to_i
+    keybd_event key, 0, KEYEVENTF_KEYDOWN, 0
     sleep KEY_DELAY
     keystroke *keys[1..-1]
     sleep KEY_DELAY
-    keybd_event keys.first, 0, KEYEVENTF_KEYUP, 0
+    keybd_event key, 0, KEYEVENTF_KEYUP, 0
   end
 
-  # types text message into window holding the focus
+  # types text message into a window currently holding the focus
   def type_in(message)
     message.scan(/./m) do |char|
-      keystroke(*char.to_vkeys)
+      keystroke(*char.to_key)
     end
   end
 

data/lib/win_gui/window.rb

@@ -4,8 +4,8 @@ module WinGui
   class Window
     # 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
+#    include WinGui
+#    extend WinGui
 
     def initialize(handle)
       @handle = handle
@@ -22,46 +22,33 @@ module WinGui
     def self.top_level(opts={})
       window_title = opts[:title]
       window_class = opts[:class]
-      timeout = opts[:timeout] # || LOOKUP_TIMEOUT
+      timeout = opts[:timeout] # || LOOKUP_TIMEOUT ? # no timeout by default
 
       if timeout
         begin
           timeout(timeout) do
-            sleep SLEEP_DELAY while (@handle = find_window window_class, window_title) == nil
+            sleep SLEEP_DELAY while (@handle = WinGui.find_window window_class, window_title) == nil
           end
         rescue TimeoutError
           nil
         end
       else
-        @handle = find_window window_class, window_title
+        @handle = WinGui.find_window window_class, window_title
       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 = find_window_ex 0, nil, id.gsub('_', '&' )
+          by_class = find_window_ex 0, id, nil
           by_title ? by_title : by_class
         when Fixnum
-          get_dlg_item @handle, id
+          get_dlg_item id
         when nil
-          find_window_ex @handle, 0, nil, nil
+          find_window_ex 0, nil, nil
         else
           nil
       end
@@ -69,40 +56,51 @@ module WinGui
       Window.new result
     end
 
-    # returns array of Windows that are descendants (not only DIRECTchildren) of a given Window
+    # returns array of Windows that are descendants (not only DIRECT children) of a given Window
     def children
-      enum_child_windows(@handle).map{|child_handle| Window.new child_handle}
+      enum_child_windows.map{|child_handle| Window.new child_handle}
     end
 
     # emulate click of the control identified by id
     def click(id)
-      left, top, right, bottom = get_window_rect child(id).handle
+      left, top, right, bottom = child(id).get_window_rect
       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
+      WinGui.set_cursor_pos *center
+      WinGui.mouse_event WinGui::MOUSEEVENTF_LEFTDOWN, 0, 0, 0, 0
+      WinGui.mouse_event WinGui::MOUSEEVENTF_LEFTUP, 0, 0, 0, 0
     end
 
-    def wait_for_close
-      timeout(CLOSE_TIMEOUT) do
-        sleep SLEEP_DELAY while window_visible?(@handle)
+    def wait_for_close(timeout =CLOSE_TIMEOUT )
+      timeout(timeout) do
+        sleep SLEEP_DELAY while window_visible?
       end
     end
 
-    # Window class name property - static (not changing)
-    def class_name
-      @class_name ||= get_class_name @handle
+    # We alias convenience method shut_window (from Win::Gui::WIndow) with even more convenient
+    #   window.close
+    # Please keep in mind that Win32 API has another function CloseWindow that merely MINIMIZES window.
+    # If you want to invoke this function, you can do it like this:
+    #   window.close_window
+    def close
+      shut_window
     end
 
-    # Window text/title property - dynamic (changing)
-    def text
-      buffer = FFI::MemoryPointer.from_string("\x0" * 2048)
-      num_chars = send_message @handle, WM_GETTEXT, buffer.size, buffer # length?
-      num_chars == 0 ? '' : buffer.read_string
+    # Since Window instances wrap actual window handles, they should support WinGui functions
+    # manipulating these handles. Therefore, when unsupported instance method is invoked, we check if
+    # WinGui responds to such method, and if yes, call it with our window handle as a first argument.
+    # This gives us all handle-related WinGui functions as instance methods for Window instances, like so:
+    #   window.visible?
+    # This API is much more Ruby-like compared to:
+    #   visible?(window.handle)
+    # Of course, if we unvoke WinGui function that DOESN'T accept handle as a first arg this way, we are screwed.
+    # Call such functions only like this:
+    #   WinGui.function(*args)
+    def method_missing(name, *args, &block)
+      if WinGui.respond_to? name
+         WinGui.send(name, @handle, *args, &block)
+      else
+        super
+      end
     end
   end
 end

data/lib/win_gui.rb

@@ -1,4 +1,5 @@
 require 'version'
+require 'extension'
 
 module WinGui
 

data/spec/extension_spec.rb

@@ -0,0 +1,64 @@
+# encoding: UTF-8
+require File.join(File.dirname(__FILE__), "spec_helper" )
+
+module WinGuiTest
+
+  describe String do
+    describe '#to_key' do
+      it 'transforms number char into [equivalent key code]' do
+        ('0'..'9').each {|char| char.to_key.should == char.unpack('C')}
+      end
+
+      it 'transforms uppercase letters into [shift, equivalent key code]' do
+        ('A'..'Z').each {|char| char.to_key.should == [0x10, *char.unpack('C')]}
+      end
+
+      it 'transforms lowercase letters into [(upcase) key code]' do
+        ('a'..'z').each {|char| char.to_key.should == char.upcase.unpack('C')}
+      end
+
+      it 'transforms space into [equivalent key code]' do
+        ' '.to_key.should == " ".unpack('C')
+      end
+
+      it 'transforms .,:\\ into [equivalent key code]' do
+        ','.to_key.should == [VK_OEM_COMMA]
+        '.'.to_key.should == [VK_OEM_PERIOD]
+        ':'.to_key.should == [VK_SHIFT, VK_OEM_1]
+        "\\".to_key.should == [VK_OEM_102]
+      end
+
+      it 'raises error if char is not implemented punctuation' do
+        ('!'..'+').each {|char| lambda {char.to_key}.should raise_error ERROR_CONVERSION }
+        (';'..'@').each {|char| lambda {char.to_key}.should raise_error ERROR_CONVERSION }
+        (']'..'`').each {|char| lambda {char.to_key}.should raise_error ERROR_CONVERSION }
+        ('{'..'~').each {|char| lambda {char.to_key}.should raise_error ERROR_CONVERSION }
+        ['-', '/', '['].each {|char| lambda {char.to_key}.should raise_error ERROR_CONVERSION }
+      end
+
+      it 'raises error if char is non-printable or non-ascii' do
+        lambda {1.chr.to_key}.should raise_error ERROR_CONVERSION
+        lambda {230.chr.to_key}.should raise_error ERROR_CONVERSION
+      end
+
+      it 'raises error if string is multi-char' do
+        lambda {'hello'.to_key}.should raise_error ERROR_CONVERSION
+        lambda {'23'.to_key}.should raise_error ERROR_CONVERSION
+      end
+    end
+
+    describe '#to_print' do
+      it 'converts String from (implied) WinCyrillic (CP1251) to default output encoding' do
+        string = "Широкая электрификация южных губерний даст мощный толчок подъёму сельского хозяйства"
+        win_string = string.encode('cp1251')
+        print_string = win_string.encode(Encoding.default_external, :undef => :replace)
+        win_string_thought_utf8 = win_string.force_encoding('utf-8')
+        win_string_thought_dos = win_string.force_encoding('cp866')
+
+        win_string_thought_utf8.to_print.should == print_string
+        win_string_thought_dos.to_print.should == print_string
+      end
+
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -62,29 +62,28 @@ module WinGuiTest
 
   def launch_test_app
     system APP_START
-    sleep SLEEP_DELAY until (handle = find_window(nil, WIN_TITLE))
-    @launched_test_app = Window.new handle
+    @test_app = Window.top_level( title: WIN_TITLE, timeout: 10)
 
-    def @launched_test_app.textarea #define singleton method retrieving app's text area
-      Window.new find_window_ex(self.handle, 0, TEXTAREA_CLASS, nil)
+    def @test_app.textarea #define singleton method retrieving app's text area
+      Window.new WinGui::find_window_ex(self.handle, 0, TEXTAREA_CLASS, nil)
     end
 
-    @launched_test_app
+    @test_app
   end
 
-  def close_test_app(app = @launched_test_app)
-    while app && app.respond_to?(:handle) && find_window(nil, WIN_TITLE)
-      post_message(app.handle, WM_SYSCOMMAND, SC_CLOSE, nil)
-      sleep SLEEP_DELAY
+  def close_test_app
+    while @test_app && find_window(nil, WIN_TITLE)
+      @test_app.close
+      # Dealing with closing confirmation modal dialog
+      keystroke("N") if Window.top_level( title: "Steganos Locknote", timeout: SLEEP_DELAY*5)
     end
-    @launched_test_app = nil
+    @test_app = nil
   end
 
   # Creates test app object and yields it back to the block
   def test_app
-    app = launch_test_app
-
-    yield app
+    test_app = launch_test_app
+    yield test_app
     close_test_app
   end
 

data/spec/win_gui/convenience_spec.rb

@@ -7,18 +7,20 @@ module WinGuiTest
     after(:each) { close_test_app }
 
     describe '#dialog' do
-      before(:each){ keystroke(VK_ALT, 'F'.ord, 'A'.ord) }
-      after(:each) { keystroke(VK_ESCAPE) }
+      # Open "Save as" modal dialog
+      before(:each){ keystroke(VK_ALT, 'F', 'A') }
+      # Close modal dialog if it is opened
+      after(:each) { keystroke(VK_ESCAPE) if Window.top_level( title: "Save As", timeout: 0.1) }
 
       it 'returns top-level dialog window with given title if no block attached' do
-        dialog_window = dialog(DIALOG_TITLE, 0.1)
+        dialog_window = dialog(title: DIALOG_TITLE, timeout: 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(title: DIALOG_TITLE) do |dialog_window|
           dialog_window.should_not == nil
           dialog_window.should be_a Window
           dialog_window.text.should == DIALOG_TITLE
@@ -26,39 +28,38 @@ module WinGuiTest
       end
 
       it 'returns nil if there is no dialog with given title' do
-        dialog(IMPOSSIBLE, 0.1).should == nil
+        dialog(title: IMPOSSIBLE, timeout: 0.1).should == nil
       end
 
       it 'yields nil to attached block if no dialog found' do
-        dialog(IMPOSSIBLE, 0.1) do |dialog_window|
+        dialog(title: IMPOSSIBLE, timeout: 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
+      it 'considers all arguments optional' do
+        use { dialog_window = dialog() }
       end
     end # describe dialog
 
     describe 'convenience input methods on top of Windows API' do
       describe '#keystroke' do
-        spec{ use{ keystroke( vkey = 30, vkey = 30) }}
+        spec{ use{ keystroke( vkey = 30, char = 'Z') }}
 
         it 'emulates combinations of keys pressed (Ctrl+Alt+P+M, etc)' do
-          keystroke(VK_CONTROL, 'A'.ord)
+          keystroke(VK_CONTROL, 'A')
           keystroke(VK_SPACE)
           @app.textarea.text.should.should == ' '
-          2.times {keystroke(VK_CONTROL, 'Z'.ord)} # rolling back changes to allow window closing without dialog!
+          keystroke('1', '2', 'A', 'B'.ord)
+          @app.textarea.text.should.should == ' 12ab'
         end
       end # describe '#keystroke'
 
       describe '#type_in' do
         it 'types text message into the window holding the focus' do
-          text = '12 34'
+          text = '1234 abcdefg'
           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'
 

data/spec/win_gui/window_spec.rb

@@ -14,20 +14,11 @@ module WinGuiTest
     end
 
     context 'manipulating' do
-
       it 'has handle property equal to underlying window handle' do
         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
-
       it 'closes when asked nicely' do
         @app.close
         sleep SLEEP_DELAY # needed to ensure window had enough time to close down
@@ -44,6 +35,29 @@ module WinGuiTest
       end
     end
 
+    context 'handle-related WinGui functions as instance methods' do
+      it 'calls all WinGui functions as instance methods (with handle as implicit first argument)' do
+        @app.window?.should == true
+        @app.visible?.should == true
+        @app.foreground?.should == true
+        @app.maximized?.should == false
+        @app.maximized?.should == false
+        @app.child?(any_handle).should == false
+
+        @app.window_rect.should be_an Array
+        @app.window_thread_process_id.should be_an Array
+        @app.enum_child_windows.should be_an Array
+      end
+
+      it 'has class_name and text properties (derived from WinGui function calls)' do
+        @app.class_name.should == WIN_CLASS
+        # window_text propery accessed via GetWindowText
+        @app.window_text.should == WIN_TITLE
+        # text propery accessed by sending WM_GETTEXT directly to window (convenience method in WinGui)
+        @app.text.should == WIN_TITLE
+      end
+    end
+
     describe '.top_level' do
       it 'finds top-level window by title and wraps it in a Window object' do
         win = Window.top_level( title: WIN_TITLE, timeout: 1)
@@ -68,8 +82,8 @@ module WinGuiTest
 
       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
+        Window.top_level( title: IMPOSSIBLE, timeout: 0.5).should == nil
+        (Time.now - start).should be_close 0.5, 0.02
       end
     end
 
@@ -104,13 +118,13 @@ module WinGuiTest
     describe '#children' do
       spec { use { children = @app.children  }}
 
-      it 'returns an array of Windows that are descendants (not only DIRECTchildren) of a given Window' do
+      it 'returns an array of Windows that are descendants (not only DIRECT children) of a given Window' do
         children = @app.children
         children.should be_a_kind_of Array
         children.should_not be_empty
         children.should have(2).elements
         children.each{|child| child?(@app.handle, child.handle).should == true }
-        get_class_name(children.last.handle).should == TEXTAREA_CLASS
+        children.last.class_name.should == TEXTAREA_CLASS
       end
 
 #      it 'finds child window(control) by name' do

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 3
+  version: 0.2.3
 platform: ruby
 authors: 
 - arvicco
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-31 00:00:00 +04:00
+date: 2010-06-03 00:00:00 +04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -68,10 +68,12 @@ extra_rdoc_files:
 - HISTORY
 - README.rdoc
 files: 
+- lib/extension.rb
 - lib/version.rb
 - lib/win_gui/convenience.rb
 - lib/win_gui/window.rb
 - lib/win_gui.rb
+- spec/extension_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
 - spec/win_gui/convenience_spec.rb
@@ -127,6 +129,7 @@ signing_key:
 specification_version: 3
 summary: Abstractions/wrappers around GUI-related Win32 API functions
 test_files: 
+- spec/extension_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
 - spec/win_gui/convenience_spec.rb