win_gui 0.1.1 → 0.1.2

data/README.rdoc

@@ -37,10 +37,15 @@ Contributors always welcome!
   require 'win_gui'
   include WinGui
 
-More examples will follow as the code will be closer to production quality...  
+More examples will follow when the code is closer to production quality...  
+
+== CREDITS:
+
+This library started as an extension of ideas and code described in excellent book
+"Scripted GUI Testing with Ruby" by Ian Dees.
 
 == Note on Patches/Pull Requests
- 
+
 * Fork the project.
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a
@@ -49,11 +54,6 @@ More examples will follow as the code will be closer to production quality...
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
-== CREDITS:
-
-This library started as an extension of ideas and code described in excellent book
-"Scripted GUI Testing with Ruby" by Ian Dees.
-
 == LICENSE:
 
 Copyright (c) 2009 Arvicco. See LICENSE for details

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

data/lib/win_gui/constants.rb

@@ -1,7 +1,7 @@
 module WinGui
   
   # WinGui Module internal Constants:
-  WG_DLL_DEFAULT = 'user32'
+
   WG_KEY_DELAY = 0.00001 
   WG_SLEEP_DELAY = 0.001 
   WG_CLOSE_TIMEOUT = 1
@@ -9,19 +9,20 @@ module WinGui
   
   # Windows keyboard-related Constants:
   #   Virtual key codes:
+
   VK_CANCEL   = 0x03 # Control-break processing
   VK_BACK     = 0x08
   VK_TAB      = 0x09
   VK_SHIFT    = 0x10
   VK_CONTROL  = 0x11
-  VK_RETURN   = 0x0D #   ENTER key
-  VK_ALT      = 0x12 #   ALT key
-  VK_MENU     = 0x12 #   ALT key alias
-  VK_PAUSE    = 0x13 #   PAUSE key
-  VK_CAPITAL  = 0x14 #   CAPS LOCK key
-  VK_ESCAPE   = 0x1B #   ESC key
-  VK_SPACE    = 0x20 #   SPACEBAR
-  VK_PRIOR    = 0x21 #   PAGE UP key
+  VK_RETURN   = 0x0D  #  ENTER key
+  VK_ALT      = 0x12  #  ALT key
+  VK_MENU     = 0x12  #  ALT key alias
+  VK_PAUSE    = 0x13  #  PAUSE key
+  VK_CAPITAL  = 0x14  #  CAPS LOCK key
+  VK_ESCAPE   = 0x1B  #  ESC key
+  VK_SPACE    = 0x20  #  SPACEBAR
+  VK_PRIOR    = 0x21  #  PAGE UP key
   VK_NEXT     = 0x22  #  PAGE DOWN key
   VK_END      = 0x23  #  END key
   VK_HOME     = 0x24  #  HOME key
@@ -36,11 +37,14 @@ module WinGui
   VK_INSERT   = 0x2D  #  INS key
   VK_DELETE   = 0x2E  #  DEL key
   VK_HELP     = 0x2F  #  HELP key
+
   #   Key events:
-  KEYEVENTF_KEYDOWN = 0 
+
+  KEYEVENTF_KEYDOWN = 0
   KEYEVENTF_KEYUP = 2 
   
-  # Show Window Commands:
+  #   Show Window Commands:
+
   SW_HIDE           = 0
   SW_NORMAL         = 1
   SW_SHOWNORMAL     = 1
@@ -57,6 +61,7 @@ module WinGui
   SW_FORCEMINIMIZE  = 11
   
   # Windows Messages Constants:
+
   WM_GETTEXT = 0x000D
   WM_SYSCOMMAND = 0x0112
   SC_CLOSE = 0xF060

data/lib/win_gui/def_api.rb

@@ -1,5 +1,7 @@
 module WinGui
   module DefApi
