=pod

=head1 NAME

Win32::OLE::NEWS - What's new in Win32::OLE

This file contains a history of user visible changes to the
Win32::OLE::* modules. Only new features and major bug fixes that
might affect backwards compatibility are included.

=head1 Version 0.11 (changes since 0.1008)

=head2 new DHTML typelib browser

The Win32::OLE distribution now contains a type library browser.  It
is written in PerlScript, generating dynamic HTML.  It requires
Internet Explorer 4.0 or later.  You'll find it in
F<browser/Browser.html>.  It should be available in the ActivePerl
HTML help under Win32::OLE::Browser.

After selecting a library, type or member you can press F1 to call up
the corresponding help file at the appropriate location.

=head2 VT_DECIMAL support

The Win32::OLE::Variant module now supports VT_DECIMAL variants too.
They are not "officially" allowed in OLE Automation calls, but even
Microsoft's "ActiveX Data Objects" sometimes returns VT_DECIMAL
values.

VT_DECIMAL variables are stored as 96-bit integers scaled by a
variable power of 10.  The power of 10 scaling factor specifies the
number of digits to the right of the decimal point, and ranges from 0
to 28.  With a scale of 0 (no decimal places), the largest possible
value is +/-79,228,162,514,264,337,593,543,950,335.  With a 28 decimal
places, the largest value is +/-7.9228162514264337593543950335 and the
smallest, non-zero value is +/-0.0000000000000000000000000001.

=head1 Version 0.1008

=head2 new LetProperty() object method

In Win32::OLE property assignment using the hash syntax is equivalent
to the Visual Basic C<Set> syntax (I<by reference> assignment):

  $Object->{Property} = $OtherObject;

corresponds to this Visual Basic statement:

  Set Object.Property = OtherObject

To get the I<by value> treatment of the Visual Basic C<Let> statement

  Object.Property = OtherObject

you have to use the LetProperty() object method in Perl:

  $Object->LetProperty($Property, $OtherObject);

=head2 new HRESULT() function

The HRESULT() function converts an unsigned number into a signed HRESULT
error value as used by OLE internally. This is necessary because Perl
treats all hexadecimal constants as unsigned. To check if the last OLE
function returned "Member not found" (0x80020003) you can write:

  if (Win32::OLE->LastError == HRESULT(0x80020003)) {
      # your error recovery here
  }

=head1 Version 0.1007 (changes since 0.1005)

=head2 OLE Event support

This version of Win32::OLE contains B<ALPHA> level support for OLE events. The
userinterface is still subject to change. There are ActiveX objects / controls
that don't fire events under the current implementation.

Events are enabled for a specific object with the Win32::OLE->WithEvents()
class method:

  Win32::OLE->WithEvents(OBJECT, HANDLER, INTERFACE)

Please read further documentation in Win32::OLE.

=head2 GetObject() and GetActiveObject() now support optional DESTRUCTOR argument

It is now possible to specify a DESTRUCTOR argument to the GetObject() and
GetActiveObject() class methods. They work identical to the new() DESTRUCTOR
argument.

=head2 Remote object instantiation via DCOM

This has actually been in Win32::OLE since 0.0608, but somehow never got
documented. You can provide an array reference in place of the usual PROGID
parameter to Win32::OLE->new():

  OBJ = Win32::OLE->new([MACHINE, PRODID]);

The array must contain two elements: the name of the MACHINE and the PROGID.
This will try to create the object on the remote MACHINE.

=head2 Enumerate all Win32::OLE objects

This class method returns the number Win32::OLE objects currently in
existance. It will call the optional CALLBACK function for each of
these objects:

  $Count = Win32::OLE->EnumAllObjects(sub {
      my $Object = shift;
      my $Class = Win32::OLE->QueryObjectType($Object);
      printf "# Object=%s Class=%s\n", $Object, $Class;
  });

The EnumAllObjects() method is primarily a debugging tool. It can be
used e.g. in an END block to check if all external connections have
been properly destroyed.

=head2 The VARIANT->Put() method now returns the VARIANT object itself

This allows chaining of Put() method calls to set multiple values in an
array variant:

  $Array->Put(0,0,$First_value)->Put(0,1,$Another_value);

=head2 The VARIANT->Put(ARRAYREF) form allows assignment to a complete SAFEARRAY

This allows automatic conversion from a list of lists to a SAFEARRAY.
You can now write:

  my $Array = Variant(VT_ARRAY|VT_R8, [1,2], 2);
  $Array->Put([[1,2], [3,4]]);

instead of the tedious:

  $Array->Put(1,0,1);
  $Array->Put(1,1,2);
  $Array->Put(2,0,3);
  $Array->Put(2,1,4);

=head2 New Variant formatting methods

There are four new methods for formatting variant values: Currency(), Date(),
Number() and Time(). For example:

  my $v = Variant(VT_DATE, "April 1 99");
  print $v->Date(DATE_LONGDATE), "\n";
  print $v->Date("ddd',' MMM dd yy"), "\n";

will print:

  Thursday, April 01, 1999
  Thu, Apr 01 99

=head2 new Win32::OLE::NLS methods: SendSettingChange() and SetLocaleInfo()

SendSettingChange() sends a WM_SETTINGCHANGE message to all top level windows.

SetLocaleInfo() allows changing elements in the user override section of the
locale database. Unfortunately these changes are not automatically available
to further Variant formatting; you have to call SendSettingChange() first.

=head2 Win32::OLE::Const now correctly treats version numbers as hex

The minor and major version numbers of type libraries have been treated as
decimal. This was wrong. They are now correctly decoded as hex.

=head2 more robust global destruction of Win32::OLE objects

The final destruction of Win32::OLE objects has always been somewhat fragile.
The reason for this is that Perl doesn't honour reference counts during global
destruction but destroys objects in seemingly random order. This can lead
to leaked database connections or unterminated external objects. The only
solution was to make all objects lexical and hope that no object would be
trapped in a closure. Alternatively all objects could be explicitly set to
C<undef>, which doesn't work very well with exception handling.

With version 0.1007 of Win32::OLE this problem should be gone: The module
keeps a list of active Win32::OLE objects. It uses an END block to destroy
all objects at program termination I<before> the Perl's global destruction
starts. Objects still existing at program termination are now destroyed in
reverse order of creation. The effect is similar to explicitly calling
Win32::OLE->Uninitialize() just prior to termination.

=head1 Version 0.1005 (changes since 0.1003)

Win32::OLE 0.1005 has been release with ActivePerl build 509. It is also
included in the I<Perl Resource Kit for Win32> Update.

=head2 optional DESTRUCTOR for GetActiveObject() GetObject() class methods

The GetActiveObject() and GetObject() class method now also support an
optional DESTRUCTOR parameter just like Win32::OLE->new(). The DESTRUCTOR
is executed when the last reference to this object goes away. It is
generally considered C<impolite> to stop applications that you did not
start yourself.

=head2 new Variant object method: $object->Copy()

See L<Win32::OLE::Variant/Copy([DIM])>.

=head2 new Win32::OLE->Option() class method

The Option() class method can be used to inspect and modify
L<Win32::OLE/Module Options>. The single argument form retrieves
the value of an option:

  my $CP = Win32::OLE->Option('CP');

A single call can be used to set multiple options simultaneously:

  Win32::OLE->Option(CP => CP_ACP, Warn => 3);

Currently the following options exist: CP, LCID and C<Warn>.

=cut