win_gui 0.1.3 → 0.1.4

data/README.rdoc

@@ -1,6 +1,6 @@
 = win_gui
     by: Arvicco
-    url: http://github.com/arvicco/git_hub
+    url: http://github.com/arvicco/win_gui
 
 == DESCRIPTION:
 
@@ -12,30 +12,32 @@ In addition to straightforward API wrappers, it also defines more Ruby-like
 abstractions and convenience methods for manipulating windows and other GUI 
 elements (such as WinGui::Window class and its methods).
 
-It is still work in progress, only a small number of API functions wrapped so far...
+It is still work in progress, only a small number of user32 API functions wrapped so far...
 
 == SUMMARY
 
 So you want to write a simple program that makes some Win32 API function calls.
-You searched MSDN and you know what functions you'll need. Now you just want to
-put those calls into your Ruby code. You'd love it to be a natural extension of
-Ruby code, preferably not turning your code base into a ugly C++ like spaghetty
+You searched MSDN high and low and you now know exactly what functions you need.
+All you want is just putting those function calls into your Ruby code without too
+much pain. You'd love this to be more or less natural extension of your Ruby code,
+preferably not turning your code base into an ugly C++ like spaghetty
 of CamelCase calls, String/Array pack/unpack gymnastics, buffer allocations,
 extracting return values from [in/out] parameters and checking return codes for 0.
+
 You can definitely use excellent 'win32-api' gem by Daniel J. Berger and Park Heesob
 that allows you to define Win32 API objects for any function you can find on MSDN,
 execute calls on them and even define callback objects that some of those API functions expect.
 
-However, this gem will only take you so far. You'll still have to handle (somewhat)
+However, that gem will only take you so far. You'll still have to handle (somewhat)
 gory details of argument preparation, mimicking pointers with Strings and stuff.
 For example, consider the amount of code needed to complete a task as simple as
 getting unicode title text for the window that you already have handle for:
 
   api = Win32::API.new( 'GetWindowTextW', ['L', 'P', 'I'], 'L', 'user32' )
-  buffer = "\x00" * 1024
+  buffer = "\x00" * 1024  # I just hope it will be enough...
   num_chars = api.call( window_handle, buffer, buffer.size)
   title = if num_chars == 0
-    nil
+    nil                   
   else
      buffer.force_encoding('utf-16LE').encode('utf-8').rstrip
   end
@@ -45,7 +47,7 @@ Ew, ugly. What about getting information about process id for a known window?
   api = Win32::API.new( 'GetWindowThreadProcessId', ['L', 'P'], 'L' , 'user32' )
     process_packed = [1].pack('L')
     thread = api.call(window_handle, process_packed)
-    process = process.unpack('L').first
+    process = process_packed.unpack('L').first
 
 Wow, packing and unpacking arrays into String to get hold of a simple integer id.
 Just great. Now, wouldn't it be MUCH better if you can just say something like this:
@@ -57,9 +59,9 @@ What about API functions expecting callbacks? Well, something like this may be n
 
   enum_child_windows( parent_handle, message ){|child_handle, message| puts child_handle }
 
-If you think about it, callbacks are not much than more than code blocks, so let's not
-be afraid to treat them as such. It would be also good if test functions return true/false
-instead of zero/nonzero, find functions return nil if nothing was found etc...
+If you think about it, callbacks are not much more than code blocks, so let's not be afraid
+to treat them as such. It would be also good if test functions return true/false instead of
+zero/nonzero, find functions return nil if nothing was found etc...
 
 So this is an idea behind WinGui library - make Win32 API functions more fun to use
 and feel more natural inside Ruby code. Following the principle of least surprise, we
@@ -70,7 +72,12 @@ Well, we even keep a backup solution for those diehard Win32 API longtimers who
 allocate their buffer strings by hand and mess with obscure return codes. If you use original
 CamelCase method name instead of Rubyesque snake_case one, it will expect those standard
 parameters you know and love from MSDN, return your zeroes instead of nils and support no
-other enhancements. Enjoy!
+other enhancements.
+
+And if you do not see your favorite Windows API function amoung those already defined, it is
+quite easy to define new one with def_api class method that does a lot of heavy lifting for
+you and can be customized with options and code blocks to give you reusable API wrapper method
+with the exact behavior you need.
 
 == DOCUMENTATION:
 
@@ -83,7 +90,7 @@ arguments given to block, etc...)
 
 == FEATURES/PROBLEMS:
 
-This project is quite new, so it's may be not suitable for production-quality systems
+This project is quite new, so it may be not suitable for production-quality systems yet.
 Contributors always welcome!
 
 == INSTALL:

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/lib/win_gui/def_api.rb

@@ -33,37 +33,53 @@ module WinGui
     #   :zeronil:: Forces method to return nil if function result is zero
     #
     def def_api(function, params, returns, options={}, &define_block)
+      name, aliases = generate_names(function, options)
+      boolean = options[:boolean]
+      zeronil = options[:zeronil]
+      proto = params.respond_to?(:join) ? params.join : params # Convert params into prototype string
+      api = Win32::API.new(function, proto.upcase, returns.upcase, options[:dll] || DEFAULT_DLL)
+
+      define_method(function) {|*args| api.call(*args)} # define CamelCase method wrapper for api call
+
+      define_method(name) do |*args, &runtime_block|    # define snake_case method with enhanced api
+        return api if args == [:api]
+        return define_block[api, *args, &runtime_block] if define_block
+        WinGui.enforce_count(args, proto)
+        result = api.call(*args)
+        result = runtime_block[result] if runtime_block
+        return result != 0 if boolean         # Boolean function returns true/false instead of nonzero/zero
+        return nil if zeronil && result == 0  # Zeronil function returns nil instead of zero
+        result
+      end
+      aliases.each {|ali| alias_method ali, name }        # define aliases
+    end 
+
+    # Generates name and aliases for defined method based on function name,
+    # sets boolean flag for test functions (Is...)
+    #
+    def generate_names(function, options)
       aliases = ([options[:alias]] + [options[:aliases]]).flatten.compact
       name = options[:rename] || function.snake_case
       case name
         when /^is_/
           aliases << name.sub(/^is_/, '') + '?'
