win_gui 0.2.5 → 0.2.9

data/HISTORY

@@ -25,3 +25,19 @@
 == 0.2.5 / 2010-06-04
 
 * Code brought to about Book-level quality
+
+== 0.2.6 / 2010-06-04
+
+* Docs improved
+
+== 0.2.7 / 2010-06-04
+
+* more punctuation added to String#to_key
+
+== 0.2.8 / 2010-06-04
+
+* Window#click api improved with position and mouse_button type
+
+== 0.2.9 / 2010-06-04
+
+* Window: Full feature parity with Book code

data/VERSION

@@ -1 +1 @@
-0.2.5
+0.2.9

data/lib/extension.rb

@@ -16,10 +16,14 @@ class String
         [WinGui.const_get(:VK_OEM_COMMA)]
       when '.'
         [WinGui.const_get(:VK_OEM_PERIOD)]
+      when ';'
+        [WinGui.const_get(:VK_OEM_1)]
       when ':'
         [:VK_SHIFT, :VK_OEM_1].map {|s| WinGui.const_get s}
       when "\\"
         [WinGui.const_get(:VK_OEM_102)]
+      when "\n"
+        [WinGui.const_get(:VK_RETURN)]
       else
         raise "Can't convert unknown character: #{self}"
     end

data/lib/win_gui/convenience.rb

@@ -1,5 +1,10 @@
 require 'win/gui'
 
+# Module contains Win32 API gui-related functions as both module and instance methods.
+# See documentation of Win::Gui module of *win* gem for a full scope of available functions.
+# In addition, module defines several higher-level convenience methods that can be useful
+# when dealing with GUI-related tasks under windows (such as testing automation).
+#
 module WinGui
   include Win::Gui
   extend Win::Gui
@@ -13,16 +18,22 @@ module WinGui
   # Default timeout for dialog operations (in sec)
   LOOKUP_TIMEOUT = 3
 
-  # Window class identifying standard modal dialog window
+  # Windows class identifying standard modal dialog window
   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 if dialog is not found)
-  def dialog(opts={})
+  # 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 if dialog is not found).
+  # Options:
+  # :title:: dialog title
+  # :class:: dialog class - default DIALOG_WINDOW_CLASS
+  # :timeout:: timeout (seconds) - default LOOKUP_TIMEOUT (3)
+  # :raise:: raise this exception instead of returning nil if nothing found
+  #
+  def dialog(opts={})  # :yields: dialog_window
     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
@@ -30,10 +41,11 @@ module WinGui
     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. These codes must be a value in the range 1 to 254.
+  # 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 (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?
     key = String === keys.first ? keys.first.upcase.ord : keys.first.to_i
@@ -44,28 +56,11 @@ module WinGui
     keybd_event key, 0, KEYEVENTF_KEYUP, 0
   end
 
-  # types text message into a window currently 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_key)
     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

@@ -11,12 +11,11 @@ module WinGui
 
     attr_reader :handle
 
-    # Looks up window handle using code specified in attached block (either with or without :timeout)
-    # Returns either Window instance (for a found handle) or nil if nothing found
+    # Looks up window handle using code specified in attached block (either with or without :timeout).
+    # Returns either Window instance (for a found handle) or nil if nothing found.
     # Private method to dry up other window lookup methods
-    # :yields:
     #
-    def self.lookup_window(opts)
+    def self.lookup_window(opts) # :yields: index, position
       # Need this to avoid handle considered local in begin..end block
       handle = yield
       if opts[:timeout]
@@ -32,60 +31,97 @@ module WinGui
       Window.new(handle) if handle
     end
 
-    # Find 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
+    # 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
     # :timeout:: timeout (seconds)
+    # :raise:: raise this exception instead of returning nil if nothing found
+    #
     def self.top_level(opts={})
       lookup_window(opts) { WinGui.find_window opts[:class], opts[:title] }
     end
 
-    # Find DIRECT child window (control) by either control ID or window class/title.
+    # Finds DIRECT child window (control) by either control ID or window class/title.
+    # Options:
+    # :id:: integer control id (such as IDOK, IDCANCEL, etc)
+    # :title:: window title
+    # :class:: window class
+    # :timeout:: timeout (seconds)
+    # :raise:: raise this exception instead of returning nil if nothing found
+    #
     def child(opts={})
       self.class.lookup_window(opts) do
         opts[:id] ? get_dlg_item(opts[:id]) : find_window_ex(0, opts[:class], opts[:title])
       end
     end
 
-    # Return array of Windows that are descendants (not only DIRECT children) of a given Window
+    # Returns array of Windows that are descendants (not only DIRECT children) of a given Window
+    #
     def children
       enum_child_windows.map{|child_handle| Window.new child_handle}
     end
 
-    # Emulate click of the control identified by opts (:id, :title, :class)
-    # Return true if click was presumably successful, false if it failed (control was not found)
+    # Emulates click of the control identified by opts (:id, :title, :class).
+    # Beware of keyboard shortcuts in button titles! So, use "&Yes" instead of just "Yes".
+    # Returns screen coordinates of click point if successful, nil if control was not found
+    # :id:: integer control id (such as IDOK, IDCANCEL, etc)
+    # :title:: window title
+    # :class:: window class
+    # :raise:: raise this exception instead of returning nil if nothing found
+    # :position/point/where:: location where the click is to be applied - default :center
+    # :mouse_button/button/which:: mouse button which to click - default :right
+    #
     def click(opts={})
       control = child(opts)
       if control
         left, top, right, bottom = control.get_window_rect
-        center = [(left + right) / 2, (top + bottom) / 2]
-        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
-        true
+
+        where = opts[:point] || opts[:where] || opts[:position]
+        point = case where
+          when Array
+            where                                                  # Explicit screen coords
+          when :random
+            [left + rand(right - left), top + rand(bottom - top)]  # Random point within control window
+          else
+            [(left + right) / 2, (top + bottom) / 2]               # Center of a control window
+        end
+
+        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]
+
+        WinGui.mouse_event down, 0, 0, 0, 0
+        WinGui.mouse_event up, 0, 0, 0, 0
+        point
       else
-        false
+        nil
       end
     end
 
+    # Waits for this window to close with timeout (default CLOSE_TIMEOUT).
+    #
     def wait_for_close(timeout=CLOSE_TIMEOUT )
       timeout(timeout) do
         sleep SLEEP_DELAY while window_visible?
       end
     end
 
-    # We alias convenience method shut_window (from Win::Gui::WIndow) with even more convenient
+    # 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
 
-    # Since Window instances wrap actual window handles, they should support WinGui functions
+    # Since Window instances wrap actual window handles, they should directly support Win32 API 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:
@@ -95,6 +131,11 @@ module WinGui
     # 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)
+    # TODO: Such setup is problematic if WinGui is included into Window ancestor chain.
+    # TODO: in this case, all WinGui functions become available as instance methods, and method_missing never fires.
+    # TODO: it may be a better solution to explicitly define all needed instance methods.
+    # TODO: instead of showing off cool meta-programming skillz.
+    #
     def method_missing(name, *args, &block)
       if WinGui.respond_to? name
 #        puts "Window #{@handle} calling: #{name} #{@handle} #{args} &#{block}"

data/spec/extension_spec.rb

@@ -21,16 +21,20 @@ module WinGuiTest
         ' '.to_key.should == " ".unpack('C')
       end
 
-      it 'transforms .,:\\ into [equivalent key code]' do
+      it 'transforms \n into [VK_RETURN]' do
+        "\n".to_key.should == [VK_RETURN]
+      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_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 }

data/spec/win_gui/window_spec.rb

@@ -169,27 +169,47 @@ module WinGuiTest
     end # describe #children
 
     describe '#click' do
-      it 'emulates clicking of the control identified by id, returns true' do
+      it 'emulates left click of the control identified by id, returns click coords' do
         with_dialog(:save) do |dialog|
-          dialog.click(id: IDCANCEL).should == true
-          sleep 0.5
+          point = dialog.click(id: IDCANCEL)
+          point.should be_an Array
+          sleep 0.3
           dialog.window?.should == false
         end
       end
 
-      it 'emulates clicking of the control identified by title, returns true' do
+      it 'emulates left click of the control identified by title, returns click coords' do
         with_dialog(:save) do |dialog|
-          dialog.click(title: "Cancel").should == true
-          sleep 0.5
+          point = dialog.click(title: "Cancel")
+          point.should be_an Array
+          sleep 0.3
           dialog.window?.should == false
         end
       end
 
-      it 'returns false if the specified control was not found' do
+      it 'emulates right click of the control identified by id, returns click coords' do
         with_dialog(:save) do |dialog|
-          dialog.click(title: "Shpancel").should == false
-          dialog.click(id: 66).should == false
-          sleep 0.5
+          point = dialog.click(id: IDCANCEL, mouse_button: :right)
+          point.should be_an Array
+          sleep 0.3
+          dialog.window?.should == true
+        end
+      end
+
+      it 'emulates right click of the control identified by title, returns click coords' do
+        with_dialog(:save) do |dialog|
+          point = dialog.click(title: "Cancel", mouse_button: :right)
+          point.should be_an Array
+          sleep 0.3
+          dialog.window?.should == true
+        end
+      end
+
+      it 'returns nil if the specified control was not found' do
+        with_dialog(:save) do |dialog|
+          dialog.click(title: "Shpancel").should == nil
+          dialog.click(id: 66).should == nil
+          sleep 0.3
           dialog.window?.should == true
         end
       end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 5
-  version: 0.2.5
+  - 9
+  version: 0.2.9
 platform: ruby
 authors: 
 - arvicco