win_gui 0.1.2 → 0.1.3

data/README.rdoc

@@ -14,6 +14,64 @@ elements (such as WinGui::Window class and its methods).
 
 It is still work in progress, only a small number of API functions wrapped so far...
 
+== SUMMARY
+
+So you want to write a simple program that makes some Win32 API function calls.
+You searched MSDN and you know what functions you'll need. Now you just want to
+put those calls into your Ruby code. You'd love it to be a natural extension of
+Ruby code, preferably not turning your code base into a ugly C++ like spaghetty
+of CamelCase calls, String/Array pack/unpack gymnastics, buffer allocations,
+extracting return values from [in/out] parameters and checking return codes for 0.
+You can definitely use excellent 'win32-api' gem by Daniel J. Berger and Park Heesob
+that allows you to define Win32 API objects for any function you can find on MSDN,
+execute calls on them and even define callback objects that some of those API functions expect.
+
+However, this gem will only take you so far. You'll still have to handle (somewhat)
+gory details of argument preparation, mimicking pointers with Strings and stuff.
+For example, consider the amount of code needed to complete a task as simple as
+getting unicode title text for the window that you already have handle for:
+
+  api = Win32::API.new( 'GetWindowTextW', ['L', 'P', 'I'], 'L', 'user32' )
+  buffer = "\x00" * 1024
+  num_chars = api.call( window_handle, buffer, buffer.size)
+  title = if num_chars == 0
+    nil
+  else
+     buffer.force_encoding('utf-16LE').encode('utf-8').rstrip
+  end
+
+Ew, ugly. What about getting information about process id for a known window?
+
+  api = Win32::API.new( 'GetWindowThreadProcessId', ['L', 'P'], 'L' , 'user32' )
+    process_packed = [1].pack('L')
+    thread = api.call(window_handle, process_packed)
+    process = process.unpack('L').first
+
+Wow, packing and unpacking arrays into String to get hold of a simple integer id.
+Just great. Now, wouldn't it be MUCH better if you can just say something like this:
+
+  title = window_text( window_handle)
+  thread, process = window_thread_process_id( window_handle)
+
+What about API functions expecting callbacks? Well, something like this may be nice:
+
+  enum_child_windows( parent_handle, message ){|child_handle, message| puts child_handle }
+
+If you think about it, callbacks are not much than more than code blocks, so let's not
+be afraid to treat them as such. It would be also good if test functions return true/false
+instead of zero/nonzero, find functions return nil if nothing was found etc...
+
+So this is an idea behind WinGui library - make Win32 API functions more fun to use
+and feel more natural inside Ruby code. Following the principle of least surprise, we
+define methods with Rubyesque names (minimized? instead of IsMinimized, etc), minimum
+arguments with sensible defaults, explicit return values and generous use of attached blocks.
+
+Well, we even keep a backup solution for those diehard Win32 API longtimers who would rather
+allocate their buffer strings by hand and mess with obscure return codes. If you use original
+CamelCase method name instead of Rubyesque snake_case one, it will expect those standard
+parameters you know and love from MSDN, return your zeroes instead of nils and support no
+other enhancements. Enjoy!
+
 == DOCUMENTATION:
 
 See WinGui and WinGui::Window for documentation
@@ -25,7 +83,7 @@ arguments given to block, etc...)
 
 == FEATURES/PROBLEMS:
 
-This project is quite new, so it's probably not ready for prime time just yet...
+This project is quite new, so it's may be not suitable for production-quality systems
 Contributors always welcome!
 
 == INSTALL:

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/lib/win_gui/constants.rb

@@ -1,71 +1,82 @@
 module WinGui
   
-  # WinGui Module internal Constants:
-
-  WG_KEY_DELAY = 0.00001 
-  WG_SLEEP_DELAY = 0.001 
+  # Delay between key commands (events)
+  WG_KEY_DELAY = 0.00001
+  # Wait delay quant
+  WG_SLEEP_DELAY = 0.001
+  # Timeout waiting for Window to be closed
   WG_CLOSE_TIMEOUT = 1
-  #WG_TEXT_BUFFER = '\0' * 2048
-  
+
   # Windows keyboard-related Constants:
   #   Virtual key codes:
 
-  VK_CANCEL   = 0x03 # Control-break processing
+
+  # Control-break processing
+  VK_CANCEL   = 0x03
+  #  Backspace? key
   VK_BACK     = 0x08
+  #  Tab key
   VK_TAB      = 0x09
+  #  Shift key
   VK_SHIFT    = 0x10
+  #  Ctrl key
   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_NEXT     = 0x22  #  PAGE DOWN key
