<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Programming Ruby: The Pragmatic Programmer's Guide</title>
<link rel="StyleSheet" href="pr_style.css" type="text/css" media="screen">
</head>
<body bgcolor="white">
<table bgcolor="#c09090" cellpadding="3" border="0" cellspacing="0" width="100%">
<tr>
<td colspan="3">
<table bgcolor="#701a1a" cellpadding="20" width="100%">
<tr>
<td width="6in">
<h1 class="header">Programming Ruby</h1>
<h3 class="subheader">The Pragmatic Programmer's Guide</h3>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td width="33%" align="left">
<a class="subheader" href="lib_network.html">Previous <</a>
</td>
<td width="33%" align="center" valign="middle">
<a class="subheader" href="index.html">Contents ^</a>
<br>
</td>
<td width="33%" align="right">
<a class="subheader" href="rdtool.html">Next ></a>
<br>
</td>
</tr>
</table>
<!--
Copyright (c) 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/).
<P></P>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<P></P>
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.
-->
<h1>Microsoft Windows Support</h1>
<hr>
<br>
<P></P>
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.
<P></P>
<table>
<tr>
<td height="20"><img src="dot.gif" width="1" height="20"></td>
</tr>
</table>
<table border="0" width="100%" bgcolor="660066" cellpadding="10">
<tr>
<td valign="center">
<font color="white" size="7">class WIN32OLE</font>
</td>
<td>
<table border="0">
<tr>
<td>
<font color="white">
Parent:
</font>
</td>
<td>
<font color="white">Object</font>
</td>
</tr>
<tr>
<td>
<font color="white">
Version:
</font>
</td>
<td>
<font color="white">
1.6
</font>
</td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<H3>Index:</H3>
<a href="#WIN32OLE.connect">connect</a>
<a href="#WIN32OLE.const_load">const_load</a>
<a href="#WIN32OLE.new">new</a>
<i>
<a href="#WIN32OLE._ob_cb">[ ]</a>
</i> <i>
<a href="#WIN32OLE._ob_cb_eq">[ ]=</a>
</i> <i>
<a href="#WIN32OLE.each">each</a>
</i> <i>
<a href="#WIN32OLE.invoke">invoke</a>
</i> <p></p>
<hr>
<P></P>
<table class="codebox" cellspacing="0" border="0" cellpadding="3" width="400">
<tr>
<td>
<pre>
require 'win32ole'
ie = WIN32OLE.new('InternetExplorer.Application')
ie.visible = true
ie.gohome
</pre>
</td>
</tr>
</table>
<P></P>
<code>WIN32OLE</code> provides a client interface to Windows 32 OLE
Automation servers. See the tutorial description on page 164
for more information.
<P></P>
<table border="0" width="100%" cellpadding="10">
<tr>
<td valign="center" colspan="3" bgcolor="990066">
<font color="white" size="6">
constants
</font>
</td>
</tr>
</table>
<table border="2" cellpadding="5">
<tr>
<td valign="top">
<tr>
<td>
<a name="WIN32OLE.WIN32OLE::VERSION">
<code>WIN32OLE::VERSION</code>
</a>
</td>
<td></td>
<td>
<em>Current version number</em>
</td>
</tr>
</td>
</tr>
</table>
<p></p>
<P></P>
<table border="0" width="100%" cellpadding="10">
<tr>
<td valign="center" colspan="2" bgcolor="990066">
<font color="white" size="6">class methods
</font>
</td>
</tr>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE.connect">connect</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
WIN32OLE.connect( <i>aString</i> )
-> <i>wapi</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Returns a new OLE automation client connected to an existing instance
of the named automation server.
<P></P>
</td>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE.const_load">const_load</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
WIN32OLE.const_load( <i>wapi</i>,
<i>[</i>
<i>aClass=WIN32OLE</i>
<i>]</i> )
-> <code>nil</code>
</td>
</tr>
<td></td>
<td>
<P></P>
Defines the constants from the specified automation server
as class constants in <i>aClass</i>.
<P></P>
</td>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE.new">new</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
WIN32OLE.new( <i>aString</i> )
-> <i>wapi</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Returns a new OLE automation client connected to a new instance
of the automation server named by <i>aString</i>.
<P></P>
</td>
</table>
<P></P>
<table border="0" width="100%" cellpadding="10">
<tr>
<td valign="center" colspan="2" bgcolor="990066">
<font color="white" size="6">instance methods
</font>
</td>
</tr>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE._ob_cb">[ ]</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
<i>wapi</i>[ <i>aString</i> ]
-> <i>anObject</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Returns the named property from the OLE automation object.
<P></P>
</td>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE._ob_cb_eq">[ ]=</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
<i>wapi</i>[ <i>aString</i> ] = <i>aValue</i>
-> <code>nil</code>
</td>
</tr>
<td></td>
<td>
<P></P>
Sets the named property in the OLE automation object.
<P></P>
</td>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE.each">each</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
<i>wapi</i>.each {| anObj | block }
<P></P>
-> <code>nil</code>
</td>
</tr>
<td></td>
<td>
<P></P>
Iterates over each item of this OLE server that supports the
<code>IEnumVARIANT</code> interface.
<P></P>
</td>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE.invoke">invoke</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
<i>wapi</i>.invoke ( <i>aCmdString</i>,
<i>[</i>
<i>args</i>
<i>]<sup>*</sup>
</i> )
-> <i>anObject</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Invokes the command given in <i>aCmdString</i> with the given
<i>args</i>. <i>args</i> may be a <code>Hash</code> of named parameters
and values. You don't need to call <code>invoke</code> explicitly; this
class uses <code>method_missing</code> to forward calls through
<code>invoke</code>, so you can simply use the OLE methods as methods of
this class.
<P></P>
</td>
</table>
<P></P>
<P></P>
<table>
<tr>
<td height="20"><img src="dot.gif" width="1" height="20"></td>
</tr>
</table>
<table border="0" width="100%" bgcolor="660066" cellpadding="10">
<tr>
<td valign="center">
<font color="white" size="7">class WIN32OLE_EVENT</font>
</td>
<td>
<table border="0">
<tr>
<td>
<font color="white">
Parent:
</font>
</td>
<td>
<font color="white">Object</font>
</td>
</tr>
<tr>
<td>
<font color="white">
Version:
</font>
</td>
<td>
<font color="white">
1.6
</font>
</td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<H3>Index:</H3>
<a href="#WIN32OLE_EVENT.message_loop">message_loop</a>
<a href="#WIN32OLE_EVENT.new">new</a>
<i>
<a href="#WIN32OLE_EVENT.on_event">on_event</a>
</i> <p></p>
<hr>
<P></P>
This (slightly modified) example from the Win32OLE 0.1.1
distribution shows the use of an event sink.
<P></P>
<table class="codebox" cellspacing="0" border="0" cellpadding="3" width="400">
<tr>
<td>
<pre>
require 'win32ole'
<P></P>
$urls = []
<P></P>
def navigate(url)
$urls << url
end
<P></P>
def stop_msg_loop
puts "IE has exited..."
throw :done
end
<P></P>
def default_handler(event, *args)
case event
when "BeforeNavigate"
puts "Now Navigating to #{args[0]}..."
end
end
<P></P>
ie = WIN32OLE.new('InternetExplorer.Application')
ie.visible = TRUE
ie.gohome
ev = WIN32OLE_EVENT.new(ie, 'DWebBrowserEvents')
<P></P>
ev.on_event {|*args| default_handler(*args)}
ev.on_event("NavigateComplete") {|url| navigate(url)}
ev.on_event("Quit") {|*args| stop_msg_loop}
<P></P>
catch(:done) {
loop {
WIN32OLE_EVENT.message_loop
}
}
<P></P>
puts "You Navigated to the following URLs: "
$urls.each_with_index do |url, i|
puts "(#{i+1}) #{url}"
end
</pre>
</td>
</tr>
</table>
<P></P>
<code>WIN32OLE_EVENT</code> is used in conjunction with the <code>WIN32OLE</code> class
to add callbacks for Windows 32 events.
<table border="0" width="100%" cellpadding="10">
<tr>
<td valign="center" colspan="2" bgcolor="990066">
<font color="white" size="6">class methods
</font>
</td>
</tr>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE_EVENT.message_loop">message_loop</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
WIN32OLE_EVENT.message_loop
-> <code>nil</code>
</td>
</tr>
<td></td>
<td>
<P></P>
Executes the Windows event loop, translating and dispatching
events.
<P></P>
</td>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE_EVENT.new">new</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
WIN32OLE_EVENT.new ( <i>anOle</i>, <i>aName</i> )
-> <i>wapi</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Returns a new <code>WIN32OLE_EVENT</code> (an event sink) for the given
<code>WIN32OLE</code> object and named event source. If <i>aName</i> is <code>nil</code>,
it will attempt to use the default source and will raise a
<code>RuntimeError</code> if it cannot find one.
<P></P>
</td>
</table>
<P></P>
<table border="0" width="100%" cellpadding="10">
<tr>
<td valign="center" colspan="2" bgcolor="990066">
<font color="white" size="6">instance methods
</font>
</td>
</tr>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="WIN32OLE_EVENT.on_event">on_event</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
<i>wapi</i>.on_event ( <i>[</i>
<i>anEvent</i>
<i>]</i> )
{| args | block }
<P></P>
-> <code>nil</code>
</td>
</tr>
<td></td>
<td>
<P></P>
Defines a callback
for the named <i>anEvent</i>. If <i>anEvent</i>
is <code>nil</code>, then this callback is associated with all events.
The block will be given any arguments appropriate for this
event.
<P></P>
</td>
</table>
<P></P>
<P></P>
<table>
<tr>
<td height="20"><img src="dot.gif" width="1" height="20"></td>
</tr>
</table>
<table border="0" width="100%" bgcolor="660066" cellpadding="10">
<tr>
<td valign="center">
<font color="white" size="7">class Win32API</font>
</td>
<td>
<table border="0">
<tr>
<td>
<font color="white">
Parent:
</font>
</td>
<td>
<font color="white">Object</font>
</td>
</tr>
<tr>
<td>
<font color="white">
Version:
</font>
</td>
<td>
<font color="white">
1.6
</font>
</td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<H3>Index:</H3>
<a href="#Win32API.new">new</a>
<i>
<a href="#Win32API.call">call</a>
</i> <i>
<a href="#Win32API.Call">Call</a>
</i> <p></p>
<hr>
<P></P>
This example is from the Ruby distribution, in
<code>ext/Win32API</code>:
<P></P>
<table class="codebox" cellspacing="0" border="0" cellpadding="3" width="400">
<tr>
<td>
<pre>
require 'Win32API'
<P></P>
getCursorPos = Win32API.new("user32", "GetCursorPos", ['P'], 'V')
<P></P>
lpPoint = " " * 8 # store two LONGs
getCursorPos.Call(lpPoint)
x, y = lpPoint.unpack("LL") # get the actual values
<P></P>
print "x: ", x, "\n"
print "y: ", y, "\n"
<P></P>
ods = Win32API.new("kernel32", "OutputDebugString", ['P'], 'V')
ods.Call("Hello, World\n")
<P></P>
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)
</pre>
</td>
</tr>
</table>
<P></P>
The <code>Win32API</code> module allows access to any arbitrary Windows 32
function. Many of these functions take or return a <code>Pointer</code>
datatype---a region of memory corresponding to a C string or
structure type.
<P></P>
In Ruby, these pointers are represented using class <code>String</code>,
which contains a sequence of 8-bit bytes. It is up to you
to pack and unpack the bits in the <code>String</code>.
See the reference section for unpack on page 378 and
pack on page 286 for details.
<table border="0" width="100%" cellpadding="10">
<tr>
<td valign="center" colspan="2" bgcolor="990066">
<font color="white" size="6">class methods
</font>
</td>
</tr>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="Win32API.new">new</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
Win32API.new( <i>dllname</i>,
<i>procname</i>,
<i>importArray</i>,
<i>export</i> )
-> <i>wapi</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Returns a new object representing a Windows 32 API function.
<i>dllname</i> is the name of the DLL containing the function,
such as ``user32'' or ``kernel32.''
<i>procname</i> is the name of the desired function.
<i>importArray</i> is an array of strings
representing the types of arguments to the
function.
<i>export</i> 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.
<P></P>
</td>
</table>
<P></P>
<table border="0" width="100%" cellpadding="10">
<tr>
<td valign="center" colspan="2" bgcolor="990066">
<font color="white" size="6">instance methods
</font>
</td>
</tr>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="Win32API.call">call</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
<i>wapi</i>.call( <i>[</i>
<i>args</i>
<i>]<sup>*</sup>
</i> )
-> <i>anObject</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Calls this API function with the given arguments, which must
match the signature specified to <code>new</code>.
<P></P>
</td>
<tr>
<td valign="center" bgcolor="#ff9999">
<font size="4">
<b>
<a name="Win32API.Call">Call</a>
</b>
</font>
</td>
<td bgcolor="#ffaaaa">
<i>wapi</i>.Call( <i>[</i>
<i>args</i>
<i>]<sup>*</sup>
</i> )
-> <i>anObject</i>
</td>
</tr>
<td></td>
<td>
<P></P>
Synonym for <code>Win32API#call</code>.
<P></P>
</td>
</table>
<P></P>
<P></P>
<p></p>
<hr>
<table bgcolor="#a03030" cellpadding="10" border="0" cellspacing="0">
<tr>
<td width="33%" align="left">
<a class="subheader" href="lib_network.html">Previous <</a>
</td>
<td width="33%" align="center" valign="middle">
<a class="subheader" href="index.html">Contents ^</a>
<br>
</td>
<td width="33%" align="right">
<a class="subheader" href="rdtool.html">Next ></a>
<br>
</td>
</tr>
</table>
<p></p>
<font size="-1">Extracted from the book "Programming Ruby -
The Pragmatic Programmer's Guide"</font>
<br>
<font size="-3">
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
<a href="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</a>)).
<p></p>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p></p>
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.
<br>
</font>
</body>
</html>
