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:

require 'win32ole'

ie = WIN32OLE.new('InternetExplorer.Application')

ie.visible = true

ie.gohome

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 theIEnumVARIANT interface.

invoke
wapi.invoke (aCmdString,[args]^*) ->anObject
Invokes the command given inaCmdString with the givenargs.args may be aHash of named parameters and values. You don't need to callinvoke explicitly; this class usesmethod_missing to forward calls throughinvoke, so you can simply use the OLE methods as methods of this class.

class WIN32OLE_EVENT
Parent:
Object
Version:
1.6

Index:

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_EVENT is used in conjunction with theWIN32OLE class 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 newWIN32OLE_EVENT (an event sink) for the givenWIN32OLE object and named event source. IfaName isnil, it will attempt to use the default source and will raise aRuntimeError if it cannot find one.

instance methods
on_event
wapi.on_event ([anEvent] ) {| args | block }
->nil
Defines a callback for the namedanEvent. IfanEvent isnil, 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:

This example is from the Ruby distribution, inext/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)

TheWin32API module allows access to any arbitrary Windows 32 function. Many of these functions take or return aPointer datatype---a region of memory corresponding to a C string or structure type.
In Ruby, these pointers are represented using classString, which contains a sequence of 8-bit bytes. It is up to you to pack and unpack the bits in theString. 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.dllname is the name of the DLL containing the function, such as ``user32'' or ``kernel32.''procname is the name of the desired function.importArray is an array of strings representing the types of arguments to the function.export is 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 tonew.

Call
wapi.Call([args]^*) ->anObject
Synonym forWin32API#call.