-  VK_END      = 0x23  #  END key
-  VK_HOME     = 0x24  #  HOME key
-  VK_LEFT     = 0x25  #  LEFT ARROW key
-  VK_UP       = 0x26  #  UP ARROW key
-  VK_RIGHT    = 0x27  #  RIGHT ARROW key
-  VK_DOWN     = 0x28  #  DOWN ARROW key
-  VK_SELECT   = 0x29  #  SELECT key
-  VK_PRINT    = 0x2A  #  PRINT key
-  VK_EXECUTE  = 0x2B  #  EXECUTE key
-  VK_SNAPSHOT = 0x2C  #  PRINT SCREEN key
-  VK_INSERT   = 0x2D  #  INS key
-  VK_DELETE   = 0x2E  #  DEL key
-  VK_HELP     = 0x2F  #  HELP key
-
-  #   Key events:
+  #  ENTER key
+  VK_RETURN   = 0x0D
+  #  ALT key
+  VK_ALT      = 0x12
+  #  ALT key alias
+  VK_MENU     = 0x12
+  #  PAUSE key
+  VK_PAUSE    = 0x13
+  #  CAPS LOCK key
+  VK_CAPITAL  = 0x14
+  #  ESC key
+  VK_ESCAPE   = 0x1B
+  #  SPACEBAR
+  VK_SPACE    = 0x20
+  #  PAGE UP key
+  VK_PRIOR    = 0x21
+  #  PAGE DOWN key
+  VK_NEXT     = 0x22
+  #  END key
+  VK_END      = 0x23
+  #  HOME key
+  VK_HOME     = 0x24
+  #  LEFT ARROW key
+  VK_LEFT     = 0x25
+  #  UP ARROW key
+  VK_UP       = 0x26
+  #  RIGHT ARROW key
+  VK_RIGHT    = 0x27
+  #  DOWN ARROW key
+  VK_DOWN     = 0x28
+  #  SELECT key
+  VK_SELECT   = 0x29
+  #  PRINT key
+  VK_PRINT    = 0x2A
+  #  EXECUTE key
+  VK_EXECUTE  = 0x2B
+  #  PRINT SCREEN key
+  VK_SNAPSHOT = 0x2C
+  #  INS key
+  VK_INSERT   = 0x2D
+  #  DEL key
+  VK_DELETE   = 0x2E
+  #  HELP key
+  VK_HELP     = 0x2F
 
+  # Key down keyboard event
   KEYEVENTF_KEYDOWN = 0
-  KEYEVENTF_KEYUP = 2 
-  
-  #   Show Window Commands:
-
-  SW_HIDE           = 0
-  SW_NORMAL         = 1
-  SW_SHOWNORMAL     = 1
-  SW_SHOWMINIMIZED  = 2
-  SW_SHOWMAXIMIZED  = 3
-  SW_MAXIMIZE       = 3
-  SW_SHOWNOACTIVATE = 4
-  SW_SHOW           = 5
-  SW_MINIMIZE       = 6
-  SW_SHOWMINNOACTIVE= 7
-  SW_SHOWNA         = 8
-  SW_RESTORE        = 9
-  SW_SHOWDEFAULT    = 10
-  SW_FORCEMINIMIZE  = 11
+  # Key up keyboard event
+  KEYEVENTF_KEYUP = 2
   
-  # Windows Messages Constants:
-
+  # Windows Message Get Text
   WM_GETTEXT = 0x000D
+  # Windows Message Sys Command
   WM_SYSCOMMAND = 0x0112
+  # Sys Command Close
   SC_CLOSE = 0xF060
   
-  # Other Windows Constants:
 end
 

data/lib/win_gui/def_api.rb

@@ -1,66 +1,97 @@
+require 'Win32/api'
+
 module WinGui
   module DefApi
+    # DLL to use with API decarations by default ('user32')
     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
-    # to attached block (if any) and (optionally) transforms the result before returning it.
+    # Defines new method wrappers for Windows API function call:
+    #   - Defines method with original (CamelCase) API function name and original signature (matches MSDN description)
+    #   - Defines method with snake_case name (converted from CamelCase function name) with enhanced API signature
+    #       When the defined wrapper method is called, it checks the argument count, executes underlying API
+    #       function call and (optionally) transforms the result before returning it. If block is attached to
+    #       method invocation, raw result is yielded to this block before final transformations
+    #   - Defines aliases for enhanced method with more Rubyesque names for getters, setters and tests:
+    #       GetWindowText -> window_test, SetWindowText -> window_text=, IsZoomed -> zoomed?
     #
