Programming Ruby: The Pragmatic Programmer's Guide

# Programming Ruby ### The Pragmatic Programmer's Guide
Previous < | Contents ^ | Next >

# 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

`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 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
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. 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`.

Previous < | Contents ^ | Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0.
This reference is available for download.