Programming Ruby
The Pragmatic Programmer's Guide
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
WIN32OLE provides a client interface to Windows 32 OLE
Automation servers. See the tutorial description on page 164
for more information.
constants
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 in
aClass.
new
WIN32OLE.new(
aString )
->
wapi
Returns a new OLE automation client connected to a new instance
of the automation server named by
aString.
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 in
aCmdString with the given
args.
args may 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_EVENT is used in conjunction with the
WIN32OLE class
to add callbacks for Windows 32 events.
class methods
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. If
aName is
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 named
anEvent. If
anEvent
is
nil, 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
Win32API module allows access to any arbitrary Windows 32
function. Many of these functions take or return a
Pointer
datatype---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.
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 to
new.
Call
wapi.Call(
[
args
]*
)
->
anObject
Synonym for
Win32API#call.
Extracted from the book "Programming Ruby -
The Pragmatic Programmer's Guide"
Copyright
©
2001 by Addison Wesley Longman, Inc. This material may
be distributed only subject to the terms and conditions set forth in
the Open Publication License, v1.0 or later (the latest version is
presently available at
http://www.opencontent.org/openpub/)).
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
Distribution of the work or derivative of the work in any standard
(paper) book form is prohibited unless prior permission is obtained
from the copyright holder.