Microsoft Windows Support

The three libraries documented in this chapter turn Ruby into a powerful and convenient Windows scripting language. Now you have the power to control your applications, but in a controlled, object-oriented environment.

class WIN32OLE

Parent:	Object
Version:	1.6

Index:

connect const_load new [ ] [ ]= each invoke

require 'win32ole' ie = WIN32OLE.new('InternetExplorer.Application') ie.visible = true ie.gohome

WIN32OLEprovides a client interface to Windows 32 OLE Automation servers. See the tutorial description on page 164 for more information.

constants


`WIN32OLE::VERSION`		Current version number

class methods
connect	WIN32OLE.connect(aString) ->wapi
	Returns a new OLE automation client connected to an existing instance of the named automation server.
const_load	WIN32OLE.const_load(wapi,[aClass=WIN32OLE]) ->`nil`
	Defines the constants from the specified automation server as class constants inaClass.
new	WIN32OLE.new(aString) ->wapi
	Returns a new OLE automation client connected to a new instance of the automation server named byaString.

instance methods
[ ]	wapi[aString] ->anObject
	Returns the named property from the OLE automation object.
[ ]=	wapi[aString] =aValue->`nil`
	Sets the named property in the OLE automation object.
each	wapi.each {\| anObj \| block } ->`nil`
	Iterates over each item of this OLE server that supports the`IEnumVARIANT`interface.
invoke	wapi.invoke (aCmdString,[args]^) ->anObject*
	Invokes the command given inaCmdStringwith the givenargs.argsmay be a`Hash`of named parameters and values. You don't need to call`invoke`explicitly; this class uses`method_missing`to forward calls through`invoke`, so you can simply use the OLE methods as methods of this class.

class WIN32OLE_EVENT

Parent:	Object
Version:	1.6

Index:

message_loop new on_event

This (slightly modified) example from the Win32OLE 0.1.1 distribution shows the use of an event sink.

require 'win32ole'
$urls = []
def navigate(url) $urls << url end
def stop_msg_loop puts "IE has exited..." throw :done end
def default_handler(event, *args) case event when "BeforeNavigate" puts "Now Navigating to #{args[0]}..." end end
ie = WIN32OLE.new('InternetExplorer.Application') ie.visible = TRUE ie.gohome ev = WIN32OLE_EVENT.new(ie, 'DWebBrowserEvents')
ev.on_event {|*args| default_handler(*args)} ev.on_event("NavigateComplete") {|url| navigate(url)} ev.on_event("Quit") {|*args| stop_msg_loop}
catch(:done) { loop { WIN32OLE_EVENT.message_loop } }
puts "You Navigated to the following URLs: " $urls.each_with_index do |url, i| puts "(#{i+1}) #{url}" end

WIN32OLE_EVENTis used in conjunction with the WIN32OLEclass to add callbacks for Windows 32 events.

class methods
message_loop	WIN32OLE_EVENT.message_loop ->`nil`
	Executes the Windows event loop, translating and dispatching events.
new	WIN32OLE_EVENT.new (anOle,aName) ->wapi
	Returns a new`WIN32OLE_EVENT`(an event sink) for the given`WIN32OLE`object and named event source. IfaNameis`nil`, it will attempt to use the default source and will raise a`RuntimeError`if it cannot find one.

instance methods

on_event

wapi.on_event ([anEvent]) {| args | block }

->nil

Defines a callback for the namedanEvent. IfanEventisnil, then this callback is associated with all events. The block will be given any arguments appropriate for this event.

class Win32API

Parent:	Object
Version:	1.6

Index:

new call Call

This example is from the Ruby distribution, in ext/Win32API:

require 'Win32API'
getCursorPos = Win32API.new("user32", "GetCursorPos", ['P'], 'V')
lpPoint = " " * 8 # store two LONGs getCursorPos.Call(lpPoint) x, y = lpPoint.unpack("LL") # get the actual values
print "x: ", x, "\n" print "y: ", y, "\n"
ods = Win32API.new("kernel32", "OutputDebugString", ['P'], 'V') ods.Call("Hello, World\n")
GetDesktopWindow = Win32API.new("user32", "GetDesktopWindow", [], 'L') GetActiveWindow = Win32API.new("user32", "GetActiveWindow", [], 'L') SendMessage = Win32API.new("user32", "SendMessage", ['L'] * 4, 'L') SendMessage.Call(GetDesktopWindow.Call, 274, 0xf140, 0)

The Win32APImodule allows access to any arbitrary Windows 32 function. Many of these functions take or return a Pointerdatatype---a region of memory corresponding to a C string or structure type.

In Ruby, these pointers are represented using class String, which contains a sequence of 8-bit bytes. It is up to you to pack and unpack the bits in the String. See the reference section for unpack on page 378 and pack on page 286 for details.

class methods

new

Win32API.new(dllname,procname,importArray,export) ->wapi

Returns a new object representing a Windows 32 API function.dllnameis the name of the DLL containing the function, such as ``user32'' or ``kernel32.''procnameis the name of the desired function.importArrayis an array of strings representing the types of arguments to the function.exportis a string representing the return type of the function. Strings ``n'' and ``l'' represent numbers, ``i'' represent integers, ``p'' represents pointers to data stored in a string, and ``v'' represents a void type (used for export parameters only). These strings are case-insensitive.

instance methods
call	wapi.call([args]^) ->anObject*
	Calls this API function with the given arguments, which must match the signature specified to`new`.
Call	wapi.Call([args]^) ->anObject*
	Synonym for`Win32API#call`.

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright