win 0.3.3 → 0.3.5

data/HISTORY

@@ -6,3 +6,11 @@
 == 0.3.3 / 2010-04-17
 
 * Moved from Jeweler to own Rake tasks
+
+== 0.3.4 / 2010-05-12
+
+* Cleanup
+
+== 0.3.5 / 2010-05-28
+
+* GetParent

data/VERSION

@@ -1 +1 @@
-0.3.3
+0.3.5

data/lib/win/gui/window.rb

@@ -43,6 +43,20 @@ module Win
       # flag when minimizing windows from a different thread.
       SW_FORCEMINIMIZE  = 11
 
+      # GetWindow constants:
+      GW_HWNDFIRST = 0
+      GW_HWNDLAST = 1
+      GW_HWNDNEXT = 2
+      GW_HWNDPREV = 3
+      GW_OWNER = 4
+      GW_CHILD = 5
+      GW_ENABLEDPOPUP = 6
+
+      # GetAncestor constants:
+      GA_PARENT = 1
+      GA_ROOT = 2
+      GA_ROOTOWNER = 3
+
       class << self
         # Def_block that calls API function expecting EnumWindowsProc callback (EnumWindows, EnumChildWindows, ...).
         # Default callback pushes all passed handles into Array that is returned if Enum function call was successful.
@@ -227,7 +241,7 @@ module Win
 
       ##
       #  The FindWindowEx function retrieves a handle to a window whose class name and window name match the specified
-      #  strings. The function searches child windows, beginning with the one following the specified child window.
+      #  strings. The function searches only child windows, beginning with the one following the specified child window.
       #  This function does not perform a case-sensitive search.
       #
       #  [*Syntax*] HWND FindWindowEx( HWND hwndParent, HWND hwndChildAfter, LPCTSTR lpszClass, LPCTSTR lpszWindow );
@@ -257,7 +271,11 @@ module Win
       #              call GetLastError.
       #  ---
       #  *Remarks*:
-      #  - If the lpszWindow parameter is not NULL, FindWindowEx calls the GetWindowText function to retrieve the window name for comparison. For a description of a potential problem that can arise, see the Remarks section of GetWindowText.
+      #  - Only DIRECT children of given parent window being searched, not ALL its the descendants. This behavior is
+      #    different from EnumChildWindows which enumerates also non-direct descendants.
+      #  - If the lpszWindow parameter is not nil, FindWindowEx calls the GetWindowText function to retrieve the window
+      #    name for comparison. For a description of a potential problem that can arise, see the Remarks section of
+      #    GetWindowText.
       #  - An application can call this function in the following way.
       #         find_window_ex( nil, nil, MAKEINTATOM(0x8000), nil )
       #    0x8000 is the atom for a menu class. When an application calls this function, the function checks whether
@@ -470,11 +488,8 @@ module Win
       function :GetWindowRect, [:HWND, :pointer], :int,
                &->(api, handle) {
                rect = FFI::MemoryPointer.new(:long, 4)
-               #rect.write_array_of_long([0, 0, 0, 0])
                res = api.call handle, rect
                res == 0 ? [nil, nil, nil, nil] :  rect.read_array_of_long(4) }
-      # weird lambda literal instead of normal block is needed because current version of RDoc
-      # goes crazy if block is attached to meta-definition
 
       ##
       # EnumWindowsProc is an application-defined callback function that receives top-level window handles
@@ -499,8 +514,8 @@ module Win
 
       ##
       # The EnumWindows function enumerates all top-level windows on the screen by passing the handle to
-      #   each window, in turn, to an application-defined callback function. EnumWindows continues until
-      #   the last top-level window is enumerated or the callback function returns FALSE.
+      # each window, in turn, to an application-defined callback function. EnumWindows continues until
+      # the last top-level window is enumerated or the callback function returns FALSE.
       #
       # [*Syntax*] BOOL EnumWindows( WNDENUMPROC lpEnumFunc, LPARAM lParam );
       #
@@ -636,7 +651,112 @@ module Win
       #
       function :GetActiveWindow, [], :HWND, zeronil: true
 