+    DEFAULT_DLL = 'user32'
+
     # Defines new instance method wrapper for Windows API function call. Converts CamelCase function name
     # into snake_case method name, renames test functions according to Ruby convention (IsWindow -> window?)
     # When the defined wrapper method is called, it executes underlying API function call, yields the result
@@ -10,6 +12,7 @@ module WinGui
     # and (optional) runtime block to &define_block that should define method content and return result.
     #
     # Accepts following options:
+    # :dll:: Use this dll instead of default 'user32'
     # :rename:: Use this name instead of standard (conventional) function name
     # :alias(es):: Provides additional alias(es) for defined method
     # :boolean:: Forces method to return true/false instead of nonzero/zero
@@ -25,9 +28,9 @@ module WinGui
       zeronil = options[:zeronil]
       aliases = ([options[:alias]] + [options[:aliases]]).flatten.compact
       proto = params.respond_to?(:join) ? params.join : params # Converts params into prototype string
-      api = Win32::API.new(function, proto.upcase, returns.upcase, options[:dll] || WG_DLL_DEFAULT)
+      api = Win32::API.new(function, proto.upcase, returns.upcase, options[:dll] || DEFAULT_DLL)
 
-      define_method(name) do |*args, &runtime_block| 
+      define_method(name) do |*args, &runtime_block|
         return api if args == [:api]
         return define_block.call(api, *args, &runtime_block) if define_block
         raise 'Invalid args count' unless args.size == params.size
@@ -51,5 +54,38 @@ module WinGui
     def buffer(size = 1024, code = "\x00")
       code * size
     end
+
+    # Procedure that returns (possibly encoded) string as a result of api function call
+    def return_string( encode = nil )
+      lambda do |api, *args|
+        raise 'Invalid args count' unless args.size == api.prototype.size-2
+        args += [string = buffer, string.length]
+        num_chars = api.call(*args) # num_chars not used
+        string = string.force_encoding('utf-16LE').encode(encode) if encode
+        string.rstrip
+      end
+    end
+
+    # Procedure that calls api function expecting a callback. If runtime block is given
+    # it is converted into callback, otherwise procedure returns an array of all handles
+    # pushed into callback by api enumeration
+    def return_enum
+      lambda do |api, *args, &block|
+        raise 'Invalid args count' unless args.size == api.prototype.size-1
+        handles = []
+        cb = if block
+          callback('LP', 'I', &block)
+        else
+          callback('LP', 'I') do |handle, message|
+            handles << handle
+            true
+          end
+        end
+        args[api.prototype.find_index('K'), 0] = cb # Insert callback into appropriate place of args Array
+        api.call *args
+        handles
+      end
+    end
+
   end
 end

data/lib/win_gui/win_gui.rb

@@ -13,108 +13,98 @@ require 'window'
 
 module WinGui
   self.extend DefApi
-  
-  return_string_proc = lambda do |api, *args|
-    raise 'Invalid args count' unless args.size == api.prototype.size-2
-    args += [string = buffer, string.length]
-    num_chars = api.call(*args) # num_chars not used
-    string.rstrip
-  end
-
-  return_utf_string_proc = lambda do |api, *args|
-    raise 'Invalid args count' unless args.size == api.prototype.size-2
-    args += [string = buffer, string.length]
-    num_chars = api.call(*args) # num_chars not used
-    string.force_encoding('utf-16LE').encode('utf-8').rstrip
-  end
-
-  return_enum_proc = Proc.new do |api, *args, &block|
-    raise 'Invalid args count' unless args.size == api.prototype.size-1
-    handles = []
-    cb = if block
-      callback('LP', 'I', &block)
-    else
-      callback('LP', 'I') do |handle, message|
-        handles << handle
-        true
-      end
-    end
-    api.call *(args.size == 1 ? [cb, args.first] : [args.first, cb, args.last])
-    handles
-  end
 
   # Windows GUI API definitions:
 
   # Tests whether the specified window handle identifies an existing window.