-          boolean = true
+          options[:boolean] = true
         when /^set_/
           aliases << name.sub(/^set_/, '')+ '='
         when /^get_/
           aliases << name.sub(/^get_/, '')
       end
-      boolean ||= options[:boolean]
-      zeronil = options[:zeronil]
-      proto = params.respond_to?(:join) ? params.join : params # Converts params into prototype string
-      api = Win32::API.new(function, proto.upcase, returns.upcase, options[:dll] || DEFAULT_DLL)
-
-      define_method(function) {|*args| api.call(*args)} # defines CamelCase method wrapper for api call
+      [name, aliases]
+    end
 
-      define_method(name) do |*args, &runtime_block|    # defines snake_case method with enhanced api
-        return api if args == [:api]
-        return define_block.call(api, *args, &runtime_block) if define_block
-        unless args.size == params.size
-          raise ArgumentError, "wrong number of parameters: expected #{params.size}, got #{args.size}"
-        end  
-        result = api.call(*args)
-        result = runtime_block[result] if runtime_block
-        return result != 0 if boolean       # Boolean function returns true/false instead of nonzero/zero
-        return nil if zeronil && result == 0
-        result
+    # Ensures that args count is equal to params count plus diff
+    #
+    def enforce_count(args, params, diff = 0)
+      num_args = args.size
+      num_params = params == 'V' ? 0 : params.size + diff
+      if num_args != num_params
+        raise ArgumentError, "wrong number of parameters: expected #{num_params}, got #{num_args}"
       end
-      aliases.each {|ali| alias_method ali, name } unless aliases == []
     end
 
     # Converts block into API::Callback object that can be used as API callback argument
@@ -80,15 +96,19 @@ module WinGui
       code * size
     end
 
+    # Returns array of given args if none of them is zero,
+    # if any arg is zero, returns array of nils
+    #
+    def nonzero_array(*args)
+      args.any?{|arg| arg == 0 } ? args.map{||nil} : args
+    end
+
     # Procedure that returns (possibly encoded) string as a result of api function call
     # or nil if zero characters was returned by api call
     #
     def return_string( encode = nil )
       lambda do |api, *args|
-      num_params = api.prototype.size-2
-      unless args.size == num_params
-        raise ArgumentError, "wrong number of parameters: expected #{num_params}, got #{args.size}"
-      end
+        WinGui.enforce_count( args, api.prototype, -2)
         args += [string = buffer, string.length]
         num_chars = api.call(*args)
         return nil if num_chars == 0
@@ -103,10 +123,7 @@ module WinGui
     #
     def return_enum
       lambda do |api, *args, &block|
-        num_params = api.prototype.size-1
-        unless args.size == num_params
-          raise ArgumentError, "wrong number of parameters: expected #{num_params}, got #{args.size}"
-        end
+        WinGui.enforce_count( args, api.prototype, -1)
         handles = []
         cb = if block
           callback('LP', 'I', &block)
@@ -131,10 +148,9 @@ module WinGui
       lambda do |api, id=0, cmd, &block|
         raise ArgumentError, 'No callback block' unless block
         callback = callback 'IIPPPPPP', 'L', &block
-        id = [id].pack('L')
 
-        status = api.call(id, callback, cmd, 0)
-        [*id.unpack('L'), status]
+        status = api.call(id = [id].pack('L'), callback, cmd, 0)
+        nonzero_array(*id.unpack('L'), status)
       end
     end
 

data/lib/win_gui/win_gui.rb

@@ -15,7 +15,6 @@ require 'window'
 module WinGui
   extend DefApi
 
-
   # Windows GUI API definitions:
 
   ##
@@ -78,7 +77,7 @@ module WinGui
   #     title matches the win_title parameter.
   #   win_name (P) - String that specifies the window name (title). If nil, all names match.
   # Return Value (L): found window handle or NIL if nothing found
-
+  #
   # :call-seq:
   #   win_handle = find_window( class_name, win_name )
   #
@@ -107,7 +106,7 @@ module WinGui
   #   win_class (P), win_title (P) - Strings that specify window class and name(title). If nil, anything matches.
   # Returns (L): found child window handle or NIL if nothing found
   #
-  #:call-seq:
+  # :call-seq:
   #   win_handle = find_window_ex( win_handle, after_child, class_name, win_name )
   #
   def_api 'FindWindowEx', 'LLPP', 'L', zeronil: true
@@ -221,7 +220,7 @@ module WinGui
   SW_SHOWMINIMIZED  = 2
   # Activates the window and displays it as a maximized window.
   SW_SHOWMAXIMIZED  = 3
-  # Maximizes the specified window.
+  # Activates the window and displays it as a maximized window.
   SW_MAXIMIZE       = 3
   # Displays a window in its most recent size and position. Similar to SW_SHOWNORMAL, but the window is not activated.
   SW_SHOWNOACTIVATE = 4
@@ -243,8 +242,15 @@ module WinGui
   # flag when minimizing windows from a different thread.
   SW_FORCEMINIMIZE  = 11
 
-  def hide_window(handle)
-    show_window(handle, SW_HIDE)
+  # Hides the window and activates another window
+  def hide_window(win_handle)
+    show_window(win_handle, SW_HIDE)
+  end
+
+  return_thread_process = lambda do |api, *args|
+    WinGui.enforce_count( args, api.prototype, -1)
+    thread = api.call(args.first, process = [1].pack('L'))
+    nonzero_array(thread, *process.unpack('L'))
   end
 
   ##
