diff options
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/Win32/OLE/NEWS.pod')
-rw-r--r-- | Master/tlpkg/tlperl/site/lib/Win32/OLE/NEWS.pod | 380 |
1 files changed, 0 insertions, 380 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/Win32/OLE/NEWS.pod b/Master/tlpkg/tlperl/site/lib/Win32/OLE/NEWS.pod deleted file mode 100644 index 217fe4a6fcc..00000000000 --- a/Master/tlpkg/tlperl/site/lib/Win32/OLE/NEWS.pod +++ /dev/null @@ -1,380 +0,0 @@ -=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.18 - -=head2 VT_CY and VT_DECIMAL return values handled differently - -The new C<Variant> option enables values of VT_CY or VT_DECIMAL type -to be returned as Win32::OLE::Variant objects instead of being -converted into strings and numbers respectively. This is similar to -the change in Win32::OLE version 0.12 to VT_DATE and VT_ERROR values. -The Win32::OLE::Variant module must be included to make sure that -VT_CY and VT_DECIMAL values behave as before in numeric or string -contexts. - -Because the new behavior is potentially incompatible, it must be -explicitly enabled: - - Win32::OLE->Option(Variant => 1); - - -=head1 Version 0.17 - -=head2 New nullstring() function in Win32::OLE::Variant - -The nullstring() function returns a VT_BSTR variant containing a NULL -string pointer. Note that this is not the same as a VT_BSTR variant -containing the empty string "". - -The nullstring() return value is equivalent to the Visual Basic -C<vbNullString> constant. - - -=head1 Version 0.16 - -=head2 Improved Unicode support - -Passing Unicode strings to methods and properties as well as returning -Unicode strings back to Perl works now with both Perl 5.6 and 5.8. -Note that the Unicode support in 5.8 is much more complete than in 5.6 -or 5.6.1. - -C<Unicode::String> objects can now be passed to methods or assigned to -properties. - -You must enable Unicode support by switching Win32::OLE to the UTF8 -codepage: - - Win32::OLE->Option(CP => Win32::OLE::CP_UTF8()); - - -=head1 Version 0.13 - -=head2 New nothing() function in Win32::OLE::Variant - -The nothing() function returns an empty VT_DISPATCH variant. It can be -used to clear an object reference stored in a property - - use Win32::OLE::Variant qw(:DEFAULT nothing); - # ... - $object->{Property} = nothing; - -This has the same effect as the Visual Basic statement - - Set object.Property = Nothing - -=head2 New _NewEnum and _Unique options - -There are two new options available for the Win32::OLE->Option class -method: C<_NewEnum> provides the elements of a collection object -directly as the value of a C<_NewEnum> property. The C<_Unique> -option guarantees that Win32::OLE will not create multiple proxy -objects for the same underlying COM/OLE object. - -Both options are only really useful to tree traversal programs or -during debugging. - - -=head1 Version 0.12 - -=head2 Additional error handling functionality - -The Warn option can now be set to a CODE reference too. For example, - - Win32::OLE->Option(Warn => 3); - -could now be written as - - Win32::OLE->Option(Warn => \&Carp::croak); - -This can even be used to emulate the VisualBasic C<On Error Goto -Label> construct: - - Win32::OLE->Option(Warn => sub {goto CheckError}); - # ... your normal OLE code here ... - - CheckError: - # ... your error handling code here ... - -=head2 Builtin event loop - -Processing OLE events required a polling loop before, e.g. - - my $Quit; - #... - until ($Quit) { - Win32::OLE->SpinMessageLoop; - Win32::Sleep(100); - } - package BrowserEvents; - sub OnQuit { $Quit = 1 } - -This is inefficient and a bit odd. This version of Win32::OLE now -supports a standard messageloop: - - Win32::OLE->MessageLoop(); - - package BrowserEvents; - sub OnQuit { Win32::OLE->QuitMessageLoop } - -=head2 Free unused OLE libraries - -Previous versions of Win32::OLE would call the CoFreeUnusedLibraries() -API whenever an OLE object was destroyed. This made sure that OLE -libraries would be unloaded as soon as they were no longer needed. -Unfortunately, objects implemented in Visual Basic tend to crash -during this call, as they pretend to be ready for unloading, when in -fact, they aren't. - -The unloading of object libraries is really only important for long -running processes that might instantiate a huge number of B<different> -objects over time. Therefore this API is no longer called -automatically. The functionality is now available explicitly to those -who want or need it by calling a Win32::OLE class method: - - Win32::OLE->FreeUnusedLibraries(); - -=head2 The "Win32::OLE" article from "The Perl Journal #10" - -The article is Copyright 1998 by I<The Perl -Journal>. http://www.tpj.com - -It originally appeared in I<The Perl Journal> # 10 and appears here -courtesy of Jon Orwant and I<The Perl Journal>. The sample code from -the article is in the F<eg/tpj.pl> file. - -=head2 VARIANT->Put() bug fixes - -The Put() method didn't work correctly for arrays of type VT_BSTR, -VT_DISPATH or VT_UNKNOWN. This has been fixed. - -=head2 Error message fixes - -Previous versions of Win32::OLE gave a wrong argument index for some -OLE error messages (the number was too large by 1). This should be -fixed now. - -=head2 VT_DATE and VT_ERROR return values handled differently - -Method calls and property accesses returning a VT_DATE or VT_ERROR -value would previously translate the value to string or integer -format. This has been changed to return a Win32::OLE::Variant object. -The return values will behave as before if the Win32::OLE::Variant -module is being used. This module overloads the conversion of -the objects to strings and numbers. - - -=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 -user interface 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 -existence. 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 |