-    # You may modify default defined method behavior by providing optional &define_block to def_api.
-    # If you do so, instead of directly calling API function, defined method yields callable api object, arguments
-    # and (optional) runtime block to &define_block that should define method content and return result.
+    # You may modify default behavior of defined method by providing optional &define_block to def_api.
+    #   If you do so, instead of directly calling API function, defined method just yields callable api
+    #   object, arguments and (optional) runtime block to your &define_block and returns result coming out of it.
+    #   So, &define_block should define all the behavior of defined method. You can use define_block to:
+    #   - Change original signature of API function, provide argument defaults, check argument types
+    #   - Pack arguments into strings for [in] or [in/out] parameters that expect a pointer
+    #   - Allocate string buffers for pointers required by API functions [out] parameters
+    #   - Unpack [out] and [in/out] parameters returned as pointers
+    #   - Explicitly return results of API call that are returned in [out] and [in/out] parameters
+    #   - Convert attached runtime blocks into callback functions and stuff them into [in] callback parameters
     #
     # 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
-    # :zeronil:: Forces method to return nil if function result is zero
+    #   :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
+    #   :zeronil:: Forces method to return nil if function result is zero
     #
     def def_api(function, params, returns, options={}, &define_block)
+      aliases = ([options[:alias]] + [options[:aliases]]).flatten.compact
       name = options[:rename] || function.snake_case
-      if name.sub!(/^is_/, '')
-        name << '?'
-        boolean = true
+      case name
+        when /^is_/
+          aliases << name.sub(/^is_/, '') + '?'
+          boolean = true
+        when /^set_/
+          aliases << name.sub(/^set_/, '')+ '='
+        when /^get_/
+          aliases << name.sub(/^get_/, '')
       end
       boolean ||= options[:boolean]
       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] || DEFAULT_DLL)
 
-      define_method(name) do |*args, &runtime_block|
+      define_method(function) {|*args| api.call(*args)} # defines CamelCase method wrapper for api call
+
+      define_method(name) do |*args, &runtime_block|    # defines snake_case method with enhanced api
         return api if args == [:api]
         return define_block.call(api, *args, &runtime_block) if define_block
-        raise 'Invalid args count' unless args.size == params.size
+        unless args.size == params.size
+          raise ArgumentError, "wrong number of parameters: expected #{params.size}, got #{args.size}"
+        end  
         result = api.call(*args)
-        yield result if runtime_block
+        result = runtime_block[result] if runtime_block
         return result != 0 if boolean       # Boolean function returns true/false instead of nonzero/zero
         return nil if zeronil && result == 0
         result
       end
-      aliases.each {|aliass| alias_method aliass, name } unless aliases == []
+      aliases.each {|ali| alias_method ali, name } unless aliases == []
     end
 
-    # Helper methods:
-
     # Converts block into API::Callback object that can be used as API callback argument
+    #
     def callback(params, returns, &block)
       Win32::API::Callback.new(params, returns, &block)
     end
 
+    private  # Helper methods:
+
     # Returns string buffer - used to supply string pointer reference to API functions
+    #
     def buffer(size = 1024, code = "\x00")
       code * size
     end
 
     # Procedure that returns (possibly encoded) string as a result of api function call
+    # or nil if zero characters was returned by api call
+    #
     def return_string( encode = nil )
       lambda do |api, *args|
-        raise 'Invalid args count' unless args.size == api.prototype.size-2
+      num_params = api.prototype.size-2
+      unless args.size == num_params
+        raise ArgumentError, "wrong number of parameters: expected #{num_params}, got #{args.size}"
+      end
         args += [string = buffer, string.length]
-        num_chars = api.call(*args) # num_chars not used
+        num_chars = api.call(*args)
+        return nil if num_chars == 0
         string = string.force_encoding('utf-16LE').encode(encode) if encode
         string.rstrip
       end
@@ -69,9 +100,13 @@ module WinGui
     # 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
+        num_params = api.prototype.size-1
+        unless args.size == num_params
+          raise ArgumentError, "wrong number of parameters: expected #{num_params}, got #{args.size}"
+        end
         handles = []
         cb = if block
           callback('LP', 'I', &block)
@@ -87,5 +122,21 @@ module WinGui
       end
     end
 
+    # Procedure that calls (DdeInitialize) function expecting a DdeCallback. Runtime block is converted
+    # into Dde callback and registered with DdeInitialize. Returns DDE init status and DDE instance id.
+    #
+    # TODO: Pushed into this module since RubyMine (wrongly) reports error on lambda args
+    #
+    def return_id_status
+      lambda do |api, id=0, cmd, &block|
+        raise ArgumentError, 'No callback block' unless block
+        callback = callback 'IIPPPPPP', 'L', &block
+        id = [id].pack('L')
+
+        status = api.call(id, callback, cmd, 0)
+        [*id.unpack('L'), status]
+      end
+    end
+
   end
 end