@@ -265,10 +271,13 @@ module WinGui
   #:call-seq:
   #   thread, process_id = get_window_tread_process_id( win_handle )
   #
-  def_api 'GetWindowThreadProcessId', 'LP', 'L' do |api, *args|
-    raise 'Invalid args count' unless args.size == api.prototype.size-1
-    thread = api.call(args.first, process = [1].pack('L'))
-    [thread, *process.unpack('L')]
+  def_api 'GetWindowThreadProcessId', 'LP', 'L', &return_thread_process
+
+  return_rect = lambda do |api, *args|
+    WinGui.enforce_count( args, api.prototype, -1)
+    rectangle = [0, 0, 0, 0].pack('L*')
+    res = api.call args.first, rectangle
+    res == 0 ? [nil, nil, nil, nil] : rectangle.unpack('L*')
   end
 
   ##
@@ -293,12 +302,7 @@ module WinGui
   #:call-seq:
   #   rect = get_window_rect( win_handle )
   #
-  def_api 'GetWindowRect', 'LP', 'I' do |api, *args|
-    raise 'Invalid args count' unless args.size == api.prototype.size-1
-    rectangle = [0, 0, 0, 0].pack 'L*'
-    api.call args.first, rectangle
-    rectangle.unpack 'L*'
-  end
+  def_api 'GetWindowRect', 'LP', 'I', &return_rect
 
   ##
   # The EnumWindows function enumerates all top-level windows on the screen by passing the handle to
@@ -356,9 +360,43 @@ module WinGui
   #
   #:call-seq:
   #   enum_windows( parent_handle, message ) {|win_handle, message| callback procedure }
+  #
   def_api 'EnumChildWindows', 'LKP', 'L', &return_enum
 
+  ##
+  # GetForegroundWindow function returns a handle to the foreground window (the window with which the user
+  # is currently working). The system assigns a slightly higher priority to the thread that creates the
+  # foreground window than it does to other threads.
+  #
+  # Syntax:  HWND GetForegroundWindow(VOID);
+  #
+  # Return Value: The return value is a handle to the foreground window. The foreground window can be NULL in
+  # certain circumstances, such as when a window is losing activation.
+  #
+  #:call-seq:
+  #   win_handle = (get_)foreground_window()
+  #
   def_api 'GetForegroundWindow', 'V', 'L'
+
+  def foreground?(win_handle)
+    win_handle == foreground_window
+  end
+
+  ##
+  # The GetActiveWindow function retrieves the window handle to the active window attached to
+  # the calling thread's message queue.
+  #
+  # Syntax:  HWND GetActiveWindow(VOID);
+  #
+  # Return Value: The return value is the handle to the active window attached to the calling
+  # thread's message queue. Otherwise, the return value is NULL.
+  #
+  #  Remarks: To get the handle to the foreground window, you can use GetForegroundWindow.
+  #  To get the window handle to the active window in the message queue for another thread, use GetGUIThreadInfo.
+  #
+  #:call-seq:
+  #   win_handle = (get_)active_window()
+  #
   def_api 'GetActiveWindow', 'V', 'L'
 
   def_api 'keybd_event', 'IILL', 'V'

data/spec/spec_helper.rb

@@ -38,6 +38,7 @@ module GuiTest
   TEST_MAX_RECT = [-4, -4, 1924, 1204]  # on my 1920x1200 display
   TEST_MIN_RECT = [-32000, -32000, -31840, -31976]
   TEST_TEXTAREA_CLASS = 'ATL:00434310'
+  TEST_STATUSBAR_CLASS = 'msctls_statusbar32' 
   TEST_IMPOSSIBLE = 'Impossible'
   TEST_ERROR_CONVERSION = /Can.t convert/
 
@@ -60,23 +61,29 @@ module GuiTest
   end
 
   def hide_method(*names) # hide original method(s) if it is defined
-    names.each do |name|
+    names.map(&:to_s).each do |name|
       WinGui.module_eval do
-        if method_defined? name.to_sym
-          alias_method "orig_#{name.to_s}".to_sym, name.to_sym
-          remove_method name.to_sym
+        aliases = generate_names(name, {}).flatten + [name]
+        aliases.map(&:to_s).each do |ali|
+          if method_defined? ali
+            alias_method "orig_#{ali}".to_sym, ali
+            remove_method ali
+          end
         end
       end
     end
   end
 
   def restore_method(*names) # restore original method if it was hidden
-    names.each do |name|
+    names.map(&:to_s).each do |name| 
       WinGui.module_eval do
-        temp = "orig_#{name.to_s}".to_sym
-        if method_defined? temp
-          alias_method name.to_sym, temp
-          remove_method temp
+        aliases = generate_names(name, {}).flatten + [name]
+        aliases.map(&:to_s).each do |ali|
+          temp = "orig_#{ali}".to_sym
+          if method_defined? temp
+            alias_method ali, temp
+            remove_method temp
+          end
         end
       end
     end

data/spec/win_gui/def_api_spec.rb

@@ -13,14 +13,14 @@ module GuiTest
   end
 
   def redefined_methods
-    [:find_window, :is_window, :window?, :enum_windows, :get_computer_name, :computer_name]
+    [:FindWindow, :IsWindow, :EnumWindows, :GetComputerName, :GetForegroundWindow]
   end
 
   def should_count_args(*methods, rights, wrongs)
     rights = [rights].flatten
     wrongs = [wrongs].flatten
     methods.each do |method|
-      (1..8).each do |n|
+      (0..8).each do |n|
         if n == rights.size
           expect {send method, *rights}.to_not raise_error
         else
@@ -302,6 +302,21 @@ module GuiTest
       end
     end
 