-  #   A thread should not use IsWindow for a window that it did not create because the window could be destroyed after this
-  #   function was called. Further, because window handles are recycled the handle could even point to a different window.
+  #   A thread should not use IsWindow for a window that it did not create because the window
+  #   could be destroyed after this function was called. Further, because window handles are
+  #   recycled the handle could even point to a different window.
+  #
   def_api 'IsWindow', 'L', 'L'
 
-  # Tests if the specified window, its parent window, its parent's parent window, and so forth, have the WS_VISIBLE style.
-  # Because the return value specifies whether the window has the WS_VISIBLE style, it may be true even if the window is totally obscured by other windows.
-  def_api 'IsWindowVisible', 'L', 'L'
-  alias visible? window_visible?
+  # Tests if the specified window, its parent window, its parent's parent window, and so forth,
+  # have the WS_VISIBLE style. Because the return value specifies whether the window has the
+  # WS_VISIBLE style, it may be true even if the window is totally obscured by other windows.
+  #
+  def_api 'IsWindowVisible', 'L', 'L', :alias => :visible?
 
-  def_api 'IsZoomed', 'L', 'L'
-  alias maximized? zoomed?
   # Tests whether the specified window is maximized.
+  #
+  def_api 'IsZoomed', 'L', 'L', :alias => :maximized?
 
-  def_api 'IsIconic', 'L', 'L', :alias => :minimized?
   # Tests whether the specified window is maximized.
+  #
+  def_api 'IsIconic', 'L', 'L', :alias => :minimized?
 
+  # 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.
+  #
   def_api 'IsChild', 'LL', 'L'
-  # 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.
 
-  def_api 'FindWindow', 'PP', 'L', :zeronil => true
-  # Retrieves a handle to the top-level window whose class name and window name match the specified strings.
+  # Retrieves a handle to the top-level window whose class and window name match the specified strings.
   #   This function does not search child windows. This function does not perform a case-sensitive search.
-  # class_name (P) - String that specifies (window) class name or a class atom created by a previous call to the RegisterClass(Ex) function.
-  #   The atom must be in the low-order word of class_name; the high-order word must be zero.
-  #   The class name can be any name registered with RegisterClass(Ex), or any of the predefined control-class names.
-  #   If this parameter is nil, it finds any window whose title matches the win_title parameter.
-  # win_name (P) - String that specifies the window name (title). If this parameter is nil, all window names match.
+  # class_name (P) - String that specifies (window) class name OR class atom created by a previous
+  #   call to the RegisterClass(Ex) function. The atom must be in the low-order word of class_name;
+  #   the high-order word must be zero. The class name can be any name registered with RegisterClass(Ex),
+  #   or any of the predefined control-class names. If this parameter is nil, it finds any window whose
+  #   title matches the win_title parameter.
+  # win_name (P) - String that specifies the window name (title). If nil, all names match.
   # returns (L) found window handle or NIL if nothing found
+  #
+  def_api 'FindWindow', 'PP', 'L', :zeronil => true
 
-  def_api 'FindWindowW', 'PP', 'L', :zeronil => true
   # Unicode version of find_window (strings must be encoded as utf-16LE AND terminate with "\x00\x00")
+  #
+  def_api 'FindWindowW', 'PP', 'L', :zeronil => true
 
-  def_api 'FindWindowEx', 'LLPP', 'L', :zeronil => true
-  # Retrieves a handle to a CHILD 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. This function does NOT perform a case-sensitive search.
+  # Retrieves a handle to a CHILD 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.
+  #   This function does NOT perform a case-sensitive search.
   # parent (L) - Handle to the parent window whose child windows are to be searched.
   #   If nil, the function uses the desktop window as the parent window.
   #   The function searches among windows that are child windows of the desktop.
-  # after_child (L) - Handle to a child window. The search begins with the NEXT child window in the Z order.
+  # after_child (L) - Handle to a child window. Search begins with the NEXT child window in the Z order.
   #   The child window must be a direct child window of parent, not just a descendant window.
   #   If after_child is nil, the search begins with the first child window of parent.
