<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  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/).
</copyright>
<chapter name="Microsoft Windows Support">
<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/>
<class name="WIN32OLE" super="Object" type="class">
<p/>
<codefragment>
<alltt><fullcode><![CDATA[      require 'win32ole'
      ie = WIN32OLE.new('InternetExplorer.Application')
      ie.visible = true
      ie.gohome
]]></fullcode>
require<nbsp/>'win32ole'
ie<nbsp/>=<nbsp/>WIN32OLE.new('InternetExplorer.Application')
ie.visible<nbsp/>=<nbsp/>true
ie.gohome
</alltt>
</codefragment>
<p/>
  <classname>WIN32OLE</classname> provides a client interface to Windows 32 OLE
  Automation servers.  See the tutorial description on page 166
  for more information.
<p/>
  <constants>
<tr>
  <td><constant>
       <constname>WIN32OLE::VERSION</constname>
       <constval></constval>
       <constdesc><em>Current version number</em></constdesc>
     </constant>
</td>
</tr>
</constants>
<p/>
  <methods type="class">
<p/>
        <method name="connect" ref="connect">
      <callseq>
        WIN32OLE.connect( <obj>aString</obj> )
        <returns><obj>wapi</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new OLE automation client connected to an existing instance
      of the named automation server.
<p/>
      </desc>
    </method>
<p/>
        <method name="const_load" ref="const_load">
      <callseq>
        WIN32OLE.const_load( <obj>wapi</obj>,
        <opt><obj>aClass=WIN32OLE</obj></opt> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Defines the constants from the specified automation server 
      as class constants in <obj>aClass</obj>.
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
        WIN32OLE.new( <obj>aString</obj> )
        <returns><obj>wapi</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new OLE automation client connected to a new instance
      of the automation server named by <obj>aString</obj>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="[ ]" ref="_ob_cb">
      <callseq>
        <obj>wapi</obj>[ <obj>aString</obj> ]
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the named property from the OLE automation object.
<p/>
      </desc>
    </method>
<p/>
        <method name="[ ]=" ref="_ob_cb_eq">
      <callseq>
        <obj>wapi</obj>[ <obj>aString</obj> ] = <obj>aValue</obj>
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Sets the named property in the OLE automation object.
<p/>
      </desc>
    </method>
<p/>
        <method name="each" ref="each">
      <callseq>
        <obj>wapi</obj>.each <block>{| anObj | <blockbody>block</blockbody> }</block>
<p/>
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Iterates over each item of this OLE server that supports the
      <tt>IEnumVARIANT</tt> interface.
<p/>
      </desc>
    </method>
<p/>
        <method name="invoke" ref="invoke">
      <callseq>
        <obj>wapi</obj>.invoke ( <obj>aCmdString</obj>,
        <optz><obj>args</obj></optz> )
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Invokes the command given in <obj>aCmdString</obj> with the given
      <obj>args</obj>.  <obj>args</obj> may be a <classname>Hash</classname> of named parameters
      and values.  You don't need to call <tt>invoke</tt> explicitly; this
      class uses <tt>method_missing</tt> to forward calls through
      <tt>invoke</tt>, so you can simply use the OLE methods as methods of 
      this class.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
<p/>
<class name="WIN32OLE_EVENT" super="Object" type="class">
<p/>
    This (slightly modified) example from the Win32OLE 0.1.1
    distribution shows the use of an event sink.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[      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
]]></fullcode>
require<nbsp/>'win32ole'
<p/>
$urls<nbsp/>=<nbsp/>[]
<p/>
def<nbsp/>navigate(url)
<nbsp/><nbsp/>$urls<nbsp/>&lt;&lt;<nbsp/>url
end
<p/>
def<nbsp/>stop_msg_loop
<nbsp/><nbsp/>puts<nbsp/>"IE<nbsp/>has<nbsp/>exited..."
<nbsp/><nbsp/>throw<nbsp/>:done
end
<p/>
def<nbsp/>default_handler(event,<nbsp/>*args)
<nbsp/><nbsp/>case<nbsp/>event
<nbsp/><nbsp/>when<nbsp/>"BeforeNavigate"
<nbsp/><nbsp/><nbsp/><nbsp/>puts<nbsp/>"Now<nbsp/>Navigating<nbsp/>to<nbsp/>#{args[0]}..."
<nbsp/><nbsp/>end
end
<p/>
ie<nbsp/>=<nbsp/>WIN32OLE.new('InternetExplorer.Application')
ie.visible<nbsp/>=<nbsp/>TRUE
ie.gohome
ev<nbsp/>=<nbsp/>WIN32OLE_EVENT.new(ie,<nbsp/>'DWebBrowserEvents')
<p/>
ev.on_event<nbsp/>{|*args|<nbsp/>default_handler(*args)}
ev.on_event("NavigateComplete")<nbsp/>{|url|<nbsp/>navigate(url)}
ev.on_event("Quit")<nbsp/>{|*args|<nbsp/>stop_msg_loop}
<p/>
catch(:done)<nbsp/>{
<nbsp/><nbsp/>loop<nbsp/>{
<nbsp/><nbsp/><nbsp/><nbsp/>WIN32OLE_EVENT.message_loop
<nbsp/><nbsp/>}
}
<p/>
puts<nbsp/>"You<nbsp/>Navigated<nbsp/>to<nbsp/>the<nbsp/>following<nbsp/>URLs:<nbsp/>"
$urls.each_with_index<nbsp/>do<nbsp/>|url,<nbsp/>i|
<nbsp/><nbsp/>puts<nbsp/>"(#{i+1})<nbsp/>#{url}"
end
</alltt>
</codefragment>
<p/>
<classname>WIN32OLE_EVENT</classname> is used in conjunction with the <classname>WIN32OLE</classname> class 
  to add callbacks for Windows 32 events.
  <methods type="class">