+      ##
+      # The GetWindow function retrieves a handle to a window that has the specified relationship (Z-Order or
+      # owner) to the specified window.
+      #
+      # [*Syntax*] HWND GetWindow( HWND hWnd, UINT uCmd );
+      #
+      # hWnd:: [in] Handle to a window. The window handle retrieved is relative to this window, based on the
+      #        value of the uCmd parameter.
+      # uCmd:: [in] Specifies the relationship between the specified window and the window whose handle is to
+      #        be retrieved. This parameter can be one of the following values.
+      #        GW_CHILD - The retrieved handle identifies the child window at the top of the Z order, if the specified
+      #                   window is a parent window; otherwise, the retrieved handle is NULL. The function examines
+      #                   only child windows of the specified window. It does not examine descendant windows.
+      #        GW_ENABLEDPOPUP - Windows 2000/XP: The retrieved handle identifies the enabled popup window owned by
+      #                          the specified window (the search uses the first such window found using GW_HWNDNEXT);
+      #                          otherwise, if there are no enabled popup windows, the retrieved handle is that of the
+      #                          specified window.
+      #        GW_HWNDFIRST - The retrieved handle identifies the window of the same type that is highest in Z order.
+      #                       If the specified window is a topmost window, the handle identifies the topmost window
+      #                       that is highest in the Z order. If the specified window is a top-level window, the handle
+      #                       identifies the top-level window that is highest in the Z order. If the specified window
+      #                       is a child window, the handle identifies the sibling window that is highest in Z order.
+      #        GW_HWNDLAST -  The retrieved handle identifies the window of the same type that is lowest in the Z order.
+      #                       If the specified window is a topmost window, the handle identifies the topmost window that
+      #                       is lowest in the Z order. If the specified window is a top-level window, the handle
+      #                       identifies the top-level window that is lowest in the Z order. If the specified window is
+      #                       a child window, the handle identifies the sibling window that is lowest in the Z order.
+      #        GW_HWNDNEXT -  The retrieved handle identifies the window below the specified window in the Z order.
+      #                       If the specified window is a topmost window, the handle identifies the topmost window
+      #                       below the specified window. If the specified window is a top-level window, the handle
+      #                       identifies the top-level window below the specified window. If the specified window is
+      #                       a child window, the handle identifies the sibling window below the specified window.
+      #        GW_HWNDPREV -  The retrieved handle identifies the window above the specified window in the Z order.
+      #                       If the specified window is a topmost window, the handle identifies the topmost window
+      #                       above the specified window. If the specified window is a top-level window, the handle
+      #                       identifies the top-level window above the specified window. If the specified window is
+      #                       a child window, the handle identifies the sibling window above the specified window.
+      #        GW_OWNER - The retrieved handle identifies the specified window's owner window, if any. For more
+      #                   information, see Owned Windows.
+      # *Returns*:: If the function succeeds, the return value is a window handle. If no window exists with
+      #             the specified relationship to the specified window, the return value is NULL. To get
+      #             extended error information, call GetLastError.
+      # ---
+      # *Remarks*:
+      # The EnumChildWindows function is more reliable than calling GetWindow in a loop. An application that
+      # calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to
+      # a window that has been destroyed.
+      # Function Information
+      #
+      # ---
+      # <b>Enhanced (snake_case) API: returns nil instead of 0 in case of failure</b>
+      #
+      # :call-seq:
+      #  window_handle = get_window(h_wnd, u_cmd)
+      #
+      function :GetWindow, [:HWND, :UINT], :HWND, zeronil: true
+
+      ##
+      # The GetParent function retrieves a handle to the specified window's parent OR OWNER.
+      # To retrieve a handle to a specified ancestor, use the GetAncestor function.
+      #
+      # [*Syntax*] HWND GetParent( HWND hWnd );
+      #
+      # hWnd:: [in] Handle to the window whose parent window handle is to be retrieved.
+      #
+      # *Returns*:: If the window is a child window, the return value is a handle to the parent window. If the
+      #             window is a top-level window, the return value is a handle to the owner window. If the
+      #             window is a top-level unowned window or if the function fails, the return value is NULL.
+      #             To get extended error information, call GetLastError. For example, this would determine,
+      #             when the function returns NULL, if the function failed or the window was a top-level window.
+      # ---
+      # *Remarks*:
+      # Note that, despite its name, this function can return an owner window instead of a parent window. To
+      # obtain the parent window and not the owner, use GetAncestor with the GA_PARENT flag.
+      #
+      # ---
+      # <b>Enhanced (snake_case) API: returns nil instead of 0 in case of failure</b>
+      #
+      # :call-seq:
+      #  parent = get_parent(h_wnd)
+      #
+      function :GetParent, [:HWND], :HWND, zeronil: true
+
+      ##
+      # The GetAncestor function retrieves the handle to the ancestor of the specified window.
+      #
+      # [*Syntax*] HWND GetAncestor( HWND hwnd, UINT gaFlags );
+      #
+      # hwnd:: [in] Handle to the window whose ancestor is to be retrieved. If this parameter is the desktop
+      #        window, the function returns NULL.
+      # gaFlags:: [in] Specifies the ancestor to be retrieved. This parameter can be one of the following values:
+      #           GA_PARENT - Retrieves parent window. Unlike GetParent function, this does NOT include the owner.
+      #           GA_ROOT - Retrieves the root window by walking the chain of parent windows.
+      #           GA_ROOTOWNER - Retrieves the owned root window by walking the chain of parent and owner windows
+      #                          returned by GetParent.
+      #
+      # *Returns*:: The return value is the handle to the ancestor window.
+      # ---
+      # <b>Enhanced (snake_case) API: returns nil instead of 0 in case of failure</b>
+      #
+      # :call-seq:
+      #  ancestor = get_ancestor(hwnd, ga_flags)
+      #
+      function :GetAncestor, [:HWND, :UINT], :HWND, zeronil: true
 