-  # win_class (P), win_title (P) - Strings that specify window class and name(title). If parameter is nil, anything matches.
+  # win_class (P), win_title (P) - Strings that specify window class and name(title). If nil, anything matches.
   # Returns (L) - found child window (control) handle or NIL if nothing found
+  #
+  def_api 'FindWindowEx', 'LLPP', 'L', :zeronil => true
 
-  def_api 'GetWindowText', 'LPI', 'L', &return_string_proc
-  # Returns the text of the specified window's title bar (if it has one). If the specified window is a control, the text of the control is copied.
-  #   However, GetWindowText cannot retrieve the text of a control in another application.
-  # API improved to require only win_handle and return rstripped string
+  # Returns the text of the specified window's title bar (if it has one). If the specified window is
+  #   a control, the text of the control is copied. However, GetWindowText cannot retrieve the text of
+  #   a control in another application.
+  # API improved to require only win_handle and return rstripped text
   # win_handle (L) - Handle to the window and, indirectly, the class to which the window belongs.
-  # buffer (P) - Pointer to the buffer that will receive the text. If the string is as long or longer than the buffer,
-  #   the string is truncated and terminated with a NULL character.
-  # count (L) Specifies the maximum number of characters to copy to the buffer, including the NULL character. If the text exceeds this limit, it is truncated.
+  # buffer (P) - Pointer to the buffer that will receive the text. If the string is as long or longer
+  #   than the buffer, the string is truncated and terminated with a NULL character.
+  # count (L) Specifies the maximum number of characters to copy to the buffer, including the NULL character.
+  #   If the text exceeds this limit, it is truncated.
   # Returns (L) length, in characters, of the copied string, not including the terminating NULL character.
-  #   If the window has no title bar or text, if the title bar is empty, or if the window or control handle is invalid, the return value is zero.
+  #   If the window has no title bar or text, if the title bar is empty, or if the window or control handle
+  #   is invalid, the return value is zero.
   # To get extended error information, call GetLastError.
+  #
   # Remarks: This function CANNOT retrieve the text of an edit control in ANOTHER app.
-  #   If the target window is owned by the current process, GetWindowText causes a WM_GETTEXT message to be sent to the specified window or control.
-  #   If the target window is owned by another process and has a caption, GetWindowText retrieves the window caption text. If the window does not have a caption,
-  #   the return value is a null string. This allows to call GetWindowText without becoming unresponsive if the target window owner process is not responding.
-  #   However, if the unresponsive target window belongs to the calling app, GetWindowText will cause the calling app to become unresponsive.
-  #   To retrieve the text of a control in another process, send a WM_GETTEXT message directly instead of calling GetWindowText.
+  #   If the target window is owned by the current process, GetWindowText causes a WM_GETTEXT message to
+  #   be sent to the specified window or control. If the target window is owned by another process and has
+  #   a caption, GetWindowText retrieves the window caption text. If the window does not have a caption,
+  #   the return value is a null string. This allows to call GetWindowText without becoming unresponsive
+  #   if the target window owner process is not responding. However, if the unresponsive target window
+  #   belongs to the calling app, GetWindowText will cause the calling app to become unresponsive.
+  #   To retrieve the text of a control in another process, send a WM_GETTEXT message directly instead
+  #   of calling GetWindowText.
+  #
+  def_api 'GetWindowText', 'LPI', 'L', &return_string
 
-  def_api 'GetWindowTextW', 'LPI', 'L', &return_utf_string_proc
   # Unicode version of get_window_text (returns rstripped utf-8 string)
   # API improved to require only win_handle and return rstripped string
+  #
+  def_api 'GetWindowTextW', 'LPI', 'L', &return_string('utf-8')
 