+    context 'defining API function without arguments - f(VOID)' do
+      it 'should enforce argument count to 0, NOT 1 (enhanced methods)' do
+        WinGui.def_api 'GetForegroundWindow', 'V', 'L', zeronil: true
+        should_count_args :get_foreground_window, :foreground_window, [], [nil, 0, 123]
+      end
+
+      it 'should NOT enforce argument count (raw method)' do
+        WinGui.def_api 'GetForegroundWindow', 'V', 'L', zeronil: true
+        expect {GetForegroundWindow()}.to_not raise_error
+        expect {GetForegroundWindow(nil)}.to_not raise_error
+        expect {GetForegroundWindow(1,2)}.to_not raise_error
+        expect {GetForegroundWindow(1,2,3)}.to_not raise_error
+      end
+    end
+
     context 'working with API function callbacks' do
       it '#callback method creates a valid callback object' do
         expect { @callback = WinGui.callback('LP', 'I') {|handle, message| true} }.to_not raise_error

data/spec/win_gui/win_gui_spec.rb

@@ -1,41 +1,64 @@
 require File.join(File.dirname(__FILE__), "..", "spec_helper" )
 
 module GuiTest
+  def test_show_window *cmds, tests
+    cmds.each do |cmd|
+      test_app do |app|
+        show_window(app.handle, cmd)
+        tests.each{|test, result| send(test.to_sym, app.handle).should == result}
+
+        hide_window(app.handle) # hiding window first
+        show_window(app.handle, cmd)
+        tests.each{|test, result| send(test.to_sym, app.handle).should == result}
+
+        show_window(app.handle, SW_MAXIMIZE) # now maximizing window
+        show_window(app.handle, cmd)
+        tests.each{|test, result| send(test.to_sym, app.handle).should == result}
+
+        show_window(app.handle, SW_MINIMIZE) # now minimizing window
+        show_window(app.handle, cmd)
+        tests.each{|test, result| send(test.to_sym, app.handle).should == result}
+      end
+    end
+  end
+
   describe WinGui, ' contains a set of pre-defined GUI functions' do
     describe '#window?' do
-      spec{ use{ window?(handle = 0) }}
+      spec{ use{ IsWindow(any_handle) }}
+      spec{ use{ is_window(any_handle) }}
+      spec{ use{ window?(any_handle) }}
 
       it 'returns true if window exists' do
-        test_app do |app|
-          window?(app.handle).should == true
-          window?(app.textarea.handle).should == true
-        end
+        window?(any_handle).should == true
+      end
+
+      it 'returns false for invalid window handle' do
+        window?(not_a_handle).should == false
       end
 
-      it 'returns false if window does not exist' do
+      it 'changes from true to false when existing window is closed' do
         test_app do |app|
           @app_handle = app.handle
           @ta_handle = app.textarea.handle
+          window?(@app_handle).should == true
+          window?(@ta_handle).should == true
         end
         window?(@app_handle).should == false
         window?(@ta_handle).should == false
       end
     end
 
-    describe '#window_visible?' do 
-      spec{ use{ window_visible?(handle = any_handle) }}
-      spec{ use{ visible?(handle = any_handle) }}
+    describe '#window_visible?' do
+      spec{ use{ IsWindowVisible(any_handle) }}
+      spec{ use{ is_window_visible(any_handle) }}
+      spec{ use{ window_visible?(any_handle) }}
+      spec{ use{ visible?(any_handle) }}
 
-      it 'returns true if window is visible' do
+      it 'returns true when window is visible, false when window is hidden' do
         test_app do |app|
           visible?(app.handle).should == true
           window_visible?(app.handle).should == true
           window_visible?(app.textarea.handle).should == true
-        end
-      end
-
-      it 'returns false if window is not visible' do
-        test_app do |app|
           hide_window(app.handle)
           visible?(app.handle).should == false
           window_visible?(app.handle).should == false
@@ -45,19 +68,15 @@ module GuiTest
     end
 
     describe '#maximized?' do
-      spec{ use{ zoomed?(handle = 0) }}
-      spec{ use{ maximized?(handle = 0) }}
-      # Tests whether the specified window is maximized. 
+      spec{ use{ IsZoomed(any_handle) }}
+      spec{ use{ is_zoomed(any_handle) }}
+      spec{ use{ zoomed?(any_handle) }}
+      spec{ use{ maximized?(any_handle) }}
 
-      it 'returns false if window is not maximized' do
+      it 'returns true if the window is maximized, false otherwise' do
         test_app do |app|
           zoomed?(app.handle).should == false
           maximized?(app.handle).should == false
-        end
-      end
-
-      it 'returns true if the window is maximized' do
-        test_app do |app|
           show_window(app.handle, SW_MAXIMIZE)
           maximized?(app.handle).should == true
           zoomed?(app.handle).should == true
@@ -66,19 +85,15 @@ module GuiTest
     end
 
     describe '#minimized?' do
-      spec{ use{ iconic?(handle = 0) }}
-      spec{ use{ minimized?(handle = 0) }}
-      # Tests whether the specified window is minimized. 
+      spec{ use{ IsIconic(any_handle) }}
+      spec{ use{ is_iconic(any_handle) }}
+      spec{ use{ iconic?(any_handle) }}
+      spec{ use{ minimized?(any_handle) }}
 
-      it 'returns false if window is not minimized' do
+      it 'returns true if the window is minimized, false otherwise' do
         test_app do |app|
           iconic?(app.handle).should == false
           minimized?(app.handle).should == false
-        end
-      end
-
-      it 'returns true if the window is minimized' do
-        test_app do |app|
           show_window(app.handle, SW_MINIMIZE)
           iconic?(app.handle).should == true
           minimized?(app.handle).should == true
