= win_gui
by:: Arvicco
url:: http://github.com/arvicco/win_gui

== DESCRIPTION:

WinGui is a module that provides higher-level abstractions/wrappers around GUI-related
Win32 API functions. It uses Win gem as a basis, which in turn uses FFI.
So (in theory) it should work for any Ruby implementation supporting FFI. In practice,
it's only been tested under mingw and cygwin flavors of Ruby 1.9. Porting to JRuby is
under way, waiting for its 1.9 compatibility to mature.

== SUMMARY:

Win gem provides Rubyesque wrappers around Win32 API functions, but it is not enough to
to make Win32 API calls feel like more or less natural extension of Ruby code.
The reason for this, straightforward API wrappers are not object-oriented enough.

For example, here is how you deal with typical GUI-related tasks using Win:

  require 'win/gui'
  include Win::Gui::Window

  window_handle = find_window('WinClass', nil)
  title = window_text(window_handle )
  thread, process = window_thread_process_id(window_handle)
  puts window_handle, title, thread, process

  enum_child_windows(window_handle, message) do |child_handle, message|
    title = window_text(child_handle )
    thread, process = window_thread_process_id(child_handle)
    puts child_handle, title, thread, process
  end
  close_window(window_handle)

This works fine, but such functional style just does not feel like object-oriented Ruby.
Ideally, there should be a thin wrapper class around window handle, and the code above
should be more like this:

  require 'win_gui'
  include WinGui

  window = Window.find(:title => /PartTitle/)
  puts window.handle, window.title, window.thread, window.process
  window.children.each {|child| puts child.handle, child.title, child.thread, child.process }
  window.close

WinGui library strives to provide such wrappers and convenience methods that will make
working with Windows GUI-related code much more fun than it is right now.

== REQUIREMENTS:

Only works with Ruby 1.9 compatible implementations since Win gem uses some of latest Ruby features.

== INSTALL:

  $ sudo gem install win_gui

== SYNOPSIS:

  require 'win_gui'
  include WinGui

More examples will follow when the code is closer to production quality...  

== CREDITS/PRIOR ART:

This library started as an extension of ideas and code described in excellent book
"Scripted GUI Testing with Ruby" by Ian Dees.

Win32::GuiTest by MoonWolf is a port of eponimous Perl library to Ruby
(http://raa.ruby-lang.org/project/win32-guitest). I do not like its Perlisms though.

== LICENSE:

Copyright (c) 2010 Arvicco. See LICENSE for details