-  def_api 'GetClassName', 'LPI', 'I', &return_string_proc
   # Retrieves the name of the class to which the specified window belongs.
   # API improved to require only win_handle and return rstripped  string
   # win_handle (L) - Handle to the window and, indirectly, the class to which the window belongs.
@@ -123,56 +113,72 @@ module WinGui
   #   The class name string is truncated if it is longer than the buffer and is always null-terminated.
   # Returns (I) - number of TCHAR copied to the specified buffer, if the function succeeds.
   #   Returns zero if function fails. To get extended error information, call GetLastError.
+  #
+  def_api 'GetClassName', 'LPI', 'I', &return_string
 
-  def_api 'GetClassNameW', 'LPI', 'I', &return_utf_string_proc
   # Unicode version of get_class_name (returns rstripped utf-8 string)
   # API improved to require only win_handle and return rstripped string
+  #
+  def_api 'GetClassNameW', 'LPI', 'I', &return_string('utf-8')
 
+  # Retrieves the identifier of the thread that created the specified window and, optionally, the identifier
+  #   of the process that created the window.
+  # API improved to accept window handle as a single arg and return a pair of [thread, process] ids
+  # handle (L) - Handle to the window.
+  # process (P) - A POINTER to a (Long) variable that receives the process identifier.
+  # Returns (L) - Identifier of the thread that created the window.
+  #
   def_api 'GetWindowThreadProcessId', 'LP', 'L' do |api, *args|
-    # Retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the process that created the window.
-    # API improved to accept window handle as a single arg and return a pair of [thread, process] ids
-    # handle (L) - Handle to the window.
-    # process (P) - A POINTER to a (Long) variable that receives the process identifier. If it is nil, nothing happens.
-    #   Otherwise, GetWindowThreadProcessId copies the identifier of the process to the variable.
-    # Returns (L) - Identifier of the thread that created the window.
     raise 'Invalid args count' unless args.size == api.prototype.size-1
     thread = api.call(args.first, process = [1].pack('L'))
     [thread] + process.unpack('L')
   end
 
-  def_api 'ShowWindow', 'LI', 'I', :boolean => true
+  # Shows and hides windows.
   # handle (L) - Handle to the window.