@@ -87,74 +102,57 @@ module GuiTest
     end
 
     describe '#child?' do
+      spec{ use{ IsChild(parent_handle = any_handle, handle = any_handle) }}
+      spec{ use{ is_child(parent_handle = any_handle, handle = any_handle) }}
       spec{ use{ child?(parent_handle = any_handle, handle = any_handle) }}
-      # Tests whether a window is a child (or descendant) window of a specified parent window. A child window is the direct descendant 
-      # of a specified parent window if that parent window is in the chain of parent windows; the chain of parent windows leads from 
-      # the original overlapped or pop-up window to the child window.
 
-      it 'returns true if the window is a child' do
+      it 'returns true if the window is a child of given parent, false otherwise' do
         test_app do |app|
           child?(app.handle, app.textarea.handle).should == true
-        end
-      end
-      it 'returns false if window is not a child' do
-        test_app do |app|
           child?(app.handle, any_handle).should == false
         end
       end
     end
 
-    describe '#find_window' do
+    describe '#find_window(w)' do
+      spec{ use{ FindWindow(class_name = nil, win_name = nil) }}
       spec{ use{ find_window(class_name = nil, win_name = nil) }}
+      # Widebyte (unicode) version
+      spec{ use{ FindWindowW(class_name = nil, win_name = nil) }}
+      spec{ use{ find_window_w(class_name = nil, win_name = nil) }}
 
       it 'returns either Integer Window handle or nil' do
         find_window(nil, nil).should be_a_kind_of Integer
-        nil.class.should === find_window(TEST_IMPOSSIBLE, nil)
+        find_window(TEST_IMPOSSIBLE, nil).should == nil
       end
 
       it 'returns nil if Window is not found' do
         find_window(TEST_IMPOSSIBLE, nil).should == nil
         find_window(nil, TEST_IMPOSSIBLE).should == nil
         find_window(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE).should == nil
-      end
-
-      it 'finds at least one window if both args are nils' do
-        find_window(nil, nil).should_not == nil
-      end
-
-      it 'finds top-level window by window class' do
-        test_app {|app| find_window(TEST_WIN_CLASS, nil).should == app.handle }
-      end
-
-      it 'finds top-level window by title' do
-        test_app {|app| find_window(nil, TEST_WIN_TITLE).should == app.handle }
-      end
-    end
-
-    describe '#find_window_w' do
-      spec{ use{ find_window_w(class_name = nil, win_name = nil) }}
-
-      it 'returns zero if Window is not found' do
         find_window_w(TEST_IMPOSSIBLE, nil).should == nil
         find_window_w(nil, TEST_IMPOSSIBLE).should == nil
         find_window_w(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE).should == nil
       end
 
-      it 'finds at least one window if given two nils' do
+      it 'finds at least one window if both args are nils' do
+        find_window(nil, nil).should_not == nil
         find_window_w(nil, nil).should_not == nil
       end
 
-      it 'finds top-level window by window class' do
-        test_app {|app| find_window_w(TEST_WIN_CLASS.to_w, nil).should == app.handle }
-      end
-
-      it 'finds top-level window by title' do
-        test_app {|app| find_window_w(nil, TEST_WIN_TITLE.to_w).should == app.handle }
+      it 'finds top-level window by window class or title' do
+        test_app do |app|
+          find_window(TEST_WIN_CLASS, nil).should == app.handle
+          find_window(nil, TEST_WIN_TITLE).should == app.handle
+          find_window_w(TEST_WIN_CLASS.to_w, nil).should == app.handle
+          find_window_w(nil, TEST_WIN_TITLE.to_w).should == app.handle
+        end
       end
     end
 
     describe '#find_window_ex' do
-      spec{ use{ control_handle = find_window_ex(parent = any_handle, after_child = 0, win_class = nil, win_title = nil) }}
+      spec{ use{ FindWindowEx(parent = any_handle, after_child = 0, win_class = nil, win_title = nil) }}
+      spec{ use{ find_window_ex(parent = any_handle, after_child = 0, win_class = nil, win_title = nil) }}
 
       it 'returns nil if wrong control is given' do
         parent_handle = any_handle
@@ -182,67 +180,115 @@ module GuiTest
       end
     end
 
-    describe '#get_window_thread_process_id' do
-      spec{ use{ thread, process = get_window_thread_process_id(handle = any_handle) }}
-      # Improved with block to accept window handle as a single arg and return a pair of [thread, process]
+    describe '#get_foreground_window' do
+      # ! Different from GetActiveWindow !
+      spec{ use{ handle = GetForegroundWindow() }}
+      spec{ use{ handle = get_foreground_window }}
+      spec{ use{ handle = foreground_window }}
 
-      it 'returns a pair of nonzero Integer ids (window thread and process)' do
-        thread, process = get_window_thread_process_id(handle = any_handle)
-        thread.should be_a_kind_of Integer
-        thread.should be > 0
-        process.should be_a_kind_of Integer
-        process.should be > 0
+      it 'returns handle to window that is currently in foreground' do
+        test_app do |app|
+          @app_handle = app.handle
+          fg1 = foreground_window
+          @app_handle.should == fg1
+        end
+        fg2 = foreground_window
+        @app_handle.should_not == fg2
       end
-    end
-
-    describe '#get_window_text' do
-      spec{ use{ text = get_window_text(handle = 0)}}
-      # Improved with block to accept window handle as a single arg and return (rstripped) text string 
 
-      it 'returns nil if incorrect window handle given' do
-        get_window_text(0).should == nil
+      it 'defines #foreground? test function ' do
+        test_app do |app|
+          @app_handle = app.handle
+          foreground?(@app_handle).should == true
+        end
+        foreground?(@app_handle).should == false
       end
+    end
 