+      
       # Convenience wrapper methods:
 
       ##

data/lib/win/library.rb

@@ -365,8 +365,8 @@ module Win
 
           define_method snake_name, &method_body       # define snake_case instance method
 
-          eigenklass = class << self; self; end        # Extracting eigenclass
-          eigenklass.class_eval do
+          eigen_class = class << self; self; end        # Extracting eigenclass
+          eigen_class.class_eval do
             define_method snake_name, &method_body       # define snake_case class method
           end
         end
@@ -446,23 +446,23 @@ module Win
     # Hook executed when Win::Library is included into class or module. It extends host class/module
     # with both FFI::Library methods and Win::Library macro methods like 'function'.
     #
-    def self.included(klass)
-      klass.extend FFI::Library
+    def self.included(host_class)
+      host_class.extend FFI::Library
 
       # Extracting host class's eigenclass
       # :stopdoc:
-      eigenklass = class << klass; self; end      # :nodoc:
+      eigen_class = class << host_class; self; end      # :nodoc:
 
-      eigenklass.class_eval do
-        define_method(:namespace) {klass}         # Defining new class method for host pointing to itself
+      eigen_class.class_eval do
+        define_method(:namespace) {host_class}         # Defining new class method for host class pointing to itself
         alias_method :attach_callback, :callback
 
         include ClassMethods
       end
       # :startdoc:
 
-      klass.ffi_lib 'user32', 'kernel32'  # Default libraries
-      klass.ffi_convention :stdcall
+      host_class.ffi_lib 'user32', 'kernel32'  # Default libraries
+      host_class.ffi_convention :stdcall
     end
   end
 end

data/spec/spec_helper.rb

@@ -4,7 +4,7 @@ require 'spec'
 require 'spec/autorun'
 require 'win/gui'
 
-$debug = true
+$debug = false
 
 # Customize RSpec with my own extensions
 module ClassMacros
@@ -13,7 +13,6 @@ module ClassMacros
   # spec { use{    function(arg1 = 4, arg2 = 'string')  }}
   def spec &block
     it description_from(caller[0]), &block # it description_from(*block.source_location), &block
-    #do lambda(&block).should_not raise_error end
   end
 
   # reads description line from source file and drops external brackets like its{}, use{}
@@ -46,11 +45,11 @@ Spec::Runner.configure do |config|
   config.extend(ClassMacros)
   config.include(InstanceMacros)
 
-  class << Spec::ExampleGroup
-#    def spoc &block
-#      it description_from(caller[0]), &block
-#    end
-  end
+#  class << Spec::ExampleGroup
+##    def spoc &block
+##      it description_from(caller[0]), &block
+##    end
+#  end
 end
 
 # Global test methods
@@ -72,17 +71,19 @@ end
 
 module WinTest
 
-  TEST_KEY_DELAY = 0.001
-  TEST_IMPOSSIBLE = 'Impossible'
-  TEST_CONVERSION_ERROR = /Can.t convert/
-  TEST_SLEEP_DELAY = 0.02
-  TEST_APP_PATH = File.join(File.dirname(__FILE__), "test_apps/locknote/LockNote.exe" )
-  TEST_APP_START = cygwin? ? "cmd /c start `cygpath -w #{TEST_APP_PATH}`" : 'start "" "' + TEST_APP_PATH + '"'
-  TEST_WIN_TITLE = 'LockNote - Steganos LockNote'
-  TEST_WIN_CLASS = 'ATL:00434098'
-  TEST_WIN_RECT = [710, 400, 1210, 800]
-  TEST_STATUSBAR_CLASS = 'msctls_statusbar32'
-  TEST_TEXTAREA_CLASS = 'ATL:00434310'
+  KEY_DELAY = 0.001
+  IMPOSSIBLE = 'Impossible'
+  CONVERSION_ERROR = /Can.t convert/
+  SLEEP_DELAY = 0.02
+  APP_PATH = File.join(File.dirname(__FILE__), "test_apps/locknote/LockNote.exe" )
+  APP_START = cygwin? ? "cmd /c start `cygpath -w #{APP_PATH}`" : 'start "" "' + APP_PATH + '"'
+  WIN_TITLE = 'LockNote - Steganos LockNote'
+  WIN_RECT = [710, 400, 1210, 800]
+  WIN_CLASS = 'ATL:00434098'
+  STATUSBAR_CLASS = 'msctls_statusbar32'
+  TEXTAREA_CLASS = 'ATL:00434310'
+  DESKTOP_CLASS = '#32769'
+  MENU_CLASS = '#32768'
 
   def any_handle
     find_window(nil, nil)