-  # cmd (I) - Specifies how the window is to be shown. This parameter is ignored the first time an application calls ShowWindow,
-  #   if the program that launched the application provides a STARTUPINFO structure. Otherwise, the first time ShowWindow is called,
-  #   the value should be the value obtained by the WinMain function in its nCmdShow parameter. In subsequent calls, cmd may be:
-  #        SW_HIDE          - Hides the window and activates another window.
-  #        SW_MAXIMIZE      - Maximizes the specified window.
-  #        SW_MINIMIZE      - Minimizes the specified window and activates the next top-level window in the Z order.
-  #        SW_SHOW          - Activates the window and displays it in its current size and position.
-  #        SW_SHOWMAXIMIZED - Activates the window and displays it as a maximized window.
-  #        SW_SHOWMINIMIZED - Activates the window and displays it as a minimized window.
-  #        SW_SHOWMINNOACTIVE Displays the window as a minimized window. This value is similar to SW_SHOWMINIMIZED, except the window is not activated.
-  #        SW_SHOWNA        - Displays the window in its current size and position. This value is similar to SW_SHOW, except the window is not activated.
-  #        SW_SHOWNOACTIVATE- Displays a window in its most recent size and position. This value is similar to SW_SHOWNORMAL, except the window is not actived.
-  #        SW_SHOWNORMAL    - Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position.
-  #                           An application should specify this flag when displaying the window for the first time.
-  #        SW_RESTORE       - Activates and displays the window. If the window is minimized or maximized, the system restores it to
-  #                           its original size and position. An application should specify this flag when restoring a minimized window.
-  #        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.
-  #        SW_FORCEMINIMIZE - Windows 2000/XP: Minimizes a window, even if the thread that owns the window is not responding.
-  #                           This flag should only be used when minimizing windows from a different thread.
+  # cmd (I) - Specifies how the window is to be shown. This parameter is ignored the first time an
+  #   application calls ShowWindow, if the program that launched the application provides a STARTUPINFO
+  #  structure. Otherwise, the first time ShowWindow is called, the value should be the value obtained
+  #  by the WinMain function in its nCmdShow parameter. In subsequent calls, cmd may be:
+  #    SW_HIDE          - Hides the window and activates another window.
+  #    SW_MAXIMIZE      - Maximizes the specified window.
+  #    SW_MINIMIZE      - Minimizes the specified window, activates the next top-level window in the Z order.
+  #    SW_SHOW          - Activates the window and displays it in its current size and position.
+  #    SW_SHOWMAXIMIZED - Activates the window and displays it as a maximized window.
+  #    SW_SHOWMINIMIZED - Activates the window and displays it as a minimized window.
+  #    SW_SHOWMINNOACTIVE Displays the window as a minimized window. This value is similar to
+  #                       SW_SHOWMINIMIZED, except the window is not activated.
+  #    SW_SHOWNA        - Displays the window in its current size and position. This value is similar to
+  #                       SW_SHOW, except the window is not activated.
+  #    SW_SHOWNOACTIVATE- Displays a window in its most recent size and position. This value is similar to
+  #                       SW_SHOWNORMAL, except the window is not actived.
+  #    SW_SHOWNORMAL    - Activates and displays a window. If the window is minimized or maximized,
+  #                       the system restores it to its original size and position. An application should
+  #                       specify this flag when displaying the window for the first time.
+  #    SW_RESTORE       - Activates and displays the window. If the window is minimized or maximized,
+  #                       the system restores it to its original size and position. An application should
+  #                       specify this flag when restoring a minimized window.
+  #    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.
+  #    SW_FORCEMINIMIZE - Windows 2000/XP: Minimizes a window, even if the thread that owns the window
+  #                       is not responding. Only use this flag when minimizing windows from a different thread.
   # Returns (I) - True if the window was PREVIOUSLY visible, otherwise false
+  #
+  def_api 'ShowWindow', 'LI', 'I', :boolean => true
+
   def hide_window(handle)
     show_window(handle, SW_HIDE)
   end
 
+  # Retrieves the dimensions of the specified window bounding rectangle. Dimensions are given relative
+  #   to the upper-left corner of the screen.
+  # API improved to accept only window handle and return 4-member dimensions array (left, top, right, bottom)
+  # handle (L) - Handle to the window, rectangle - pointer to 4-long array for coordinates
+  #
+  # Remarks: As a convention for the RECT structure, the bottom-right coordinates of the returned rectangle
+  #   are exclusive. In other words, the pixel at (right, bottom) lies immediately outside the rectangle.
+  #
   def_api 'GetWindowRect', 'LP', 'I' do |api, *args|
-    # Retrieves the dimensions of the specified window bounding rectangle. Dimensions are given relative to the upper-left corner of the screen.
-    # API improved to accept only window handle and return 4-member dimensions array (left, top, right, bottom)
-    # handle (L) - Handle to the window, rectangle - pointer to 4-long array for coordinates
-    # Remarks: In conformance with conventions for the RECT structure, the bottom-right coordinates of the returned rectangle are exclusive.
-    # In other words, the pixel at (right, bottom) lies immediately outside the rectangle.
     raise 'Invalid args count' unless args.size == api.prototype.size-1
     rectangle = [0, 0, 0, 0].pack 'L*'
     api.call args.first, rectangle
@@ -183,31 +189,35 @@ module WinGui
   def_api 'PostMessage', 'LLLL', 'L'
   def_api 'SendMessage', 'LLLP', 'L'
   def_api 'GetDlgItem', 'LL', 'L'
-  def_api 'EnumWindows', 'KP', 'L', &return_enum_proc
-  # 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.
+
+  # 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.
   # API improved to accept blocks (instead of callback objects) and message as a single arg
-  # callback [K] - Pointer to an application-defined callback function. For more information, see EnumWindowsProc.
+  # callback [K] - Pointer to an application-defined callback function (see EnumWindowsProc).
   # message [P] - Specifies an application-defined value(message) to be passed to the callback function.
-  # Returns: Nonzero if the function succeeds, zero if the function fails. For extended error info, call GetLastError.
-  #   If callback returns zero, the return value is also zero. In this case, the callback function should call
-  #   SetLastError to obtain a meaningful error code to be returned to the caller of EnumWindows.
-  # Remarks: The EnumWindows function does not enumerate child windows, with the exception of a few top-level windows
-  # owned by the system that have the WS_CHILD style. This function is more reliable than calling the GetWindow function
-  # 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.
-
-  def_api 'EnumChildWindows', 'LKP', 'L', &return_enum_proc
+  # Returns: Nonzero if the function succeeds, zero if the function fails (GetLastError for more error info).
+  #   If callback returns zero, the return value is also zero. In this case, the callback function should
+  #   call SetLastError to obtain a meaningful error code to be returned to the caller of EnumWindows.
+  #
+  # Remarks: The EnumWindows function does not enumerate child windows, with the exception of a few top-level
+  #   windows owned by the system that have the WS_CHILD style. This function is more reliable than calling
+  #   the GetWindow function 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.
+  #
+  def_api 'EnumWindows', 'KP', 'L', &return_enum
+
+  # Enumerates child windows to a given window.
   # parent (L) - Handle to the parent window whose child windows are to be enumerated.
   #   If it is nil, this function is equivalent to EnumWindows. Windows 95/98/Me: parent cannot be NULL.
-  # API improved to accept blocks (instead of callback objects) and two args: parent handle and message
-  # callback (K) - Pointer to an application-defined callback function. For more information, see EnumChildProc.
-  # message (P) - Specifies an application-defined value to be passed to the callback function.
-  # Returns (I) -  Not used (?!)
+  # API improved to accept blocks (instead of callback objects) and two args: parent handle and message.
+  # callback (K) - Pointer to an application-defined callback function (see EnumChildProc).
+  # message (P) - Specifies an application-defined value(message) to be passed to the callback function.
+  # Returns (L) -  Not used (?!)
   #   If a child window has created child windows of its own, EnumChildWindows enumerates those windows as well.
   #   A child window that is moved or repositioned in the Z order during the enumeration process will be properly enumerated.
   #   The function does not enumerate a child window that is destroyed before being enumerated or that is created during the enumeration process.
+  def_api 'EnumChildWindows', 'LKP', 'L', &return_enum
 
   def_api 'GetForegroundWindow', 'V', 'L'
   def_api 'GetActiveWindow', 'V', 'L'

data/spec/win_gui/def_api_spec.rb

@@ -1,6 +1,6 @@
 require File.join(File.dirname(__FILE__), "..", "spec_helper" )
 
-module GuiTest 
+module GuiTest
 
 #  def enum_callback
 #    @enum_callback ||= WinGui.callback('LP', 'I'){|handle, message| true }
@@ -36,6 +36,15 @@ module GuiTest
         expect { find_window_w(nil, nil) }.to_not raise_error 'Invalid args count'
       end
 
+      it 'overrides standard dll name with :dll option' do
+
+        WinGui.def_api 'GetComputerName', ['P', 'P'], 'I', :dll=> 'kernel32'
+        sys_name = `echo %COMPUTERNAME%`.strip
+        name = " " * 128
+        get_computer_name(name, "128")
+        name.unpack("A*").first.should == sys_name
+      end
+
       it 'overrides standard name for defined method with :rename option' do
         WinGui.def_api 'FindWindowW', 'PP', 'L', :rename=> 'my_own_find'
         expect {find_window_w(nil, nil)}.to raise_error