-      it 'returns correct window text' do
-        test_app {|app| get_window_text(app.handle).should == TEST_WIN_TITLE }
+    describe '#get_active_window' do
+      # ! Different from GetForegroundWindow !
+      spec{ use{ handle = GetActiveWindow() }}
+      spec{ use{ handle = get_active_window }}
+      spec{ use{ handle = active_window }}
+
+      it 'returns handle to the active window attached to the calling thread`s message queue' do
+        pending 'No idea how to test it'
+        test_app do |app|
+          @app_handle = app.handle
+          fg1 = active_window
+          @app_handle.should == fg1
+        end
+        fg2 = active_window
+        @app_handle.should_not == fg2
       end
     end
 
-    describe '#get_window_text_w' do
-      spec{ use{ class_name = get_window_text_w(handle = 0)}} # result encoded as utf-8
+    describe '#get_window_text(w)' do
+      spec{ use{ GetWindowText(any_handle, buffer = "\00"* 1024, buffer.size)}}
+      # Improved with block to accept window handle as a single arg and return (rstripped) text string
+      spec{ use{ text = get_window_text(handle = 0)}}
       # Unicode version of get_window_text (strings returned encoded as utf-8)
+      spec{ use{ GetWindowTextW(any_handle, buffer = "\00"* 1024, buffer.size)}}
+      spec{ use{ text = get_window_text_w(any_handle)}} # result encoded as utf-8
 
       it 'returns nil if incorrect window handle given' do
-        get_window_text(0).should == nil
+        get_window_text(not_a_handle).should == nil
+        get_window_text_w(not_a_handle).should == nil
       end
 
       it 'returns correct window text' do
-        test_app {|app| get_window_text_w(app.handle).should == TEST_WIN_TITLE }
+        test_app do |app|
+          get_window_text(app.handle).should == TEST_WIN_TITLE
+          get_window_text_w(app.handle).should == TEST_WIN_TITLE
+        end
       end
     end
 
-    describe '#get_class_name' do
-      spec{ use{ class_name = get_class_name(handle = 0)}}
-      # Improved with block to accept window handle as a single arg and return class name string 
+    describe '#get_class_name(w)' do
+      spec{ use{ GetClassName(any_handle, buffer = "\00"* 1024, buffer.size)}}
+      # Improved with block to accept window handle as a single arg and return class name string
+      spec{ use{ class_name = get_class_name(any_handle)}}
+      # Unicode version of get_class_name (strings returned encoded as utf-8)
+      spec{ use{ GetClassNameW(any_handle, buffer = "\00"* 1024, buffer.size)}}
+      spec{ use{ class_name = get_class_name_w(handle = 0)}} # result encoded as utf-8
 
       it 'returns correct window class name' do
-        test_app {|app| get_class_name(app.handle).should == TEST_WIN_CLASS }
+        test_app do |app|
+          get_class_name(app.handle).should == TEST_WIN_CLASS
+          get_class_name_w(app.handle).should == TEST_WIN_CLASS
+        end
       end
     end
 
-    describe '#get_class_name_w' do
-      spec{ use{ class_name = get_class_name_w(handle = 0)}} # result encoded as utf-8
-      # Unicode version of get_class_name (strings returned encoded as utf-8)
+    describe '#get_window_thread_process_id' do
+      spec{ use{ thread = GetWindowThreadProcessId(any_handle, process_buffer = [1].pack('L')) }}
+      spec{ use{ thread, process = get_window_thread_process_id(any_handle) }}
+      # Improved with block to accept window handle as a single arg and return a pair of [thread, process]
 
-      it 'returns correct window class name' do
-        test_app {|app| get_class_name_w(app.handle).should == TEST_WIN_CLASS }
+      it 'returns a pair of nonzero Integer ids (thread and process) for valid window' do
+        thread, process = get_window_thread_process_id(any_handle)
+        thread.should be_a_kind_of Integer
+        thread.should be > 0
+        process.should be_a_kind_of Integer
+        process.should be > 0
+      end
+
+      it 'returns a pair of nils (thread and process) for invalid window' do
+        thread, process = get_window_thread_process_id(not_a_handle)
+        thread.should == nil
+        process.should == nil
       end
     end
 
     describe '#get_window_rect' do
+      spec{ use{ success = GetWindowRect(any_handle, rectangle = [0, 0, 0, 0].pack('L*'))}}
       spec{ use{ left, top, right, bottom = get_window_rect(any_handle)}}
 
-      it 'returns windows rectangle' do
+      it 'returns array of nils for invalid window' do
+        get_window_rect(not_a_handle).should == [nil, nil, nil, nil]
+      end
+
+      it 'returns window`s border rectangle' do
         test_app do |app|
           get_window_rect(app.handle).should == TEST_WIN_RECT
         end
@@ -252,84 +298,66 @@ module GuiTest
     describe '#show_window ', 'LI', 'I' do
       spec{ use{ was_visible = show_window(handle = any_handle, cmd = SW_SHOWNA) }}
 
-      it 'was_visible = hide_window(handle = any_handle)  # alias method (not a separate API function)' do
+      it 'was_visible = hide_window(handle = any_handle)  # derived method (not a separate API function)' do
         test_app do |app|
-          use{ hide_window(app.handle) }
+          use{ @was_visible = hide_window(app.handle) }
+          @was_visible.should == true
+          visible?(app.handle).should == false
+          hide_window(app.handle).should == false
           visible?(app.handle).should == false
         end
       end
 
-      it 'returns true if the window was PREVIOUSLY visible' do
-        test_app {|app| show_window(app.handle, SW_HIDE).should == true }
-      end
-
-      it 'returns false if the window was PREVIOUSLY not visible' do
+      it 'returns true if the window was PREVIOUSLY visible, false otherwise' do
         test_app do |app|
