# NAME

oleauto - OLE Automation extensions

# DESCRIPTION

OLE Automation provides Visual Basic-like scripting capabilities to Perl 5 under Windows NT or Windows 95, exploiting the object-oriented programming facilities of Perl 5.

The OLE Automation extensions have been completely rewritten since the previous major version of Perl for Win32 (09x), resulting in a much cleaner syntax and added support for embedded objects (no more MkOLEx kludges!). OCX's are currently not supported, nor are VBX's.

## Syntax

A simple Microsoft Excel application:

            use OLE;
            $excel = CreateObject OLE 'Excel.Application.5'
                   or warn "Couldn't create new instance of Excel App!!";
            $excel->Workbooks->Open( 'test.xls' );
            $excel->Workbooks(1)->Worksheets('Sheet1')->Cells(1,2)->{Value} = 'foo';
            $excel->Workbooks(1)->Worksheets('Sheet1')->Cells(1,2)->{Value} = 'bar';
            $excel->Save();
            $excel->Quit();

OLE Automation objects are created using the `CreateObject` method of the `OLE` module. The name of the class of OLE object to create is supplied as the only argument. On success, the handle to the object is returned, otherwise undef is returned.

            $object = CreateObject OLE $class
                    or warn "Couldn't create instant of $class!!\n";

To invoke methods or retrieve properties within the object, one then uses the standard Perl 5 O-O syntax. Arguments must be supplied in the correct order (usually in the order that they are listed in the documentation associated with a particular class. e.g. in the help files for Microsoft Excel).

            $object->wave();
            $object->say_hello();

Properties are also accessible via the perl object's hash structure. Since the return value of a function cannot be treated as an lvalue, the hash is the only means by which we can modify an object's properties.

            print "I weigh this many pounds: ",
                    $object->{weight}, "\n";
            $object->{weight} -= 25;
            print "Hey, I lost 25 pounds, I now weigh this many pounds: ",
                    $object->{weight}, "\n";

If a method or a property returns an embedded OLE object, it can automatically be treated as a perl object itself. E.g.

            $object->dad->grandad->tell_old_war_stories();

...will invoke the method `tell_old_war_stories` in `grandad` which is an embedded object within `dad`, which itself is an embedded object in `$object`. The same goes for properties:

            print "My girlfriend weighs this many pounds: ",
                    $object->girlfriend->{weight}, "\n";
            $object->girlfriend->{weight} -= 25;
            print "Hey, she lost 25 pounds, she now weigh this many pounds: ",
                    $object->girlfriend->{weight}, "\n";

Simple as Pie!!

## Note to previous users of NT Perl

Since the OLE Automation scheme has been completely revised, none of the former constructs have to be used. There is no need for `MkOLEx`, and there is only one `OLE` module for all OLE Automation objects (i.e. no need to use the module `OLE::Word_Basic` etc).