@@ -155,6 +164,26 @@ module GuiTest
       end
     end
 
+    context 'using DLL other than default user32 with :dll option' do
+      before(:each) do
+        hide_method :get_computer_name # hide original method if it is defined
+        WinGui.def_api 'GetComputerName', ['P', 'P'], 'I', :dll=> 'kernel32'
+      end
+      after(:each) { restore_method :get_computer_name } # restore original method if it was hidden
+
+      it 'defines new instance method with appropriate name' do
+        respond_to?(:get_computer_name).should be_true
+      end
+
+      it 'returns expected result' do
+        WinGui.def_api 'GetComputerName', ['P', 'P'], 'I', :dll=> 'kernel32'
+        hostname = `hostname`.strip.upcase
+        name = " " * 128
+        get_computer_name(name, "128")
+        name.unpack("A*").first.should == hostname
+      end
+    end
+
     context 'trying to define an invalid API function' do
       it 'raises error when trying to define function with a wrong function name' do
         expect { WinGui.def_api 'FindWindowImpossible', 'PP', 'L' }.
@@ -162,7 +191,7 @@ module GuiTest
       end
     end
 
-    context 'defining API function using definition blocks' do
+    context 'defining API function using definition block' do
 
       it 'defines new instance method' do
         WinGui.def_api( 'FindWindowW', 'PP', 'L' ){|api, *args|}
@@ -188,7 +217,7 @@ module GuiTest
         end
         find_window_w(1, 2, 3)
         @args.should == [1, 2, 3]
-        @api.function_name.should == 'FindWindowW' # The name of the function passed to the constructor
+        @api.function_name.should == 'FindWindowW' # The name of the api function passed to the block
       end
 
       it ':rename option overrides standard name for defined method' do
@@ -230,12 +259,14 @@ module GuiTest
 
       it 'created callback object can be used as a valid arg of API function expecting callback' do
         WinGui.def_api 'EnumWindows', 'KP', 'L'
-        @enum_callback ||= WinGui.callback('LP', 'I'){|handle, message| true }
-        expect { enum_windows(@enum_callback, 'Message') }.to_not raise_error
+        @callback = WinGui.callback('LP', 'I'){|handle, message| true }
+        expect { enum_windows(@callback, 'Message') }.to_not raise_error
       end
 
-      it 'defined API functions expecting callback recognize/accept blocks' do
-        pending ' API is not exactly clear atm (what about prototype?)(.with_callback method?)'
+      it 'defined API functions expecting callback convert given block into callback' do
+        pending ' What about prototype!? API is not exactly clear atm (.with_callback method?)'
+        WinGui.def_api 'EnumWindows', 'KP', 'L'
+        expect { enum_windows('Message'){|handle, message| true } }.to_not raise_error
       end
     end
   end

data/spec/win_gui/win_gui_spec.rb

@@ -4,9 +4,6 @@ module GuiTest
   describe WinGui, ' contains a set of pre-defined GUI functions' do
     describe '#window?' do
       spec{ use{ window?(handle = 0) }}
-      # Tests whether the specified window handle identifies an existing window.
-      #   A thread should not use IsWindow for a window that it did not create because the window could be destroyed after this 
-      #   function was called. Further, because window handles are recycled the handle could even point to a different window. 
 
       it 'returns true if window exists' do
         test_app do |app|
@@ -28,8 +25,6 @@ module GuiTest
     describe '#window_visible?' do
       spec{ use{ window_visible?(handle = any_handle) }}
       spec{ use{ visible?(handle = any_handle) }}
-      # Tests if the specified window, its parent window, its parent's parent window, and so forth, have the WS_VISIBLE style.
-      # Because the return value specifies whether the window has the WS_VISIBLE style, it may be true even if the window is totally obscured by other windows. 
 
       it 'returns true if window is visible' do
         test_app do |app|

data/win_gui.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{win_gui}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["arvicco"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: win_gui
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - arvicco