@@ -104,14 +105,14 @@ module WinTestApp
   #include Win::Gui::Convenience
 
   def launch_test_app
-    system TEST_APP_START
-    sleep TEST_SLEEP_DELAY until (handle = find_window(nil, TEST_WIN_TITLE))
+    system APP_START
+    sleep SLEEP_DELAY until (handle = find_window(nil, WIN_TITLE))
 
-    textarea = find_window_ex(handle, 0, TEST_TEXTAREA_CLASS, nil)
+    textarea = find_window_ex(handle, 0, TEXTAREA_CLASS, nil)
     app = "Locknote" # App identifier
 
-    eigenklass = class << app; self; end      # Extracting app's eigenclass
-    eigenklass.class_eval do                  # Defining singleton methods on app
+    eigen_class = class << app; self; end      # Extracting app's eigenclass
+    eigen_class.class_eval do                  # Defining singleton methods on app
       define_method(:handle) {handle}
       define_method(:textarea) {textarea}
     end
@@ -120,9 +121,9 @@ module WinTestApp
   end
 
   def close_test_app(app = @launched_test_app)
-    while app && app.respond_to?( :handle) && find_window(nil, TEST_WIN_TITLE)
+    while app && app.respond_to?( :handle) && find_window(nil, WIN_TITLE)
       shut_window app.handle
-      sleep TEST_SLEEP_DELAY
+      sleep SLEEP_DELAY
     end
     @launched_test_app = nil
   end
@@ -132,7 +133,7 @@ module WinTestApp
     app = launch_test_app
 
 #    def app.textarea #define singleton method retrieving app's text area
-#      Window::Window.new find_window_ex(self.handle, 0, TEST_TEXTAREA_CLASS, nil)
+#      Window::Window.new find_window_ex(self.handle, 0, TEXTAREA_CLASS, nil)
 #    end
 
     yield app

data/spec/win/error_spec.rb

@@ -21,14 +21,14 @@ module WinErrorTest
       spec{ use{ err_message = get_last_error() }}
 
       it "original api retrieves the calling thread's last-error code value" do
-        find_window(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE)
+        find_window(IMPOSSIBLE, IMPOSSIBLE)
         GetLastError().should == ERROR_FILE_NOT_FOUND
         window_text(0)
         GetLastError().should == ERROR_INVALID_WINDOW_HANDLE
       end
 
       it "enhanced api retrieves the message corresponding to last error code" do
-        find_window(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE)
+        find_window(IMPOSSIBLE, IMPOSSIBLE)
         get_last_error.should == "The system cannot find the file specified."
         window_text(0)
         get_last_error.should == "Invalid window handle."
@@ -40,7 +40,7 @@ module WinErrorTest
       spec{ use{ message = format_message(sys_flags, source=nil, message_id=0, language_id=0, :int, 0) }}
 
       it "original api formats a message string - system message" do
-        find_window(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE)
+        find_window(IMPOSSIBLE, IMPOSSIBLE)
         message_id = GetLastError()
         buf = buffer()
         num_chars = FormatMessage(sys_flags, nil, message_id, dw_language_id=0, buf, buf.size, :int, 0)
@@ -48,7 +48,7 @@ module WinErrorTest
       end
 
       it "snake_case api Formats a message string - system message" do
-        find_window(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE)
+        find_window(IMPOSSIBLE, IMPOSSIBLE)
         message = format_message(sys_flags, nil, dw_message_id=GetLastError())
         message.should == "The system cannot find the file specified."
       end

data/spec/win/extensions_spec.rb

@@ -53,20 +53,20 @@ module WinTest
       end
       
       it 'raises error if char is not implemented punctuation' do
-       ('!'..'/').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
-       (':'..'@').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
-       ('['..'`').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
-       ('{'..'~').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
+       ('!'..'/').each {|char| lambda {char.to_vkeys}.should raise_error CONVERSION_ERROR }
+       (':'..'@').each {|char| lambda {char.to_vkeys}.should raise_error CONVERSION_ERROR }
+       ('['..'`').each {|char| lambda {char.to_vkeys}.should raise_error CONVERSION_ERROR }
+       ('{'..'~').each {|char| lambda {char.to_vkeys}.should raise_error CONVERSION_ERROR }
       end
       
       it 'raises error if char is non-printable or non-ascii' do