<p/>
        <method name="message_loop" ref="message_loop">
      <callseq>
        WIN32OLE_EVENT.message_loop
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Executes the Windows event loop, translating and dispatching
      events.
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
        WIN32OLE_EVENT.new ( <obj>anOle</obj>, <obj>aName</obj> )
        <returns><obj>wapi</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new <tt>WIN32OLE_EVENT</tt> (an event sink) for the given
      <tt>WIN32OLE</tt> object and named event source.  If <obj>aName</obj> is <tt>nil</tt>,
      it will attempt to use the default source and will raise a
      <exception>RuntimeError</exception> if it cannot find one.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="on_event" ref="on_event">
      <callseq>
        <obj>wapi</obj>.on_event ( <opt><obj>anEvent</obj></opt> )
        <block>{| args | <blockbody>block</blockbody> }</block>
<p/>
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Defines a callback      
      for the named <obj>anEvent</obj>.  If <obj>anEvent</obj> 
      is <tt>nil</tt>, then this callback is associated with all events.
      The block will be given any arguments appropriate for this
      event.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
<p/>
<class name="Win32API" super="Object" type="class">
<p/>
    This example is from the Ruby distribution, in
    <tt>ext/Win32API</tt>:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[      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)
]]></fullcode>
require<nbsp/>'Win32API'
<p/>
getCursorPos<nbsp/>=<nbsp/>Win32API.new("user32",<nbsp/>"GetCursorPos",<nbsp/>['P'],<nbsp/>'V')
<p/>
lpPoint<nbsp/>=<nbsp/>"<nbsp/>"<nbsp/>*<nbsp/>8<nbsp/>#<nbsp/>store<nbsp/>two<nbsp/>LONGs
getCursorPos.Call(lpPoint)
x,<nbsp/>y<nbsp/>=<nbsp/>lpPoint.unpack("LL")<nbsp/>#<nbsp/>get<nbsp/>the<nbsp/>actual<nbsp/>values
<p/>
print<nbsp/>"x:<nbsp/>",<nbsp/>x,<nbsp/>"\n"
print<nbsp/>"y:<nbsp/>",<nbsp/>y,<nbsp/>"\n"
<p/>
ods<nbsp/>=<nbsp/>Win32API.new("kernel32",<nbsp/>"OutputDebugString",<nbsp/>['P'],<nbsp/>'V')
ods.Call("Hello,<nbsp/>World\n")
<p/>
GetDesktopWindow<nbsp/>=<nbsp/>Win32API.new("user32",<nbsp/>"GetDesktopWindow",<nbsp/>[],<nbsp/>'L')
GetActiveWindow<nbsp/>=<nbsp/>Win32API.new("user32",<nbsp/>"GetActiveWindow",<nbsp/>[],<nbsp/>'L')
SendMessage<nbsp/>=<nbsp/>Win32API.new("user32",<nbsp/>"SendMessage",<nbsp/>['L']<nbsp/>*<nbsp/>4,<nbsp/>'L')
SendMessage.Call(GetDesktopWindow.Call,<nbsp/>274,<nbsp/>0xf140,<nbsp/>0)
</alltt>
</codefragment>
<p/>
  The <tt>Win32API</tt> module allows access to any arbitrary Windows 32
  function. Many of these functions take or return a <tt>Pointer</tt>
  datatype---a region of memory corresponding to a C string or
  structure type.
<p/>
  In Ruby, these pointers are represented using class <classname>String</classname>,
  which contains a sequence of 8-bit bytes.  It is up to you
  to pack and unpack the bits in the <classname>String</classname>.
  See the reference section for unpack on page 383 and
  pack on page 290 for details.
  <methods type="class">
<p/>
        <method name="new" ref="new">
      <callseq>
        Win32API.new( <obj>dllname</obj>,
    <obj>procname</obj>,
    <obj>importArray</obj>,
    <obj>export</obj> )
        <returns><obj>wapi</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new object representing a Windows 32 API function.
      <obj>dllname</obj> is the name of the DLL containing the function,
      such as ``user32'' or ``kernel32.''
      <obj>procname</obj> is the name of the desired function.
      <obj>importArray</obj> is an array of strings
      representing the types of arguments to the
      function.
      <obj>export</obj> 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/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
        <method name="call" ref="call">
      <callseq>
        <obj>wapi</obj>.call( <optz><obj>args</obj></optz> )
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Calls this API function with the given arguments, which must
      match the signature specified to <tt>new</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="Call" ref="Call">
      <callseq>
        <obj>wapi</obj>.Call( <optz><obj>args</obj></optz> )
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
    Synonym for <cim><front>Win32API</front><back>call</back></cim>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
<p/>
</chapter>
</ppdoc>