-          show_window(app.handle, SW_HIDE)
+          show_window(app.handle, SW_HIDE).should == true
           show_window(app.handle, SW_HIDE).should == false
         end
       end
 
-      it 'SW_HIDE command hides window' do
+      it 'hides window with SW_HIDE command ' do
         test_app do |app|
           show_window(app.handle, SW_HIDE)
           visible?(app.handle).should == false
         end
       end
 
-      it 'SW_SHOW command shows hidden window' do
+      it 'shows hidden window with SW_SHOW command' do
         test_app do |app|
-          show_window(app.handle, SW_HIDE)
+          hide_window(app.handle)
           show_window(app.handle, SW_SHOW)
           visible?(app.handle).should == true
         end
       end
 
-      it 'SW_MAXIMIZE maximizes window' do
-        test_app do |app|
-          show_window(app.handle, SW_MAXIMIZE)
-          maximized?(app.handle).should == true
-        end
-        pending 'Need to make sure window is maximized but NOT activated '
+      it 'SW_MAXIMIZE, SW_SHOWMAXIMIZED maximize window and activate it' do
+        test_show_window SW_MAXIMIZE, SW_SHOWMAXIMIZED,
+                         :minimized? => false, :maximized? => true, :visible? => true, :foreground? => true
       end
 
       it 'SW_MINIMIZE minimizes window and activates the next top-level window in the Z order' do
-        test_app do |app|
-          show_window(app.handle, SW_MINIMIZE)
-          minimized?(app.handle).should == true
-        end
+        test_show_window SW_MINIMIZE,
+                         :minimized? => true, :maximized? => false, :visible? => true, :foreground? => false
       end
 
-      it 'SW_SHOWMAXIMIZED activates the window and displays it as a maximized window' do
-        pending 'Need to make sure window is maximized AND activated '
-        test_app do |app|
-          show_window(app.handle, SW_SHOWMAXIMIZED)
-          get_window_rect(app.handle)
-          #.should == TEST_MAX_RECT
-        end
-
+      it 'SW_SHOWMINNOACTIVE, SW_SHOWMINIMIZED displays the window as a minimized foreground window' do
+        test_show_window SW_SHOWMINNOACTIVE, SW_SHOWMINIMIZED,
+                         :minimized? => true, :maximized? => false, :visible? => true, :foreground? => true
       end
-      it 'SW_SHOWMINIMIZED activates the window and displays it as a minimized window' do
-        pending 'Need to make sure window is minimized AND activated '
-        test_app do |app|
-          show_window(app.handle, SW_SHOWMINIMIZED)
-          p get_window_rect(app.handle)
-          #.should == TEST_MAX_RECT
-        end
 
+      it 'SW_SHOWNORMAL, SW_RESTORE, SW_SHOWNOACTIVATE activate/display a window(if min/maximized it is restored' do
+        test_show_window SW_SHOWNORMAL, SW_RESTORE, SW_SHOWNOACTIVATE,
+                         :minimized? => false, :maximized? => false, :visible? => true, :foreground? => true
       end
-      it 'SW_SHOWMINNOACTIVE displays the window as a minimized window (similar to SW_SHOWMINIMIZED, but window is not activated)'
+
       it 'SW_SHOWNA displays the window in its current size and position (similar to SW_SHOW, but window is not activated)'
-      it 'SW_SHOWNOACTIVATE displays the window in its current size and position (similar to SW_SHOW, but window is not activated)'
-      it 'SW_SHOWNORMAL activates and displays a window. Restores minimized/maximized window to original size/position. Use it to show window for the first time'
-      it 'SW_RESTORE activates and displays the window. Restores minimized/maximized window to original size/position. Use it to restore minimized windows'
       it 'SW_SHOWDEFAULT sets the show state based on the SW_ value specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application'
       it 'SW_FORCEMINIMIZE minimizes a window, even if the thread that owns the window is not responding - only Win2000/XP'
     end
 
     describe '#keydb_event' do
       spec{ use{ keybd_event(vkey = 0, bscan = 0, flags = 0, extra_info = 0) }}
-      # vkey (I) - Specifies a virtual-key code. The code must be a value in the range 1 to 254. For a complete list, see msdn:Virtual Key Codes. 
+      # vkey (I) - Specifies a virtual-key code. The code must be a value in the range 1 to 254. For a complete list, see msdn:Virtual Key Codes.
       # bscan (I) - Specifies a hardware scan code for the key.
       # flags (L) - Specifies various aspects of function operation. This parameter can be one or more of the following values.
       #   KEYEVENTF_EXTENDEDKEY - If specified, the scan code was preceded by a prefix byte having the value 0xE0 (224).
@@ -337,10 +365,10 @@ module GuiTest
       # extra_info (L) - Specifies an additional value associated with the key stroke.
       # no return value
 
-      it 'synthesizes a numeric keystroke, emulating keyboard driver' do
+      it 'synthesizes a numeric keystrokes, emulating keyboard driver' do
         test_app do |app|
           text = '123 456'
-          text.upcase.each_byte do |b| # upcase needed since user32 keybd_event expects upper case chars 
+          text.upcase.each_byte do |b| # upcase needed since user32 keybd_event expects upper case chars
             keybd_event(b.ord, 0, KEYEVENTF_KEYDOWN, 0)
             sleep TEST_KEY_DELAY
             keybd_event(b.ord, 0, KEYEVENTF_KEYUP, 0)
@@ -356,8 +384,8 @@ module GuiTest
 
     describe '#post_message' do
       spec{ use{ success = post_message(handle = 0, msg = 0, w_param = 0, l_param = 0) }}
-      # handle (L) - Handle to the window whose window procedure will receive the message. 
-      #   If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or 
+      # handle (L) - Handle to the window whose window procedure will receive the message.
+      #   If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or
       #   invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.
       # msg (L) - Specifies the message to be posted.
       # w_param (L) - Specifies additional message-specific information.