-        lambda {1.chr.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
-        lambda {230.chr.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
+        lambda {1.chr.to_vkeys}.should raise_error CONVERSION_ERROR
+        lambda {230.chr.to_vkeys}.should raise_error CONVERSION_ERROR
       end
       
       it 'raises error if string is multi-char' do
-        lambda {'hello'.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
-        lambda {'23'.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
+        lambda {'hello'.to_vkeys}.should raise_error CONVERSION_ERROR
+        lambda {'23'.to_vkeys}.should raise_error CONVERSION_ERROR
       end  
     end
   end

data/spec/win/gui/input_spec.rb

@@ -17,9 +17,9 @@ module WinWindowTest
           text = '12 34'
           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
+            sleep KEY_DELAY
             keybd_event(b.ord, 0, KEYEVENTF_KEYUP, 0)
-            sleep TEST_KEY_DELAY
+            sleep KEY_DELAY
           end
           text(app.textarea).should =~ Regexp.new(text)
           5.times {keystroke(VK_CONTROL, 'Z'.ord)} # rolling back changes to allow window closing without dialog!

data/spec/win/gui/message_spec.rb

@@ -52,7 +52,7 @@ module WinGuiMessageTest
       it 'places (posts) a message in the message queue associated with the thread that created the specified window' do
         app = launch_test_app
         post_message(app.handle, WM_SYSCOMMAND, SC_CLOSE, nil).should == true
-        sleep TEST_SLEEP_DELAY
+        sleep SLEEP_DELAY
         window?(app.handle).should == false
       end
 
@@ -80,7 +80,7 @@ module WinGuiMessageTest
         buffer.get_bytes(0, num_chars).should =~ /Welcome to Steganos LockNote/
 
         send_message(app.handle, WM_SYSCOMMAND, SC_CLOSE, nil)
-        sleep TEST_SLEEP_DELAY  # delay to allow window close
+        sleep SLEEP_DELAY  # delay to allow window close
         window?(app.handle).should == false
       end
     end # describe '#send_message'
@@ -104,7 +104,7 @@ module WinGuiMessageTest
         @data.should == nil
         @result.should == nil
 
-        sleep TEST_SLEEP_DELAY # small delay to allow message delivery
+        sleep SLEEP_DELAY # small delay to allow message delivery
         peek_message           # dispatching sent message (even though there is nothing in queue)
 
         @handle.should == @app.handle
@@ -118,7 +118,7 @@ module WinGuiMessageTest
         sent.should == true
         @data.should == nil
 
-        sleep TEST_SLEEP_DELAY # small delay to allow message delivery
+        sleep SLEEP_DELAY # small delay to allow message delivery
         peek_message           # dispatching sent message (even though there is nothing in queue)
 
         @data.should == 0

data/spec/win/gui/window_spec.rb

@@ -135,16 +135,16 @@ module WinWindowTest
 
         it 'returns either Integer Window handle or nil' do
           find_window(nil, nil).should be_a_kind_of Integer
-          find_window(TEST_IMPOSSIBLE, nil).should == nil
+          find_window(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
-          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
+          find_window(IMPOSSIBLE, nil).should == nil
+          find_window(nil, IMPOSSIBLE).should == nil
+          find_window(IMPOSSIBLE, IMPOSSIBLE).should == nil
+          find_window_w(IMPOSSIBLE, nil).should == nil
+          find_window_w(nil, IMPOSSIBLE).should == nil
+          find_window_w(IMPOSSIBLE, IMPOSSIBLE).should == nil
         end
 
         it 'finds at least one window if both args are nils' do
@@ -154,10 +154,10 @@ module WinWindowTest
 
         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
+            find_window(WIN_CLASS, nil).should == app.handle
+            find_window(nil, WIN_TITLE).should == app.handle
+            find_window_w(WIN_CLASS.to_w, nil).should == app.handle
+            find_window_w(nil, WIN_TITLE.to_w).should == app.handle
           end
         end
       end
@@ -168,13 +168,13 @@ module WinWindowTest
 
         it 'returns nil if wrong control is given' do
           parent_handle = any_handle
-          find_window_ex(parent_handle, 0, TEST_IMPOSSIBLE, nil).should == nil
-          find_window_ex(parent_handle, 0, nil, TEST_IMPOSSIBLE).should == nil
+          find_window_ex(parent_handle, 0, IMPOSSIBLE, nil).should == nil
+          find_window_ex(parent_handle, 0, nil, IMPOSSIBLE).should == nil
         end
 
         it 'finds child window/control by class' do
           test_app do |app|
-            ta_handle = find_window_ex(app.handle, 0, TEST_TEXTAREA_CLASS, nil)
+            ta_handle = find_window_ex(app.handle, 0, TEXTAREA_CLASS, nil)
             ta_handle.should_not == nil
             ta_handle.should == app.textarea
           end
@@ -252,10 +252,10 @@ module WinWindowTest
 
         it 'returns correct window text' do
           test_app do |app|
-            get_window_text(app.handle).should == TEST_WIN_TITLE
-            get_window_text_w(app.handle).should == TEST_WIN_TITLE
-            window_text(app.handle).should == TEST_WIN_TITLE
-            window_text_w(app.handle).should == TEST_WIN_TITLE
+            get_window_text(app.handle).should == WIN_TITLE
+            get_window_text_w(app.handle).should == WIN_TITLE
+            window_text(app.handle).should == WIN_TITLE
+            window_text_w(app.handle).should == WIN_TITLE
           end
         end
       end
@@ -272,10 +272,10 @@ module WinWindowTest
 
         it 'returns correct window class name' do
           test_app do |app|
-            get_class_name(app.handle).should == TEST_WIN_CLASS
-            class_name(app.handle).should == TEST_WIN_CLASS
-            class_name_w(app.handle).should == TEST_WIN_CLASS  #!!!!!!!!!!! nil?
-            get_class_name_w(app.handle).should == TEST_WIN_CLASS #!!!!!! nil?
+            get_class_name(app.handle).should == WIN_CLASS
+            class_name(app.handle).should == WIN_CLASS
+            class_name_w(app.handle).should == WIN_CLASS  #!!!!!!!!!!! nil?
+            get_class_name_w(app.handle).should == WIN_CLASS #!!!!!! nil?
           end
         end
       end
@@ -310,7 +310,7 @@ module WinWindowTest
 
         it 'returns window`s border rectangle' do
           test_app do |app|
-            get_window_rect(app.handle).should == TEST_WIN_RECT
+            get_window_rect(app.handle).should == WIN_RECT
           end
         end
       end
@@ -399,12 +399,128 @@ module WinWindowTest
         end
       end # describe 'destroy_window'
 
+
     end # context 'ensuring test app closes'
 
     context 'with single test app' do
       before(:all){@app = launch_test_app}
       after(:all){close_test_app}
 
+      describe "#get_parent" do
+        spec{ use{ parent = GetParent(any_handle) }}
+        spec{ use{ parent = get_parent(any_handle) }}
+
+        it "retrieves a handle to the specified window's parent or owner." do
+          child = find_window_ex(@app.handle, 0, nil, nil)
+          parent1 = GetParent(child)
+          parent2 = get_parent(child)
+          parent1.should == parent2
+          parent1.should == @app.handle
+        end
+
+        it "returns 0/nil if the specified window has no parent or owner." do
+          GetParent(@app.handle).should == 0
+          get_parent(@app.handle).should == nil
+        end
+      end # describe get_parent
+
+      describe "#get_ancestor" do
+        spec{ use{ ancestor = GetAncestor(any_handle, ga_flags=0) }}
+        spec{ use{ ancestor = get_ancestor(any_handle, ga_flags=0) }}
+
+        context 'GA_PARENT - Retrieves parent window. Unlike GetParent function, this does NOT include the owner.' do
+          it "retrieves a handle to the specified window's parent" do
+            child = find_window_ex(@app.handle, 0, nil, nil)
+            parent1 = GetAncestor(child, GA_PARENT)
+            parent2 = get_ancestor(child, GA_PARENT)
+            parent1.should == parent2
+            parent1.should == @app.handle
+          end
+
+          it "returns desktop handle for top-level window" do
+            parent = get_ancestor(@app.handle, GA_PARENT)
+            class_name(parent).should == DESKTOP_CLASS
+          end
+
+          it "returns 0/nil if the specified window is a desktop (has REALLY no parent)" do
+            desktop = get_ancestor(@app.handle, GA_PARENT)
+            GetAncestor(desktop, GA_PARENT).should == 0
+            get_ancestor(desktop, GA_PARENT).should == nil
+          end
+        end # context GA_PARENT
+
+        #           GA_ROOT - Retrieves the root window by walking the chain of parent windows.
+        #           GA_ROOTOWNER - Retrieves the owned root window by walking the chain of parent and owner windows
+        #                          returned by GetParent.
+        it "original api retrieves the handle to the ancestor of the specified window. " do
+          pending
+          success = GetAncestor(hwnd=0, ga_flags=0)
+        end
+
+        it "snake_case api retrieves the handle to the ancestor of the specified window. " do
+          pending
+          success = get_ancestor(hwnd=0, ga_flags=0)
+        end
+
+      end # describe get_ancestor
+
+      describe "#get_window" do
+        spec{ use{ handle = GetWindow(any_handle, command=0) }}
+        spec{ use{ handle = get_window(any_handle, command=0) }}
+
+        context "GW_CHILD retrieves a window handle to a first (top of the Z order) child of given window" do
+          before(:all) do
+            #        GW_CHILD - The retrieved handle identifies the child window at the top of the Z order, if the specified
+            @child1 = GetWindow(@app.handle, GW_CHILD)
+            @child2 = get_window(@app.handle, GW_CHILD)
+          end
+
+          it 'returns active window handle' do
+            window?(@child1).should == true
+          end
+          it 'returns the same value for original and snake case API' do
+            @child1.should == @child2
+          end
+          it 'returns first direct child of a given window' do
+            @child1.should == find_window_ex(@app.handle, 0, nil, nil)
+          end
+          it 'returns nil/0 if no children for a given window' do
+            GetWindow(@child1, GW_CHILD).should == 0
+            get_window(@child1, GW_CHILD).should == nil
+          end
+        end # context GW_CHILD
+
+        context "GW_OWNER - retrieves a handle to an owner of a given Window" do
+          #        GW_OWNER - The retrieved handle identifies the specified window's owner window, if any. For more
+
+          it 'returns owner (but NOT parent!) of a given window' do
+            pending
+
+            child = find_window_ex(@app.handle, 0, nil, nil)
+            p owner1 = GetWindow(child, GW_OWNER)
+            p owner2 = get_window(child, GW_OWNER)
+            owner1.should == owner2
+            owner1.should == @app.handle
+          end
+
+          it 'returns nil/0 if no owner for a given window' do
+            GetWindow(@app.handle, GW_OWNER).should == 0
+            get_window(@app.handle, GW_OWNER).should == nil
+          end
+
+        end
+
+        it "GW_OWNER - retrieves a handle to a window that has the specified relationship to given Window" do
+          pending
+          #        GW_ENABLEDPOPUP - Windows 2000/XP: The retrieved handle identifies the enabled popup window owned by
+          #        GW_HWNDFIRST - The retrieved handle identifies the window of the same type that is highest in Z order.
+          #        GW_HWNDLAST -  The retrieved handle identifies the window of the same type that is lowest in the Z order.
+          #        GW_HWNDNEXT -  The retrieved handle identifies the window below the specified window in the Z order.
+          #        GW_HWNDPREV -  The retrieved handle identifies the window above the specified window in the Z order.
+          #        GW_OWNER - The retrieved handle identifies the specified window's owner window, if any. For more
+        end
+      end # describe get_window
+
       describe '#enum_windows' do
 #        before(:each){@app = launch_test_app}
 #        after(:each){close_test_app}
@@ -460,8 +576,8 @@ module WinWindowTest
           enum = enum_child_windows(@app.handle, 13)
           enum.should be_a_kind_of Array
           enum.should have(2).elements
-          class_name(enum.first).should == TEST_STATUSBAR_CLASS
-          class_name(enum.last).should == TEST_TEXTAREA_CLASS
+          class_name(enum.first).should == STATUSBAR_CLASS
+          class_name(enum.last).should == TEXTAREA_CLASS
         end
 
         it 'loops through all children of given window, passing each found window handle and a message to a given block' do
@@ -471,8 +587,8 @@ module WinWindowTest
             message.should == 13
           end
           enum.should have(2).elements
-          class_name(enum.first).should == TEST_STATUSBAR_CLASS
-          class_name(enum.last).should == TEST_TEXTAREA_CLASS
+          class_name(enum.first).should == STATUSBAR_CLASS
+          class_name(enum.last).should == TEXTAREA_CLASS
         end
 
         it 'breaks loop if given block returns false' do
@@ -482,7 +598,7 @@ module WinWindowTest
             false
           end
           enum.should have(1).element
-          class_name(enum.first).should == TEST_STATUSBAR_CLASS
+          class_name(enum.first).should == STATUSBAR_CLASS
         end
 
         it 'defaults message to 0 if it is omitted from method call' do
@@ -528,7 +644,7 @@ module WinWindowTest
         app = launch_test_app
 
         shut_window(app.handle).should == true
-        sleep TEST_SLEEP_DELAY
+        sleep SLEEP_DELAY
 
         window?(app.handle).should == false
       end
@@ -540,7 +656,7 @@ module WinWindowTest
       it 'returns text associated with window by sending WM_GETTEXT message to it' do
         test_app do |app|
 
-          text(app.handle).should == TEST_WIN_TITLE
+          text(app.handle).should == WIN_TITLE
           text(app.textarea).should =~ /Welcome to Steganos LockNote/
         end
       end

data/spec/win/library_spec.rb

@@ -92,12 +92,12 @@ module WinLibraryTest
 
         it 'constructs argument prototype from uppercase string, enforces the args count' do
           expect { MyLib.function :FindWindow, 'PP', 'L' }.to_not raise_error
-          should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+          should_count_args :find_window, :FindWindow, [nil, nil], [nil, IMPOSSIBLE, 'cmd']
         end
 
         it 'constructs argument prototype from (mixed) array, enforces the args count' do
           expect { MyLib.function :FindWindow, [:pointer, 'P'], 'L' }.to_not raise_error
-          should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+          should_count_args :find_window, :FindWindow, [nil, nil], [nil, IMPOSSIBLE, 'cmd']
         end
 
         it 'with :rename option, overrides snake_case name for defined method but leaves CamelCase intact' do
@@ -110,17 +110,17 @@ module WinLibraryTest
         it 'defined snake_case method returns expected value when called' do
           MyLib.function :FindWindow, 'PP', 'L'
           find_window(nil, nil).should_not == 0
-          find_window(nil, TEST_IMPOSSIBLE).should == 0
-          find_window(TEST_IMPOSSIBLE, nil).should == 0
-          find_window(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE).should == 0
+          find_window(nil, IMPOSSIBLE).should == 0
+          find_window(IMPOSSIBLE, nil).should == 0
+          find_window(IMPOSSIBLE, IMPOSSIBLE).should == 0
         end
 
         it 'defined CamelCase method returns expected value when called' do
           MyLib.function :FindWindow, 'PP', 'L'
           FindWindow(nil, nil).should_not == 0
-          FindWindow(nil, TEST_IMPOSSIBLE).should == 0
-          FindWindow(TEST_IMPOSSIBLE, nil).should == 0
-          FindWindow(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE).should == 0
+          FindWindow(nil, IMPOSSIBLE).should == 0
+          FindWindow(IMPOSSIBLE, nil).should == 0
+          FindWindow(IMPOSSIBLE, IMPOSSIBLE).should == 0
         end
 
 #      it 'returns underlying Win32::API object if defined method is called with (:api) argument ' do
@@ -172,17 +172,17 @@ module WinLibraryTest
 
         it 'defined snake_case method returns false/true instead of zero/non-zero' do
           find_window(nil, nil).should == true
-          find_window(nil, TEST_IMPOSSIBLE).should == false
+          find_window(nil, IMPOSSIBLE).should == false
         end
 
         it 'defined CamelCase method still returns zero/non-zero' do
           FindWindow(nil, nil).should_not == true
           FindWindow(nil, nil).should_not == 0
-          FindWindow(nil, TEST_IMPOSSIBLE).should == 0
+          FindWindow(nil, IMPOSSIBLE).should == 0
         end
 
         it 'defined methods enforce the argument count' do
-          should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+          should_count_args :find_window, :FindWindow, [nil, nil], [nil, IMPOSSIBLE, 'cmd']
         end
       end
 
@@ -197,12 +197,12 @@ module WinLibraryTest
         it 'defined CamelCase method still returns zero/non-zero' do
           FindWindow(nil, nil).should_not == true
           FindWindow(nil, nil).should_not == 0
-          FindWindow(nil, TEST_IMPOSSIBLE).should == 0
+          FindWindow(nil, IMPOSSIBLE).should == 0
         end
 
         it 'defined method returns nil (but NOT false) instead of zero' do
-          find_window(nil, TEST_IMPOSSIBLE).should_not == false
-          find_window(nil, TEST_IMPOSSIBLE).should == nil
+          find_window(nil, IMPOSSIBLE).should_not == false
+          find_window(nil, IMPOSSIBLE).should == nil
         end
 
         it 'defined method does not return true when result is non-zero' do
@@ -211,7 +211,7 @@ module WinLibraryTest
         end
 
         it 'defined methods enforce the argument count' do
-          should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+          should_count_args :find_window, :FindWindow, [nil, nil], [nil, IMPOSSIBLE, 'cmd']
         end
       end
 
@@ -292,18 +292,18 @@ module WinLibraryTest
       context 'calling defined methods with attached block to preprocess the API function results' do
         it 'defined method yields raw result to block attached to its invocation' do
           MyLib.function :FindWindow, 'PP', 'L', zeronil: true
-          find_window(nil, TEST_IMPOSSIBLE) {|result| result.should == 0 }
+          find_window(nil, IMPOSSIBLE) {|result| result.should == 0 }
         end
 
         it 'defined method returns result of block attached to its invocation' do
           MyLib.function :FindWindow, 'PP', 'L', zeronil: true
-          return_value = find_window(nil, TEST_IMPOSSIBLE) {|result| 'Value'}
+          return_value = find_window(nil, IMPOSSIBLE) {|result| 'Value'}
           return_value.should == 'Value'
         end
 
         it 'defined method transforms result of block before returning it' do
           MyLib.function :FindWindow, 'PP', 'L', zeronil: true
-          return_value = find_window(nil, TEST_IMPOSSIBLE) {|result| 0 }
+          return_value = find_window(nil, IMPOSSIBLE) {|result| 0 }
           return_value.should_not == 0
           return_value.should == nil
         end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 3
-  version: 0.3.3
+  - 5
+  version: 0.3.5
 platform: ruby
 authors: 
 - arvicco
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-17 00:00:00 +04:00
+date: 2010-05-28 00:00:00 +04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency