win 0.1.27 → 0.3.1

data/lib/win/gui/window.rb

@@ -1,679 +1,679 @@
-require 'win/library'
-require 'win/gui/message' # needed because some convenience methods work via PostMessage
-
-module Win
-  module GUI
-    # Contains constants and Win32API functions related to window manipulation
-    #
-    module Window
-      include Win::Library
-
-      # ShowWindow constants:
-
-      # Hides the window and activates another window.
-      SW_HIDE           = 0
-      # Same as SW_SHOWNORMAL
-      SW_NORMAL         = 1
-      # 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_SHOWNORMAL     = 1
-      # Activates the window and displays it as a minimized window.
-      SW_SHOWMINIMIZED  = 2
-      # Activates the window and displays it as a maximized window.
-      SW_SHOWMAXIMIZED  = 3
-      # 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
-      # Activates the window and displays it in its current size and position.
-      SW_SHOW           = 5
-      # Minimizes the specified window, activates the next top-level window in the Z order.
-      SW_MINIMIZE       = 6
-      # Displays the window as a minimized window. Similar to SW_SHOWMINIMIZED, except the window is not activated.
-      SW_SHOWMINNOACTIVE= 7
-      # Displays the window in its current size and position. Similar to SW_SHOW, except the window is not activated.
-      SW_SHOWNA         = 8
-      # 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_RESTORE        = 9
-      # 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_SHOWDEFAULT    = 10
-      # 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.
-      SW_FORCEMINIMIZE  = 11
-
-      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.
-        # If runtime block is given it is called after the end of default callback (handle Array is still being
-        # collected and returned by the method). If Enum... function call fails, method returns nil, otherwise
-        # an Array of all window handles passed into callback.
-        #
-        def return_enum #:nodoc:
-          lambda do |api, *args, &block|
-            args.push 0 if args.size == api.prototype.size - 2 # If value is missing, it defaults to 0
-            handles = []
-
-            # Insert callback proc into appropriate place of args Array
-            args[api.prototype.find_index(:EnumWindowsProc), 0] =
-                    proc do |handle, message|
-                      handles << handle
-                      block ? block[handle, message] : true
-                    end
-            handles if api.call *args
-          end
-        end
-
-        # Helper method that creates def_block returning (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 )  #:nodoc:
-          lambda do |api, *args|
-            namespace.enforce_count( args, api.prototype, -2)
-            buffer = FFI::MemoryPointer.new :char, 1024
-            args += [buffer, buffer.size]
-            num_chars = api.call(*args)
-            return nil if num_chars == 0
-            if encode
-              string = buffer.get_bytes(0, num_chars*2)
-              string = string.force_encoding('utf-16LE').encode(encode)
-            else
-              string = buffer.get_bytes(0, num_chars)
-            end
-            string.rstrip
-          end
-        end
-
-        private :return_enum, :return_string
-      end
-
-      # Windows GUI API definitions:
-
-      ##
-      # The IsWindow function determines whether the specified window handle identifies an existing window.
-      # [*Syntax*] BOOL IsWindow( HWND hWnd );
-      #
-      # hWnd:: [in] Handle to the window to test.
-      #
-      # *Returns*:: If the window handle identifies an existing window, the return value is (*true*).
-      #             If the window handle does not identify an existing window, the return value is (*false*).
-      # ---
-      # *remarks*:
-      # 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.
-      #
-      # :call-seq:
-      # window?( win_handle )
-      #
-      function :IsWindow, [:HWND], :int, boolean: true
-
-      ##
-      # The IsWindowVisible function retrieves the visibility state of the specified window.
-      # [*Syntax*] BOOL IsWindowVisible( HWND hWnd );
-      #
-      # hWnd:: [in] Handle to the window to test.
-      #
-      # *Returns*:: If the specified window, its parent window, its parent's parent window, and so forth,
-      #             have the WS_VISIBLE style set, return value is *true*. 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.
-      # ---
-      # *Remarks*:
-      # - The visibility state of a window is indicated by the WS_VISIBLE style bit. When WS_VISIBLE is set,
-      #   the window is displayed and subsequent drawing into it is displayed as long as the window has the
-      #   WS_VISIBLE style.
-      # - Any drawing to a window with the WS_VISIBLE style will not be displayed if the window is obscured
-      #   by other windows or is clipped by its parent window.
-      #
-      # :call-seq:
-      #   [window_]visible?( win_handle )
-      #
-      function :IsWindowVisible, [:HWND], :int, boolean: true, aliases: :visible?
-
-      ##
-      # Tests whether the specified window is maximized.
-      # [*Syntax*] BOOL IsZoomed( HWND hWnd );
-      #
-      # hWnd:: [in] Handle to the window to test.
-      #
-      # *Returns*:: If the window is zoomed (maximized), the return value is *true*.
-      #             If the window is not zoomed (maximized), the return value is *false*.
-      #
-      # :call-seq:
-      #   zoomed?( win_handle ), maximized?( win_handle )
-      #
-      function :IsZoomed, [:HWND], :int, boolean: true, aliases: :maximized?
-
-      ##
-      # Tests whether the specified window is minimized.
-      # [*Syntax*] BOOL IsIconic( HWND hWnd );
-      #
-      # hWnd:: [in] Handle to the window to test.
-      #
-      # *Returns*:: If the window is iconic (minimized), the return value is *true*.
-      #             If the window is not iconic (minimized), the return value is *false*.
-      #
-      # :call-seq:
-      #   iconic?( win_handle ), minimized?( win_handle )
-      #
-      function :IsIconic, [:HWND], :int, boolean: true, aliases: :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.
-      #
-      # [*Syntax*] BOOL IsChild( HWND hWndParent, HWND hWnd);
-      #
-      # hWndParent:: [in] Handle to the parent window.
-      # hWnd:: [in] Handle to the window to be tested.
-      #
-      # *Returns*::  If the window is a child or descendant window of the specified parent window,
-      #              the return value is *true*. If the window is not a child or descendant window of
-      #              the specified parent window, the return value is *false*.
-      # :call-seq:
-      #   child?( win_handle )
-      #
-      function :IsChild, [:HWND, :HWND], :int, boolean: true
-
-      ##
-      # The FindWindow function retrieves a handle to the top-level window whose class name and window name
-      # match the specified strings. This function does not search child windows. This function does not
-      # perform a case-sensitive search.
-      #
-      # To search child windows, beginning with a specified child window, use the FindWindowEx function.
-      #
-      # [*Syntax*] HWND FindWindow( LPCTSTR lpClassName, LPCTSTR lpWindowName );
-      #
-      # lpClassName:: [in] Pointer to a null-terminated string that specifies the class name or a class
-      #               atom created by a previous call to the RegisterClass or RegisterClassEx function.
-      #               The atom must be in the low-order word of lpClassName; the high-order word must be zero.
-      #               If lpClassName points to a string, it specifies the window class name. The class name
-      #               can be any name registered with RegisterClass or RegisterClassEx, or any of the
-      #               predefined control-class names.
-      #               If lpClassName is NULL, it finds any window whose title matches the lpWindowName parameter.
-      # lpWindowName:: [in] Pointer to a null-terminated string that specifies the window name (the window's title).
-      #                If this parameter is NULL, all window names match.
-      # *Returns*:: If the function succeeds, the return value is a handle to the window that has the specified
-      #             class name and window name. If the function fails, the return value is *nil*.
-      #             To get extended error information, call GetLastError.
-      # ---
-      # *Remarks*:
-      # - If the lpWindowName parameter is not NULL, FindWindow calls the GetWindowText function to retrieve
-      #   the window name for comparison. For a description of a potential problem that can arise, see the
-      #   Remarks for GetWindowText.
-      # - To check if the Microsoft IntelliType version 1.x software is running, call FindWindow as follows:
-      #      find_window("MSITPro::EventQueue", nil)
-      # - To check if the IntelliType version 2.0 software is running, call FindWindow as follows:
-      #      find_window("Type32_Main_Window", nil)
-      #   If the IntelliType software is running, it sends WM_APPCOMMAND messages to the application.
-      #   Otherwise the application must install a hook to receive WM_APPCOMMAND messages.
-      #
-      # :call-seq:
-      #   win_handle = find_window( class_name, win_name )
-      #
-      function :FindWindow, [:pointer, :pointer], :HWND, zeronil: true
-
-      ##
-      # Unicode version of FindWindow (strings must be encoded as utf-16LE AND terminate with "\x00\x00")
-      #
-      # :call-seq:
-      #   win_handle = find_window_w( class_name, win_name )
-      #
-      function :FindWindowW, [:pointer, :pointer], :HWND, zeronil: true
-
-      ##
-      #  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.
-      #  This function does not perform a case-sensitive search.
-      #
-      #  [*Syntax*] HWND FindWindowEx( HWND hwndParent, HWND hwndChildAfter, LPCTSTR lpszClass, LPCTSTR lpszWindow );
-      #
-      #  hwndParent:: [in] Handle to the parent window whose child windows are to be searched.
-      #               If hwndParent is NULL, the function uses the desktop window as the parent window.
-      #               The function searches among windows that are child windows of the desktop.
-      #               Microsoft Windows 2000 and Windows XP: If hwndParent is HWND_MESSAGE, the function
-      #               searches all message-only windows.
-      #  hwndChildAfter:: [in] Handle to a child window. The search begins with the next child window in the Z order.
-      #                   The child window must be a direct child window of hwndParent, not just a descendant window.
-      #                   If hwndChildAfter is NULL, the search begins with the first child window of hwndParent.
-      #                   Note that if both hwndParent and hwndChildAfter are NULL, the function searches all
-      #                   top-level and message-only windows.
-      #  lpszClass:: [in] Pointer to a null-terminated string that specifies the class name or a class atom created
-      #              by a previous call to the RegisterClass or RegisterClassEx function. The atom must be placed in
-      #              the low-order word of lpszClass; the high-order word must be zero.
-      #              If lpszClass is a string, it specifies the window class name. The class name can be any name
-      #              registered with RegisterClass or RegisterClassEx, or any of the predefined control-class names,
-      #              or it can be MAKEINTATOM(0x800). In this latter case, 0x8000 is the atom for a menu class. For
-      #              more information, see the Remarks section of this topic.
-      #  lpszWindow:: [in] Pointer to a null-terminated string that specifies the window name (the window's title).
-      #               If this parameter is NULL, all window names match.
-      #
-      #  *Returns*:: If the function succeeds, the return value is a handle to the window that has the specified
-      #              class and window names. If the function fails, the return value is NULL. For extended error info,
-      #              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.
-      #  - 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
-      #    a context menu is being displayed that the application created.
-      #
-      # :call-seq:
-      #   win_handle = find_window_ex( win_handle, after_child, class_name, win_name )
-      #
-      function :FindWindowEx, [:HWND, :HWND, :pointer, :pointer], :HWND, zeronil: true
-
-      ##
-      # GetWindowText 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.
-      #
-      # [*Syntax*] int GetWindowText( HWND hWnd, LPTSTR lpString, int nMaxCount );
-      #
-      # *Original* Parameters:
-      # hWnd:: Handle to the window and, indirectly, the class to which the window belongs.
-      # lpString:: Long Pointer to the buffer that is to receive the text string.
-      # nMaxCount:: Specifies the length, in TCHAR, of the buffer pointed to by the text parameter.
-      #             The class name string is truncated if it is longer than the buffer and is always null-terminated.
-      # *Original* Return:: Length, in characters, of the copied string, not including the terminating null
-      #                     character (if success). Zero indicates that the window has no title bar or text,
-      #                     if the title bar is empty, or if the window or control handle is invalid.
-      #                     For extended error information, call GetLastError.
-      # ---
-      # Enhanced API requires only win_handle and returns rstripped text
-      #
-      # *Enhanced* Parameters:
-      # win_handle:: Handle to the window and, indirectly, the class to which the window belongs.
-      # *Returns*:: Window title bar text or nil. 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 *NIL*.
-      #             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.
-      #
-      #:call-seq:
-      #   text = [get_]window_text( win_handle )
-      #
-      function :GetWindowText, [:HWND, :pointer, :int], :int, &return_string
-
-      ##
-      # GetWindowTextW is a Unicode version of GetWindowText (returns rstripped utf-8 string)
-      # API improved to require only win_handle and return rstripped string
-      #
-      #:call-seq:
-      #   text = [get_]window_text_w( win_handle )
-      #
-      function :GetWindowTextW, [:HWND, :pointer, :int], :int, &return_string('utf-8')
-
-      ##
-      # GetClassName retrieves the name of the class to which the specified window belongs.
-      # [*Syntax*] int GetClassName( HWND hWnd, LPTSTR lpClassName, int nMaxCount );
-      # *Original* Parameters:
-      # hWnd:: [in] Handle to the window and, indirectly, the class to which the window belongs.
-      # lpClassName:: [out] Pointer to the buffer that is to receive the class name string.
-      # nMaxCount:: [in] Specifies the length, in TCHAR, of the buffer pointed to by the lpClassName parameter.
-      #             The class name string is truncated if it is longer than the buffer and is always null-terminated.
-      # *Original* Return:: Length, in characters, of the copied string, not including the terminating null character,
-      #                     indicates success. Zero indicates that the window has no title bar or text, if the title
-      #                     bar is empty, or if the window or control handle is invalid.
-      # ---
-      # API improved to require only win_handle and return rstripped string
-      #
-      # *Enhanced* Parameters:
-      # win_handle:: Handle to the window and, indirectly, the class to which the window belongs.
-      # *Returns*:: Name of the class or *nil* if function fails. For extended error information, call GetLastError.
-      #
-      #:call-seq:
-      #   text = [get_]class_name( win_handle )
-      #
-      function :GetClassName, [:HWND, :pointer, :int], :int, &return_string
-
-      ##
-      # GetClassNameW is a Unicode version of GetClassName (returns rstripped utf-8 string)
-      # API improved to require only win_handle and return rstripped string
-      #
-      #:call-seq:
-      #   text = [get_]class_name_w( win_handle )
-      #
-      function :GetClassNameW, [:HWND, :pointer, :int], :int, &return_string('utf-8')
-
-      ##
-      # ShowWindow shows and hides windows (sets the specified window's show state).
-      #
-      # [*Syntax*] BOOL ShowWindow( HWND hWnd, int nCmdShow);
-      #
-      # hWnd:: Handle to the window.
-      # nCmdShow:: 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, SW_MAXIMIZE, SW_MINIMIZE, SW_SHOW, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, SW_SHOWMINNOACTIVE,
-      #            SW_SHOWNA, SW_SHOWNOACTIVATE, SW_SHOWNORMAL, SW_RESTORE, SW_SHOWDEFAULT, SW_FORCEMINIMIZE
-      #
-      # *Returns*:: *True* if the window was PREVIOUSLY visible, otherwise *false*
-      #
-      #:call-seq:
-      #   was_visible = show_window( win_handle, cmd )
-      #
-      function :ShowWindow, [:HWND, :int], :int, boolean: true,
-               &->(api, handle, cmd=SW_SHOW) { api.call handle, cmd }
-
-      ##
-      # The CloseWindow function minimizes (but does not destroy) the specified window.
-      #
-      # [*Syntax*]: BOOL CloseWindow( HWND hWnd );
-      #
-      # hWnd:: [in] Handle to the window to be minimized.
-      #
-      # *Returns*:: If the function succeeds, the return value is nonzero (*true* in snake_case method). If the function
-      #             fails, the return value is zero (*false). To get extended error information, call GetLastError.
-      # ---
-      # *Remarks*:
-      # To destroy a window, an application must use the DestroyWindow function.
-      #
-      function :CloseWindow, [:HWND], :int, boolean: true
-
-      ##
-      # DestroyWindow function destroys the specified window. The function sends WM_DESTROY and WM_NCDESTROY messages
-      # to the window to deactivate it and remove the keyboard focus from it. The function also destroys the window's
-      # menu, flushes the thread message queue, destroys timers, removes clipboard ownership, and breaks the clipboard
-      # viewer chain (if the window is at the top of the viewer chain).
-      #
-      # If the specified window is a parent or owner window, DestroyWindow automatically destroys the associated child
-      # or owned windows when it destroys the parent or owner window. The function first destroys child or owned
-      # windows, and then it destroys the parent or owner window.
-      #
-      # DestroyWindow also destroys modeless dialog boxes created by the CreateDialog function.
-      #
-      # [*Syntax*]: BOOL DestroyWindow( HWND hWnd );
-      #
-      # hWnd:: [in] Handle to the window to be destroyed.
-      #
-      # *Returns*:: If the function succeeds, the return value is nonzero (snake_case method: *true*). If the function
-      #             fails, the return value is zero (*false*). To get extended error information, call GetLastError.
-      # ---
-      # *Remarks*:
-      # A thread <b>cannot use DestroyWindow to destroy a window created by a different thread.</b> Use a convenience
-      # method destroy_unowned_window instead (it relies on 
-      # If the window being destroyed is a child window that does not have the WS_EX_NOPARENTNOTIFY style, a
-      # WM_PARENTNOTIFY message is sent to the parent.
-      #
-      function :DestroyWindow, [:HWND], :int, boolean: true
-
-      ##
-      # GetWindowThreadProcessId retrieves the identifier of the thread that created the specified window
-      # and, optionally, the identifier of the process that created the window.
-      #
-      # [*Syntax*] DWORD GetWindowThreadProcessId( HWND hWnd, LPDWORD lpdwProcessId );
-      #
-      # *Original* Parameters:
-      # hWnd:: [in] Handle to the window.
-      # lpdwProcessId:: [out] Pointer to a variable that receives the process identifier. If this parameter
-      #                 is not NULL, GetWindowThreadProcessId copies the identifier of the process to the
-      #                 variable; otherwise, it does not.
-      # *Original* Return:: The identifier of the thread that created the window.
-      # ---
-      # API improved to accept window handle as a single arg and return a pair of [thread, process] ids
-      #
-      # *New* Parameters:
-      # handle:: Handle to the window.
-      # *Returns*: Pair of identifiers of the thread and process_id that created the window.
-      #
-      #:call-seq:
-      #   thread, process_id = [get_]window_tread_process_id( win_handle )
-      #
-      function :GetWindowThreadProcessId, [:HWND, :pointer], :long,
-               &->(api, handle) {
-               process = FFI::MemoryPointer.new(:long).write_long(1)
-               thread = api.call(handle, process)
-               thread == 0 ? [nil, nil] : [thread, process.read_long()] }
-      # weird lambda literal instead of normal block is needed because current version of RDoc
-      # goes crazy if block is attached to meta-definition
-
-      ##
-      # GetWindowRect retrieves the dimensions of the specified window bounding rectangle.
-      # Dimensions are given relative to the upper-left corner of the screen.
-      #
-      # [*Syntax*] BOOL GetWindowRect( HWND hWnd, LPRECT lpRect );
-      #
-      # *Original* Parameters:
-      # hWnd::  [in] Handle to the window.
-      # lpRect:: [out] Pointer to a structure that receives the screen coordinates of the upper-left and
-      #          lower-right corners of the window.
-      # *Original* Return:: Nonzero indicates success. Zero indicates failure. For error info, call GetLastError.
-      # ---
-      # API improved to accept only window handle and return 4-member dimensions array (left, top, right, bottom)
-      #
-      # *New* Parameters:
-      # win_handle:: Handle to the window
-      # *Returns*:: Array(left, top, right, bottom) - rectangle dimensions
-      # ---
-      # *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.
-      #
-      #:call-seq:
-      #   rect = [get_]window_rect( win_handle )
-      #
-      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
-      # as a result of a call to the EnumWindows, EnumChildWindows or EnumDesktopWindows function.
-      #
-      # [*Syntax*] BOOL CALLBACK EnumWindowsProc( HWND hwnd, LPARAM lParam );
-      #
-      # hWnd:: [in] Handle to a top-level window.
-      # lParam:: [in] Specifies the application-defined value given in EnumWindows or EnumDesktopWindows.
-      # *Return* *Value*:: To continue enumeration, the callback function must return TRUE;
-      #                    to stop enumeration, it must return FALSE.
-      # ---
-      # Remarks:
-      # - An application must register this callback function by passing its address to EnumWindows,
-      #   EnumChildWindows or EnumDesktopWindows.
-      # - You must ensure that the callback function sets SetLastError if it fails.
-      #
-      # :call-seq:
-      #  EnumWindowsProc callback block: {|win_handle, value| your callback code }
-      #
-      callback :EnumWindowsProc, [:HWND, :long], :bool
-
-      ##
-      # 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.
-      #
-      # [*Syntax*] BOOL EnumWindows( WNDENUMPROC lpEnumFunc, LPARAM lParam );
-      #
-      # *Original* Parameters:
-      # lpEnumFunc:: [in] Pointer to an application-defined callback function of EnumWindowsProc type.
-      # lParam:: [in] Specifies an application-defined value(message) to be passed to the callback function.
-      # *Original* Return:: Nonzero if the function succeeds, zero if the function fails. GetLastError for 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.
-      # ---
-      # API improved to accept blocks (instead of callback objects) with message as an optional argument
-      #
-      # *New* Parameters:
-      # message:: Specifies an application-defined value(message) to be passed to the callback block.
-      # attached block:: Serves as an application-defined callback function (see EnumWindowsProc).
-      # *Returns*:: *True* if the function succeeds, *false* if the function fails. GetLastError for error info.
-      #             If callback returned zero/false, the return value is also false. 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.
-      #
-      # :call-seq:
-      #   handles = enum_windows( [value=0] ) {|handle, value| your callback procedure }
-      #
-      function :EnumWindows, [:EnumWindowsProc, :long], :int8, &return_enum
-
-      ##
-      # EnumDesktopWindows Function enumerates all top-level windows associated with the specified desktop.
-      # It passes the handle to each window, in turn, to an application-defined callback function.
-      #
-      # [*Syntax*] BOOL WINAPI EnumDesktopWindows( __in_opt HDESK hDesktop, __in WNDENUMPROC lpfn,  __in LPARAM lParam);
-      #
-      # *Original* Parameters:
-      # hDesktop:: A handle to the desktop whose top-level windows are to be enumerated. This handle is returned by
-      #            the CreateDesktop, GetThreadDesktop, OpenDesktop, or OpenInputDesktop function, and must have the
-      #            DESKTOP_ENUMERATE access right. For more information, see Desktop Security and Access Rights.
-      #            If this parameter is NULL, the current desktop is used.
-      # lpfn:: A pointer to an application-defined EnumWindowsProc callback.
-      # lParam:: An application-defined value to be passed to the callback.
-      # *Return*:: If the function fails or is unable to perform the enumeration, the return value is zero.
-      #            To get extended error information, call GetLastError. You must ensure that the callback function
-      #            sets SetLastError if it fails.
-      # ---
-      # API enhanced to return *true*/*false* instead of nonzero/zero, and message value is optional (defaults to 0).
-      #
-      # *Enhanced*12 34 Parameters:
-      # desktop:: A handle to the desktop whose top-level windows are to be enumerated.
-      # value:: Specifies an application-defined value(message) to be passed to the callback (default 0).
-      # attached block:: Serves as an application-defined callback function (see EnumWindowsProc).
-      # ---
-      # *Remarks*:
-      # - Windows Server 2003 and Windows XP/2000: If there are no windows on the desktop, GetLastError returns
-      #   ERROR_INVALID_HANDLE.
-      # - The EnumDesktopWindows function repeatedly invokes the callback function until the last top-level window
-      #   is enumerated or the callback function returns FALSE.
-      # ---
-      # *Requirements*:
-      # Client Requires Windows Vista, Windows XP, or Windows 2000 Professional.
-      #
-      # :call-seq:
-      #   handles = enum_desktop_windows( desktop_handle, [value=0] ) {|handle, value| your callback procedure }
-      #
-      function :EnumDesktopWindows, [:ulong, :EnumWindowsProc, :long], :int8, &return_enum
-
-      ##
-      # The EnumChildWindows function enumerates the child windows that belong to the specified parent window by
-      # passing the handle of each child window, in turn, to an application-defined callback. EnumChildWindows
-      # continues until the last child window is enumerated or the callback function returns FALSE.
-      #
-      # [*Syntax*] BOOL EnumChildWindows( HWND hWndParent, WNDENUMPROC lpEnumFunc, LPARAM lParam );
-      #
-      # *Original* Parameters:
-      # hWndParent:: [in] Handle to the parent window whose child windows are to be enumerated. If this parameter
-      #              is NULL, this function is equivalent to EnumWindows.
-      #              Windows 95/98/Me: hWndParent cannot be NULL.
-      # lpEnumFunc:: [in] Pointer to an application-defined callback. For more information, see EnumChildProc.
-      # lParam:: [in] Specifies an application-defined value to be passed to the callback function.
-      #
-      # *Return*:: Not used!
-      # ---
-      # API improved to accept blocks (instead of callback objects) and parent handle (value is optional, default 0)
-      #
-      # *New* Parameters:
-      # parent:: Handle to the parent window whose child windows are to be enumerated.
-      # value:: Specifies an application-defined value(message) to be passed to the callback function.
-      # attached block:: Serves as an application-defined callback function (see EnumWindowsProc).
-      # ---
-      # *Remarks*:
-      # - 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.
-      #
-      #:call-seq:
-      #   handles = enum_child_windows( parent_handle, [value=0] ) {|handle, value| your callback procedure }
-      #
-      function :EnumChildWindows, [:HWND, :EnumWindowsProc, :long], :int8, &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);
-      #
-      # *Returns*:: 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()
-      #
-      function :GetForegroundWindow, [], :HWND, zeronil: true
-
-      ##
-      # The GetActiveWindow function retrieves the window handle to the active window attached to
-      # the calling thread's message queue.
-      #
-      # [*Syntax*]  HWND GetActiveWindow(VOID);
-      #
-      # *Returns*:: 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()
-      #
-      function :GetActiveWindow, [], :HWND, zeronil: true
-
-
-      # Convenience wrapper methods:
-
-      ##
-      # Hides the window and activates another window
-      #
-      def hide_window( win_handle )
-        show_window(win_handle, SW_HIDE)
-      end
-
-      ##
-      # Tests if given window handle points to foreground (topmost) window
-      #
-      def foreground?( win_handle )
-        win_handle == foreground_window
-      end
-
-      ##
-      # Shuts down the window <b>created by different thread</b> by posting WM_SYSCOMMAND, SC_CLOSE message to it.
-      # This closely emulates user clicking on X button of the target window. As it would be expected, this
-      # actually gives the target window chance to close gracefully (it may ask user to save data and stuff).
-      # I have not found so far how to REALLY destroy window in different thread without it asking user anything.
-      #
-      def shut_window( win_handle )
-        post_message(win_handle, Win::GUI::Message::WM_SYSCOMMAND, Win::GUI::Message::SC_CLOSE, nil)
-      end
-
-      ##
-      # Returns text associated with window by sending WM_GETTEXT message to it.
-      # ---
-      # *Remarks*: It is *different* from GetWindowText that returns only window title
-      #
-      def text( win_handle )
-        buffer = FFI::MemoryPointer.new :char, 1024
-        num_chars = send_message win_handle, Win::GUI::Message::WM_GETTEXT, buffer.size, buffer
-        num_chars == 0 ?  nil : buffer.get_bytes(0, num_chars)
-      end
-    end
-  end
-end
-
+require 'win/library'
+require 'win/gui/message' # needed because some convenience methods work via PostMessage
+
+module Win
+  module Gui
+    # Contains constants and Win32API functions related to window manipulation
+    #
+    module Window
+      include Win::Library
+
+      # ShowWindow constants:
+
+      # Hides the window and activates another window.
+      SW_HIDE           = 0
+      # Same as SW_SHOWNORMAL
+      SW_NORMAL         = 1
+      # 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_SHOWNORMAL     = 1
+      # Activates the window and displays it as a minimized window.
+      SW_SHOWMINIMIZED  = 2
+      # Activates the window and displays it as a maximized window.
+      SW_SHOWMAXIMIZED  = 3
+      # 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
+      # Activates the window and displays it in its current size and position.
+      SW_SHOW           = 5
+      # Minimizes the specified window, activates the next top-level window in the Z order.
+      SW_MINIMIZE       = 6
+      # Displays the window as a minimized window. Similar to SW_SHOWMINIMIZED, except the window is not activated.
+      SW_SHOWMINNOACTIVE= 7
+      # Displays the window in its current size and position. Similar to SW_SHOW, except the window is not activated.
+      SW_SHOWNA         = 8
+      # 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_RESTORE        = 9
+      # 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_SHOWDEFAULT    = 10
+      # 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.
+      SW_FORCEMINIMIZE  = 11
+
+      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.
+        # If runtime block is given it is called after the end of default callback (handle Array is still being
+        # collected and returned by the method). If Enum... function call fails, method returns nil, otherwise
+        # an Array of all window handles passed into callback.
+        #
+        def return_enum #:nodoc:
+          lambda do |api, *args, &block|
+            args.push 0 if args.size == api.prototype.size - 2 # If value is missing, it defaults to 0
+            handles = []
+
+            # Insert callback proc into appropriate place of args Array
+            args[api.prototype.find_index(:EnumWindowsProc), 0] =
+                    proc do |handle, message|
+                      handles << handle
+                      block ? block[handle, message] : true
+                    end
+            handles if api.call *args
+          end
+        end
+
+        # Helper method that creates def_block returning (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 )  #:nodoc:
+          lambda do |api, *args|
+            namespace.enforce_count( args, api.prototype, -2)
+            buffer = FFI::MemoryPointer.new :char, 1024
+            args += [buffer, buffer.size]
+            num_chars = api.call(*args)
+            return nil if num_chars == 0
+            if encode
+              string = buffer.get_bytes(0, num_chars*2)
+              string = string.force_encoding('utf-16LE').encode(encode)
+            else
+              string = buffer.get_bytes(0, num_chars)
+            end
+            string.rstrip
+          end
+        end
+
+        private :return_enum, :return_string
+      end
+
+      # Windows GUI API definitions:
+
+      ##
+      # The IsWindow function determines whether the specified window handle identifies an existing window.
+      # [*Syntax*] BOOL IsWindow( HWND hWnd );
+      #
+      # hWnd:: [in] Handle to the window to test.
+      #
+      # *Returns*:: If the window handle identifies an existing window, the return value is (*true*).
+      #             If the window handle does not identify an existing window, the return value is (*false*).
+      # ---
+      # *remarks*:
+      # 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.
+      #
+      # :call-seq:
+      # window?( win_handle )
+      #
+      function :IsWindow, [:HWND], :int, boolean: true
+
+      ##
+      # The IsWindowVisible function retrieves the visibility state of the specified window.
+      # [*Syntax*] BOOL IsWindowVisible( HWND hWnd );
+      #
+      # hWnd:: [in] Handle to the window to test.
+      #
+      # *Returns*:: If the specified window, its parent window, its parent's parent window, and so forth,
+      #             have the WS_VISIBLE style set, return value is *true*. 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.
+      # ---
+      # *Remarks*:
+      # - The visibility state of a window is indicated by the WS_VISIBLE style bit. When WS_VISIBLE is set,
+      #   the window is displayed and subsequent drawing into it is displayed as long as the window has the
+      #   WS_VISIBLE style.
+      # - Any drawing to a window with the WS_VISIBLE style will not be displayed if the window is obscured
+      #   by other windows or is clipped by its parent window.
+      #
+      # :call-seq:
+      #   [window_]visible?( win_handle )
+      #
+      function :IsWindowVisible, [:HWND], :int, boolean: true, aliases: :visible?
+
+      ##
+      # Tests whether the specified window is maximized.
+      # [*Syntax*] BOOL IsZoomed( HWND hWnd );
+      #
+      # hWnd:: [in] Handle to the window to test.
+      #
+      # *Returns*:: If the window is zoomed (maximized), the return value is *true*.
+      #             If the window is not zoomed (maximized), the return value is *false*.
+      #
+      # :call-seq:
+      #   zoomed?( win_handle ), maximized?( win_handle )
+      #
+      function :IsZoomed, [:HWND], :int, boolean: true, aliases: :maximized?
+
+      ##
+      # Tests whether the specified window is minimized.
+      # [*Syntax*] BOOL IsIconic( HWND hWnd );
+      #
+      # hWnd:: [in] Handle to the window to test.
+      #
+      # *Returns*:: If the window is iconic (minimized), the return value is *true*.
+      #             If the window is not iconic (minimized), the return value is *false*.
+      #
+      # :call-seq:
+      #   iconic?( win_handle ), minimized?( win_handle )
+      #
+      function :IsIconic, [:HWND], :int, boolean: true, aliases: :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.
+      #
+      # [*Syntax*] BOOL IsChild( HWND hWndParent, HWND hWnd);
+      #
+      # hWndParent:: [in] Handle to the parent window.
+      # hWnd:: [in] Handle to the window to be tested.
+      #
+      # *Returns*::  If the window is a child or descendant window of the specified parent window,
+      #              the return value is *true*. If the window is not a child or descendant window of
+      #              the specified parent window, the return value is *false*.
+      # :call-seq:
+      #   child?( win_handle )
+      #
+      function :IsChild, [:HWND, :HWND], :int, boolean: true
+
+      ##
+      # The FindWindow function retrieves a handle to the top-level window whose class name and window name
+      # match the specified strings. This function does not search child windows. This function does not
+      # perform a case-sensitive search.
+      #
+      # To search child windows, beginning with a specified child window, use the FindWindowEx function.
+      #
+      # [*Syntax*] HWND FindWindow( LPCTSTR lpClassName, LPCTSTR lpWindowName );
+      #
+      # lpClassName:: [in] Pointer to a null-terminated string that specifies the class name or a class
+      #               atom created by a previous call to the RegisterClass or RegisterClassEx function.
+      #               The atom must be in the low-order word of lpClassName; the high-order word must be zero.
+      #               If lpClassName points to a string, it specifies the window class name. The class name
+      #               can be any name registered with RegisterClass or RegisterClassEx, or any of the
+      #               predefined control-class names.
+      #               If lpClassName is NULL, it finds any window whose title matches the lpWindowName parameter.
+      # lpWindowName:: [in] Pointer to a null-terminated string that specifies the window name (the window's title).
+      #                If this parameter is NULL, all window names match.
+      # *Returns*:: If the function succeeds, the return value is a handle to the window that has the specified
+      #             class name and window name. If the function fails, the return value is *nil*.
+      #             To get extended error information, call GetLastError.
+      # ---
+      # *Remarks*:
+      # - If the lpWindowName parameter is not NULL, FindWindow calls the GetWindowText function to retrieve
+      #   the window name for comparison. For a description of a potential problem that can arise, see the
+      #   Remarks for GetWindowText.
+      # - To check if the Microsoft IntelliType version 1.x software is running, call FindWindow as follows:
+      #      find_window("MSITPro::EventQueue", nil)
+      # - To check if the IntelliType version 2.0 software is running, call FindWindow as follows:
+      #      find_window("Type32_Main_Window", nil)
+      #   If the IntelliType software is running, it sends WM_APPCOMMAND messages to the application.
+      #   Otherwise the application must install a hook to receive WM_APPCOMMAND messages.
+      #
+      # :call-seq:
+      #   win_handle = find_window( class_name, win_name )
+      #
+      function :FindWindow, [:pointer, :pointer], :HWND, zeronil: true
+
+      ##
+      # Unicode version of FindWindow (strings must be encoded as utf-16LE AND terminate with "\x00\x00")
+      #
+      # :call-seq:
+      #   win_handle = find_window_w( class_name, win_name )
+      #
+      function :FindWindowW, [:pointer, :pointer], :HWND, zeronil: true
+
+      ##
+      #  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.
+      #  This function does not perform a case-sensitive search.
+      #
+      #  [*Syntax*] HWND FindWindowEx( HWND hwndParent, HWND hwndChildAfter, LPCTSTR lpszClass, LPCTSTR lpszWindow );
+      #
+      #  hwndParent:: [in] Handle to the parent window whose child windows are to be searched.
+      #               If hwndParent is NULL, the function uses the desktop window as the parent window.
+      #               The function searches among windows that are child windows of the desktop.
+      #               Microsoft Windows 2000 and Windows XP: If hwndParent is HWND_MESSAGE, the function
+      #               searches all message-only windows.
+      #  hwndChildAfter:: [in] Handle to a child window. The search begins with the next child window in the Z order.
+      #                   The child window must be a direct child window of hwndParent, not just a descendant window.
+      #                   If hwndChildAfter is NULL, the search begins with the first child window of hwndParent.
+      #                   Note that if both hwndParent and hwndChildAfter are NULL, the function searches all
+      #                   top-level and message-only windows.
+      #  lpszClass:: [in] Pointer to a null-terminated string that specifies the class name or a class atom created
+      #              by a previous call to the RegisterClass or RegisterClassEx function. The atom must be placed in
+      #              the low-order word of lpszClass; the high-order word must be zero.
+      #              If lpszClass is a string, it specifies the window class name. The class name can be any name
+      #              registered with RegisterClass or RegisterClassEx, or any of the predefined control-class names,
+      #              or it can be MAKEINTATOM(0x800). In this latter case, 0x8000 is the atom for a menu class. For
+      #              more information, see the Remarks section of this topic.
+      #  lpszWindow:: [in] Pointer to a null-terminated string that specifies the window name (the window's title).
+      #               If this parameter is NULL, all window names match.
+      #
+      #  *Returns*:: If the function succeeds, the return value is a handle to the window that has the specified
+      #              class and window names. If the function fails, the return value is NULL. For extended error info,
+      #              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.
+      #  - 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
+      #    a context menu is being displayed that the application created.
+      #
+      # :call-seq:
+      #   win_handle = find_window_ex( win_handle, after_child, class_name, win_name )
+      #
+      function :FindWindowEx, [:HWND, :HWND, :pointer, :pointer], :HWND, zeronil: true
+
+      ##
+      # GetWindowText 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.
+      #
+      # [*Syntax*] int GetWindowText( HWND hWnd, LPTSTR lpString, int nMaxCount );
+      #
+      # *Original* Parameters:
+      # hWnd:: Handle to the window and, indirectly, the class to which the window belongs.
+      # lpString:: Long Pointer to the buffer that is to receive the text string.
+      # nMaxCount:: Specifies the length, in TCHAR, of the buffer pointed to by the text parameter.
+      #             The class name string is truncated if it is longer than the buffer and is always null-terminated.
+      # *Original* Return:: Length, in characters, of the copied string, not including the terminating null
+      #                     character (if success). Zero indicates that the window has no title bar or text,
+      #                     if the title bar is empty, or if the window or control handle is invalid.
+      #                     For extended error information, call GetLastError.
+      # ---
+      # Enhanced API requires only win_handle and returns rstripped text
+      #
+      # *Enhanced* Parameters:
+      # win_handle:: Handle to the window and, indirectly, the class to which the window belongs.
+      # *Returns*:: Window title bar text or nil. 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 *NIL*.
+      #             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.
+      #
+      #:call-seq:
+      #   text = [get_]window_text( win_handle )
+      #
+      function :GetWindowText, [:HWND, :pointer, :int], :int, &return_string
+
+      ##
+      # GetWindowTextW is a Unicode version of GetWindowText (returns rstripped utf-8 string)
+      # API improved to require only win_handle and return rstripped string
+      #
+      #:call-seq:
+      #   text = [get_]window_text_w( win_handle )
+      #
+      function :GetWindowTextW, [:HWND, :pointer, :int], :int, &return_string('utf-8')
+
+      ##
+      # GetClassName retrieves the name of the class to which the specified window belongs.
+      # [*Syntax*] int GetClassName( HWND hWnd, LPTSTR lpClassName, int nMaxCount );
+      # *Original* Parameters:
+      # hWnd:: [in] Handle to the window and, indirectly, the class to which the window belongs.
+      # lpClassName:: [out] Pointer to the buffer that is to receive the class name string.
+      # nMaxCount:: [in] Specifies the length, in TCHAR, of the buffer pointed to by the lpClassName parameter.
+      #             The class name string is truncated if it is longer than the buffer and is always null-terminated.
+      # *Original* Return:: Length, in characters, of the copied string, not including the terminating null character,
+      #                     indicates success. Zero indicates that the window has no title bar or text, if the title
+      #                     bar is empty, or if the window or control handle is invalid.
+      # ---
+      # API improved to require only win_handle and return rstripped string
+      #
+      # *Enhanced* Parameters:
+      # win_handle:: Handle to the window and, indirectly, the class to which the window belongs.
+      # *Returns*:: Name of the class or *nil* if function fails. For extended error information, call GetLastError.
+      #
+      #:call-seq:
+      #   text = [get_]class_name( win_handle )
+      #
+      function :GetClassName, [:HWND, :pointer, :int], :int, &return_string
+
+      ##
+      # GetClassNameW is a Unicode version of GetClassName (returns rstripped utf-8 string)
+      # API improved to require only win_handle and return rstripped string
+      #
+      #:call-seq:
+      #   text = [get_]class_name_w( win_handle )
+      #
+      function :GetClassNameW, [:HWND, :pointer, :int], :int, &return_string('utf-8')
+
+      ##
+      # ShowWindow shows and hides windows (sets the specified window's show state).
+      #
+      # [*Syntax*] BOOL ShowWindow( HWND hWnd, int nCmdShow);
+      #
+      # hWnd:: Handle to the window.
+      # nCmdShow:: 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, SW_MAXIMIZE, SW_MINIMIZE, SW_SHOW, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, SW_SHOWMINNOACTIVE,
+      #            SW_SHOWNA, SW_SHOWNOACTIVATE, SW_SHOWNORMAL, SW_RESTORE, SW_SHOWDEFAULT, SW_FORCEMINIMIZE
+      #
+      # *Returns*:: *True* if the window was PREVIOUSLY visible, otherwise *false*
+      #
+      #:call-seq:
+      #   was_visible = show_window( win_handle, cmd )
+      #
+      function :ShowWindow, [:HWND, :int], :int, boolean: true,
+               &->(api, handle, cmd=SW_SHOW) { api.call handle, cmd }
+
+      ##
+      # The CloseWindow function minimizes (but does not destroy) the specified window.
+      #
+      # [*Syntax*]: BOOL CloseWindow( HWND hWnd );
+      #
+      # hWnd:: [in] Handle to the window to be minimized.
+      #
+      # *Returns*:: If the function succeeds, the return value is nonzero (*true* in snake_case method). If the function
+      #             fails, the return value is zero (*false). To get extended error information, call GetLastError.
+      # ---
+      # *Remarks*:
+      # To destroy a window, an application must use the DestroyWindow function.
+      #
+      function :CloseWindow, [:HWND], :int, boolean: true
+
+      ##
+      # DestroyWindow function destroys the specified window. The function sends WM_DESTROY and WM_NCDESTROY messages
+      # to the window to deactivate it and remove the keyboard focus from it. The function also destroys the window's
+      # menu, flushes the thread message queue, destroys timers, removes clipboard ownership, and breaks the clipboard
+      # viewer chain (if the window is at the top of the viewer chain).
+      #
+      # If the specified window is a parent or owner window, DestroyWindow automatically destroys the associated child
+      # or owned windows when it destroys the parent or owner window. The function first destroys child or owned
+      # windows, and then it destroys the parent or owner window.
+      #
+      # DestroyWindow also destroys modeless dialog boxes created by the CreateDialog function.
+      #
+      # [*Syntax*]: BOOL DestroyWindow( HWND hWnd );
+      #
+      # hWnd:: [in] Handle to the window to be destroyed.
+      #
+      # *Returns*:: If the function succeeds, the return value is nonzero (snake_case method: *true*). If the function
+      #             fails, the return value is zero (*false*). To get extended error information, call GetLastError.
+      # ---
+      # *Remarks*:
+      # A thread <b>cannot use DestroyWindow to destroy a window created by a different thread.</b> Use a convenience
+      # method destroy_unowned_window instead (it relies on 
+      # If the window being destroyed is a child window that does not have the WS_EX_NOPARENTNOTIFY style, a
+      # WM_PARENTNOTIFY message is sent to the parent.
+      #
+      function :DestroyWindow, [:HWND], :int, boolean: true
+
+      ##
+      # GetWindowThreadProcessId retrieves the identifier of the thread that created the specified window
+      # and, optionally, the identifier of the process that created the window.
+      #
+      # [*Syntax*] DWORD GetWindowThreadProcessId( HWND hWnd, LPDWORD lpdwProcessId );
+      #
+      # *Original* Parameters:
+      # hWnd:: [in] Handle to the window.
+      # lpdwProcessId:: [out] Pointer to a variable that receives the process identifier. If this parameter
+      #                 is not NULL, GetWindowThreadProcessId copies the identifier of the process to the
+      #                 variable; otherwise, it does not.
+      # *Original* Return:: The identifier of the thread that created the window.
+      # ---
+      # API improved to accept window handle as a single arg and return a pair of [thread, process] ids
+      #
+      # *New* Parameters:
+      # handle:: Handle to the window.
+      # *Returns*: Pair of identifiers of the thread and process_id that created the window.
+      #
+      #:call-seq:
+      #   thread, process_id = [get_]window_tread_process_id( win_handle )
+      #
+      function :GetWindowThreadProcessId, [:HWND, :pointer], :long,
+               &->(api, handle) {
+               process = FFI::MemoryPointer.new(:long).write_long(1)
+               thread = api.call(handle, process)
+               thread == 0 ? [nil, nil] : [thread, process.read_long()] }
+      # weird lambda literal instead of normal block is needed because current version of RDoc
+      # goes crazy if block is attached to meta-definition
+
+      ##
+      # GetWindowRect retrieves the dimensions of the specified window bounding rectangle.
+      # Dimensions are given relative to the upper-left corner of the screen.
+      #
+      # [*Syntax*] BOOL GetWindowRect( HWND hWnd, LPRECT lpRect );
+      #
+      # *Original* Parameters:
+      # hWnd::  [in] Handle to the window.
+      # lpRect:: [out] Pointer to a structure that receives the screen coordinates of the upper-left and
+      #          lower-right corners of the window.
+      # *Original* Return:: Nonzero indicates success. Zero indicates failure. For error info, call GetLastError.
+      # ---
+      # API improved to accept only window handle and return 4-member dimensions array (left, top, right, bottom)
+      #
+      # *New* Parameters:
+      # win_handle:: Handle to the window
+      # *Returns*:: Array(left, top, right, bottom) - rectangle dimensions
+      # ---
+      # *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.
+      #
+      #:call-seq:
+      #   rect = [get_]window_rect( win_handle )
+      #
+      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
+      # as a result of a call to the EnumWindows, EnumChildWindows or EnumDesktopWindows function.
+      #
+      # [*Syntax*] BOOL CALLBACK EnumWindowsProc( HWND hwnd, LPARAM lParam );
+      #
+      # hWnd:: [in] Handle to a top-level window.
+      # lParam:: [in] Specifies the application-defined value given in EnumWindows or EnumDesktopWindows.
+      # *Return* *Value*:: To continue enumeration, the callback function must return TRUE;
+      #                    to stop enumeration, it must return FALSE.
+      # ---
+      # Remarks:
+      # - An application must register this callback function by passing its address to EnumWindows,
+      #   EnumChildWindows or EnumDesktopWindows.
+      # - You must ensure that the callback function sets SetLastError if it fails.
+      #
+      # :call-seq:
+      #  EnumWindowsProc callback block: {|win_handle, value| your callback code }
+      #
+      callback :EnumWindowsProc, [:HWND, :long], :bool
+
+      ##
+      # 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.
+      #
+      # [*Syntax*] BOOL EnumWindows( WNDENUMPROC lpEnumFunc, LPARAM lParam );
+      #
+      # *Original* Parameters:
+      # lpEnumFunc:: [in] Pointer to an application-defined callback function of EnumWindowsProc type.
+      # lParam:: [in] Specifies an application-defined value(message) to be passed to the callback function.
+      # *Original* Return:: Nonzero if the function succeeds, zero if the function fails. GetLastError for 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.
+      # ---
+      # API improved to accept blocks (instead of callback objects) with message as an optional argument
+      #
+      # *New* Parameters:
+      # message:: Specifies an application-defined value(message) to be passed to the callback block.
+      # attached block:: Serves as an application-defined callback function (see EnumWindowsProc).
+      # *Returns*:: *True* if the function succeeds, *false* if the function fails. GetLastError for error info.
+      #             If callback returned zero/false, the return value is also false. 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.
+      #
+      # :call-seq:
+      #   handles = enum_windows( [value=0] ) {|handle, value| your callback procedure }
+      #
+      function :EnumWindows, [:EnumWindowsProc, :long], :int8, &return_enum
+
+      ##
+      # EnumDesktopWindows Function enumerates all top-level windows associated with the specified desktop.
+      # It passes the handle to each window, in turn, to an application-defined callback function.
+      #
+      # [*Syntax*] BOOL WINAPI EnumDesktopWindows( __in_opt HDESK hDesktop, __in WNDENUMPROC lpfn,  __in LPARAM lParam);
+      #
+      # *Original* Parameters:
+      # hDesktop:: A handle to the desktop whose top-level windows are to be enumerated. This handle is returned by
+      #            the CreateDesktop, GetThreadDesktop, OpenDesktop, or OpenInputDesktop function, and must have the
+      #            DESKTOP_ENUMERATE access right. For more information, see Desktop Security and Access Rights.
+      #            If this parameter is NULL, the current desktop is used.
+      # lpfn:: A pointer to an application-defined EnumWindowsProc callback.
+      # lParam:: An application-defined value to be passed to the callback.
+      # *Return*:: If the function fails or is unable to perform the enumeration, the return value is zero.
+      #            To get extended error information, call GetLastError. You must ensure that the callback function
+      #            sets SetLastError if it fails.
+      # ---
+      # API enhanced to return *true*/*false* instead of nonzero/zero, and message value is optional (defaults to 0).
+      #
+      # *Enhanced*12 34 Parameters:
+      # desktop:: A handle to the desktop whose top-level windows are to be enumerated.
+      # value:: Specifies an application-defined value(message) to be passed to the callback (default 0).
+      # attached block:: Serves as an application-defined callback function (see EnumWindowsProc).
+      # ---
+      # *Remarks*:
+      # - Windows Server 2003 and Windows XP/2000: If there are no windows on the desktop, GetLastError returns
+      #   ERROR_INVALID_HANDLE.
+      # - The EnumDesktopWindows function repeatedly invokes the callback function until the last top-level window
+      #   is enumerated or the callback function returns FALSE.
+      # ---
+      # *Requirements*:
+      # Client Requires Windows Vista, Windows XP, or Windows 2000 Professional.
+      #
+      # :call-seq:
+      #   handles = enum_desktop_windows( desktop_handle, [value=0] ) {|handle, value| your callback procedure }
+      #
+      function :EnumDesktopWindows, [:ulong, :EnumWindowsProc, :long], :int8, &return_enum
+
+      ##
+      # The EnumChildWindows function enumerates the child windows that belong to the specified parent window by
+      # passing the handle of each child window, in turn, to an application-defined callback. EnumChildWindows
+      # continues until the last child window is enumerated or the callback function returns FALSE.
+      #
+      # [*Syntax*] BOOL EnumChildWindows( HWND hWndParent, WNDENUMPROC lpEnumFunc, LPARAM lParam );
+      #
+      # *Original* Parameters:
+      # hWndParent:: [in] Handle to the parent window whose child windows are to be enumerated. If this parameter
+      #              is NULL, this function is equivalent to EnumWindows.
+      #              Windows 95/98/Me: hWndParent cannot be NULL.
+      # lpEnumFunc:: [in] Pointer to an application-defined callback. For more information, see EnumChildProc.
+      # lParam:: [in] Specifies an application-defined value to be passed to the callback function.
+      #
+      # *Return*:: Not used!
+      # ---
+      # API improved to accept blocks (instead of callback objects) and parent handle (value is optional, default 0)
+      #
+      # *New* Parameters:
+      # parent:: Handle to the parent window whose child windows are to be enumerated.
+      # value:: Specifies an application-defined value(message) to be passed to the callback function.
+      # attached block:: Serves as an application-defined callback function (see EnumWindowsProc).
+      # ---
+      # *Remarks*:
+      # - 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.
+      #
+      #:call-seq:
+      #   handles = enum_child_windows( parent_handle, [value=0] ) {|handle, value| your callback procedure }
+      #
+      function :EnumChildWindows, [:HWND, :EnumWindowsProc, :long], :int8, &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);
+      #
+      # *Returns*:: 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()
+      #
+      function :GetForegroundWindow, [], :HWND, zeronil: true
+
+      ##
+      # The GetActiveWindow function retrieves the window handle to the active window attached to
+      # the calling thread's message queue.
+      #
+      # [*Syntax*]  HWND GetActiveWindow(VOID);
+      #
+      # *Returns*:: 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()
+      #
+      function :GetActiveWindow, [], :HWND, zeronil: true
+
+
+      # Convenience wrapper methods:
+
+      ##
+      # Hides the window and activates another window
+      #
+      def hide_window( win_handle )
+        show_window(win_handle, SW_HIDE)
+      end
+
+      ##
+      # Tests if given window handle points to foreground (topmost) window
+      #
+      def foreground?( win_handle )
+        win_handle == foreground_window
+      end
+
+      ##
+      # Shuts down the window <b>created by different thread</b> by posting WM_SYSCOMMAND, SC_CLOSE message to it.
+      # This closely emulates user clicking on X button of the target window. As it would be expected, this
+      # actually gives the target window chance to close gracefully (it may ask user to save data and stuff).
+      # I have not found so far how to REALLY destroy window in different thread without it asking user anything.
+      #
+      def shut_window( win_handle )
+        post_message(win_handle, Win::Gui::Message::WM_SYSCOMMAND, Win::Gui::Message::SC_CLOSE, nil)
+      end
+
+      ##
+      # Returns text associated with window by sending WM_GETTEXT message to it.
+      # ---
+      # *Remarks*: It is *different* from GetWindowText that returns only window title
+      #
+      def text( win_handle )
+        buffer = FFI::MemoryPointer.new :char, 1024
+        num_chars = send_message win_handle, Win::Gui::Message::WM_GETTEXT, buffer.size, buffer
+        num_chars == 0 ?  nil : buffer.get_bytes(0, num_chars)
+      end
+    end
+  end
+end
+