@@ -371,7 +399,7 @@ module GuiTest
     describe '#send_message' do
       spec{ use{ success = send_message(handle = 0, msg = 0, w_param = 1024, l_param = "\x0"*1024) }}
       # handle (L) - Handle to the window whose window procedure is to receive the message. The following values have special meanings.
-      #   HWND_BROADCAST - The message is posted to all top-level windows in the system, including disabled or invisible unowned windows, 
+      #   HWND_BROADCAST - The message is posted to all top-level windows in the system, including disabled or invisible unowned windows,
       #     overlapped windows, and pop-up windows. The message is not posted to child windows.
       #   NULL - The function behaves like a call to PostThreadMessage with the dwThreadId parameter set to the identifier of the current thread.
       # msg (L) - Specifies the message to be posted.
@@ -385,13 +413,13 @@ module GuiTest
 
     describe '#get_dlg_item' do
       spec{ use{ control_handle = get_dlg_item(handle = 0, item_id = 1) }}
-      # handle (L) - Handle of the dialog box that contains the control. 
-      # item_id (I) - Specifies the identifier of the control to be retrieved. 
+      # handle (L) - Handle of the dialog box that contains the control.
+      # item_id (I) - Specifies the identifier of the control to be retrieved.
       # Returns (L) - handle of the specified control if success or nil for invalid dialog box handle or a nonexistent control.
       #   To get extended error information, call GetLastError.
-      #   You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the handle 
-      #   parameter specifies a parent window and the child window has a unique id (as specified by the hMenu parameter in the 
-      #   CreateWindow or CreateWindowEx function that created the child window), GetDlgItem returns a valid handle to the child window. 
+      #   You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the handle
+      #   parameter specifies a parent window and the child window has a unique id (as specified by the hMenu parameter in the
+      #   CreateWindow or CreateWindowEx function that created the child window), GetDlgItem returns a valid handle to the child window.
 
       it 'returns handle to correctly specified control'
     end
@@ -400,13 +428,15 @@ module GuiTest
       spec{ use{ enum_windows(message = 'Message') }}
 
       it 'return an array of top-level window handles if block is not given' do
-        enum = enum_windows(message = 'Message')
-        enum.should be_a_kind_of Array
-        enum.should_not be_empty
-        enum.should have_at_least(60).elements # typical number of top windows in WinXP system?
-        enum.compact.size.should == enum.size # should not contain nils
+        test_app do |app|
+          enum = enum_windows(message = 'Message')
+          enum.should be_a_kind_of Array
+          enum.should_not be_empty
+          enum.should have_at_least(60).elements # typical number of top windows in WinXP system?
+          enum.each{|handle| handle.should be_an Integer }
+          enum.any?{|handle| handle == app.handle}.should == true
+        end
       end
-
       it 'iterates through all the top-level windows, passing each found window handle and message to a given block'
 
     end
@@ -418,25 +448,46 @@ module GuiTest
         test_app do |app|
           enum = enum_child_windows(app.handle, message = 'Message')
           enum.should be_a_kind_of Array
-          enum.should_not be_empty
           enum.should have(2).elements
-          p get_class_name(enum.first), get_class_name(enum.last)
-          get_class_name(enum.last).should == TEST_TEXTAREA_CLASS
+          class_name(enum.first).should == TEST_STATUSBAR_CLASS
+          class_name(enum.last).should == TEST_TEXTAREA_CLASS
         end
       end
 
-      it 'loops through all children of given window, passing each found window handle and a message to a given block'
-    end
+      it 'loops through all children of given window, passing each found window handle and a message to a given block' do
+        test_app do |app|
+          enum = []
+          enum_child_windows(app.handle, 'Message') do |handle, message|
+            enum << handle
+            message.should == 'Message'
+          end
+          enum.should have(2).elements
+          class_name(enum.first).should == TEST_STATUSBAR_CLASS
+          class_name(enum.last).should == TEST_TEXTAREA_CLASS
+        end
+      end
 
-    it 'GetForegroundWindow ', 'V', 'L'
-    it 'GetActiveWindow ', 'V', 'L'
+      it 'breaks loop if given block returns false' do
+        pending
+        test_app do |app|
+          enum = []
+          enum_child_windows(app.handle, 'Message') do |handle, message|
+            enum << handle
+            1
+          end
+          enum.should have(1).element
+          class_name(enum.first).should == TEST_STATUSBAR_CLASS
+#          class_name(enum.last).should == TEST_TEXTAREA_CLASS
+        end
+      end
+    end
   end
 
   describe WinGui, ' convenience wrapper methods' do
     describe '#keystroke' do
       spec{ use{ keystroke( vkey = 30, vkey = 30) }}
       # this service method emulates combinations of (any amount of) keys pressed one after another (Ctrl+Alt+P) and then released
-      # vkey (int) - Specifies a virtual-key code. The code must be a value in the range 1 to 254. For a complete list, see msdn:Virtual Key Codes. 
+      # vkey (int) - Specifies a virtual-key code. The code must be a value in the range 1 to 254. For a complete list, see msdn:Virtual Key Codes.
 
       it 'emulates combinations of keys pressed (Ctrl+Alt+P+M, etc)' do
         test_app do |app|

data/win_gui.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{win_gui}
-  s.version = "0.1.3"
+  s.version = "0.1.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["arvicco"]
-  s.date = %q{2010-01-29}
+  s.date = %q{2010-02-04}
   s.description = %q{Rubyesque interfaces and wrappers for Win32 API GUI functions}
   s.email = %q{arvitallian@gmail.com}
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: win_gui
 version: !ruby/object:Gem::Version 
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors: 
 - arvicco
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-29 00:00:00 +03:00
+date: 2010-02-04 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency