home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 June / PCWorld_2005-06_cd.bin / software / vyzkuste / firewally / firewally.exe / framework-2.3.exe / NEWS.pod < prev    next >
Text File  |  2002-07-08  |  12KB  |  333 lines
  1. =pod
  2.  
  3. =head1 NAME
  4.  
  5. Win32::OLE::NEWS - What's new in Win32::OLE
  6.  
  7. This file contains a history of user visible changes to the
  8. Win32::OLE::* modules. Only new features and major bug fixes that
  9. might affect backwards compatibility are included.
  10.  
  11. =head1 Version 0.13
  12.  
  13. =head2 nothing() method in Win32::OLE::Variant
  14.  
  15. The nothing() function returns an empty VT_DISPATCH variant.  It can be
  16. used to clear an object reference stored in a property
  17.  
  18.     use Win32::OLE::Variant qw(:DEFAULT nothing);
  19.     # ...
  20.     $object->{Property} = nothing;
  21.  
  22. This has the same effect as the Visual Basic statement
  23.  
  24.     Set object.Property = Nothing
  25.  
  26. =head2 new _NewEnum and _Unique options
  27.  
  28. There are two new options available for the Win32::OLE->Option class
  29. method: C<_NewEnum> provides the elements of a collection object
  30. directly as the value of a C<_NewEnum> property.  The C<_Unique>
  31. option guarantees that Win32::OLE will not create multiple proxy
  32. objects for the same underlying COM/OLE object.
  33.  
  34. Both options are only really useful to tree traversal programs or
  35. during debugging.
  36.  
  37.  
  38. =head1 Version 0.12
  39.  
  40. =head2 Additional error handling functionality
  41.  
  42. The Warn option can now be set to a CODE reference too.  For example,
  43.  
  44.     Win32::OLE->Option(Warn => 3);
  45.  
  46. could now be written as
  47.  
  48.     Win32::OLE->Option(Warn => \&Carp::croak);
  49.  
  50. This can even be used to emulate the VisualBasic C<On Error Goto
  51. Label> construct:
  52.  
  53.     Win32::OLE->Option(Warn =>  sub {goto CheckError});
  54.     # ... your normal OLE code here ...
  55.  
  56.   CheckError:
  57.     # ... your error handling code here ...
  58.  
  59. =head2 Builtin event loop
  60.  
  61. Processing OLE events required a polling loop before, e.g.
  62.  
  63.     my $Quit;
  64.     #...
  65.     until ($Quit) {
  66.         Win32::OLE->SpinMessageLoop;
  67.         Win32::Sleep(100);
  68.     }
  69.     package BrowserEvents;
  70.     sub OnQuit { $Quit = 1 }
  71.  
  72. This is inefficient and a bit odd.  This version of Win32::OLE now
  73. supports a standard messageloop:
  74.  
  75.     Win32::OLE->MessageLoop();
  76.  
  77.     package BrowserEvents;
  78.     sub OnQuit { Win32::OLE->QuitMessageLoop }
  79.  
  80. =head2 Free unused OLE libraries
  81.  
  82. Previous versions of Win32::OLE would call the CoFreeUnusedLibraries()
  83. API whenever an OLE object was destroyed.  This made sure that OLE
  84. libraries would be unloaded as soon as they were no longer needed.
  85. Unfortunately, objects implemented in Visual Basic tend to crash
  86. during this call, as they pretend to be ready for unloading, when in
  87. fact, they aren't.
  88.  
  89. The unloading of object libraries is really only important for long
  90. running processes that might instantiate a huge number of B<different>
  91. objects over time.  Therefore this API is no longer called
  92. automatically.  The functionality is now available explicitly to those
  93. who want or need it by calling a Win32::OLE class method:
  94.  
  95.     Win32::OLE->FreeUnusedLibraries();
  96.  
  97. =head2 The "Win32::OLE" article from "The Perl Journal #10"
  98.  
  99. The article is Copyright 1998 by I<The Perl
  100. Journal>. http://www.tpj.com
  101.  
  102. It originally appeared in I<The Perl Journal> # 10 and appears here
  103. courtesy of Jon Orwant and I<The Perl Journal>.  The sample code from
  104. the article is in the F<eg/tpj.pl> file.
  105.  
  106. =head2 VARIANT->Put() bug fixes
  107.  
  108. The Put() method didn't work correctly for arrays of type VT_BSTR,
  109. VT_DISPATH or VT_UNKNOWN.  This has been fixed.
  110.  
  111. =head2 Error message fixes
  112.  
  113. Previous versions of Win32::OLE gave a wrong argument index for some
  114. OLE error messages (the number was too large by 1).  This should be
  115. fixed now.
  116.  
  117. =head2 VT_DATE and VT_ERROR return values handled differently
  118.  
  119. Method calls and property accesses returning a VT_DATE or VT_ERROR
  120. value would previously translate the value to string or integer
  121. format.  This has been changed to return a Win32::OLE::Variant object.
  122. The return values will behave as before if the Win32::OLE::Variant
  123. module is being used.  This module overloads the conversion of
  124. the objects to strings and numbers.
  125.  
  126.  
  127. =head1 Version 0.11 (changes since 0.1008)
  128.  
  129. =head2 new DHTML typelib browser
  130.  
  131. The Win32::OLE distribution now contains a type library browser.  It
  132. is written in PerlScript, generating dynamic HTML.  It requires
  133. Internet Explorer 4.0 or later.  You'll find it in
  134. F<browser/Browser.html>.  It should be available in the ActivePerl
  135. HTML help under Win32::OLE::Browser.
  136.  
  137. After selecting a library, type or member you can press F1 to call up
  138. the corresponding help file at the appropriate location.
  139.  
  140. =head2 VT_DECIMAL support
  141.  
  142. The Win32::OLE::Variant module now supports VT_DECIMAL variants too.
  143. They are not "officially" allowed in OLE Automation calls, but even
  144. Microsoft's "ActiveX Data Objects" sometimes returns VT_DECIMAL
  145. values.
  146.  
  147. VT_DECIMAL variables are stored as 96-bit integers scaled by a
  148. variable power of 10.  The power of 10 scaling factor specifies the
  149. number of digits to the right of the decimal point, and ranges from 0
  150. to 28.  With a scale of 0 (no decimal places), the largest possible
  151. value is +/-79,228,162,514,264,337,593,543,950,335.  With a 28 decimal
  152. places, the largest value is +/-7.9228162514264337593543950335 and the
  153. smallest, non-zero value is +/-0.0000000000000000000000000001.
  154.  
  155. =head1 Version 0.1008
  156.  
  157. =head2 new LetProperty() object method
  158.  
  159. In Win32::OLE property assignment using the hash syntax is equivalent
  160. to the Visual Basic C<Set> syntax (I<by reference> assignment):
  161.  
  162.   $Object->{Property} = $OtherObject;
  163.  
  164. corresponds to this Visual Basic statement:
  165.  
  166.   Set Object.Property = OtherObject
  167.  
  168. To get the I<by value> treatment of the Visual Basic C<Let> statement
  169.  
  170.   Object.Property = OtherObject
  171.  
  172. you have to use the LetProperty() object method in Perl:
  173.  
  174.   $Object->LetProperty($Property, $OtherObject);
  175.  
  176. =head2 new HRESULT() function
  177.  
  178. The HRESULT() function converts an unsigned number into a signed HRESULT
  179. error value as used by OLE internally. This is necessary because Perl
  180. treats all hexadecimal constants as unsigned. To check if the last OLE
  181. function returned "Member not found" (0x80020003) you can write:
  182.  
  183.   if (Win32::OLE->LastError == HRESULT(0x80020003)) {
  184.       # your error recovery here
  185.   }
  186.  
  187. =head1 Version 0.1007 (changes since 0.1005)
  188.  
  189. =head2 OLE Event support
  190.  
  191. This version of Win32::OLE contains B<ALPHA> level support for OLE events. The
  192. userinterface is still subject to change. There are ActiveX objects / controls
  193. that don't fire events under the current implementation.
  194.  
  195. Events are enabled for a specific object with the Win32::OLE->WithEvents()
  196. class method:
  197.  
  198.   Win32::OLE->WithEvents(OBJECT, HANDLER, INTERFACE)
  199.  
  200. Please read further documentation in Win32::OLE.
  201.  
  202. =head2 GetObject() and GetActiveObject() now support optional DESTRUCTOR argument
  203.  
  204. It is now possible to specify a DESTRUCTOR argument to the GetObject() and
  205. GetActiveObject() class methods. They work identical to the new() DESTRUCTOR
  206. argument.
  207.  
  208. =head2 Remote object instantiation via DCOM
  209.  
  210. This has actually been in Win32::OLE since 0.0608, but somehow never got
  211. documented. You can provide an array reference in place of the usual PROGID
  212. parameter to Win32::OLE->new():
  213.  
  214.   OBJ = Win32::OLE->new([MACHINE, PRODID]);
  215.  
  216. The array must contain two elements: the name of the MACHINE and the PROGID.
  217. This will try to create the object on the remote MACHINE.
  218.  
  219. =head2 Enumerate all Win32::OLE objects
  220.  
  221. This class method returns the number Win32::OLE objects currently in
  222. existance. It will call the optional CALLBACK function for each of
  223. these objects:
  224.  
  225.   $Count = Win32::OLE->EnumAllObjects(sub {
  226.       my $Object = shift;
  227.       my $Class = Win32::OLE->QueryObjectType($Object);
  228.       printf "# Object=%s Class=%s\n", $Object, $Class;
  229.   });
  230.  
  231. The EnumAllObjects() method is primarily a debugging tool. It can be
  232. used e.g. in an END block to check if all external connections have
  233. been properly destroyed.
  234.  
  235. =head2 The VARIANT->Put() method now returns the VARIANT object itself
  236.  
  237. This allows chaining of Put() method calls to set multiple values in an
  238. array variant:
  239.  
  240.   $Array->Put(0,0,$First_value)->Put(0,1,$Another_value);
  241.  
  242. =head2 The VARIANT->Put(ARRAYREF) form allows assignment to a complete SAFEARRAY
  243.  
  244. This allows automatic conversion from a list of lists to a SAFEARRAY.
  245. You can now write:
  246.  
  247.   my $Array = Variant(VT_ARRAY|VT_R8, [1,2], 2);
  248.   $Array->Put([[1,2], [3,4]]);
  249.  
  250. instead of the tedious:
  251.  
  252.   $Array->Put(1,0,1);
  253.   $Array->Put(1,1,2);
  254.   $Array->Put(2,0,3);
  255.   $Array->Put(2,1,4);
  256.  
  257. =head2 New Variant formatting methods
  258.  
  259. There are four new methods for formatting variant values: Currency(), Date(),
  260. Number() and Time(). For example:
  261.  
  262.   my $v = Variant(VT_DATE, "April 1 99");
  263.   print $v->Date(DATE_LONGDATE), "\n";
  264.   print $v->Date("ddd',' MMM dd yy"), "\n";
  265.  
  266. will print:
  267.  
  268.   Thursday, April 01, 1999
  269.   Thu, Apr 01 99
  270.  
  271. =head2 new Win32::OLE::NLS methods: SendSettingChange() and SetLocaleInfo()
  272.  
  273. SendSettingChange() sends a WM_SETTINGCHANGE message to all top level windows.
  274.  
  275. SetLocaleInfo() allows changing elements in the user override section of the
  276. locale database. Unfortunately these changes are not automatically available
  277. to further Variant formatting; you have to call SendSettingChange() first.
  278.  
  279. =head2 Win32::OLE::Const now correctly treats version numbers as hex
  280.  
  281. The minor and major version numbers of type libraries have been treated as
  282. decimal. This was wrong. They are now correctly decoded as hex.
  283.  
  284. =head2 more robust global destruction of Win32::OLE objects
  285.  
  286. The final destruction of Win32::OLE objects has always been somewhat fragile.
  287. The reason for this is that Perl doesn't honour reference counts during global
  288. destruction but destroys objects in seemingly random order. This can lead
  289. to leaked database connections or unterminated external objects. The only
  290. solution was to make all objects lexical and hope that no object would be
  291. trapped in a closure. Alternatively all objects could be explicitly set to
  292. C<undef>, which doesn't work very well with exception handling.
  293.  
  294. With version 0.1007 of Win32::OLE this problem should be gone: The module
  295. keeps a list of active Win32::OLE objects. It uses an END block to destroy
  296. all objects at program termination I<before> the Perl's global destruction
  297. starts. Objects still existing at program termination are now destroyed in
  298. reverse order of creation. The effect is similar to explicitly calling
  299. Win32::OLE->Uninitialize() just prior to termination.
  300.  
  301. =head1 Version 0.1005 (changes since 0.1003)
  302.  
  303. Win32::OLE 0.1005 has been release with ActivePerl build 509. It is also
  304. included in the I<Perl Resource Kit for Win32> Update.
  305.  
  306. =head2 optional DESTRUCTOR for GetActiveObject() GetObject() class methods
  307.  
  308. The GetActiveObject() and GetObject() class method now also support an
  309. optional DESTRUCTOR parameter just like Win32::OLE->new(). The DESTRUCTOR
  310. is executed when the last reference to this object goes away. It is
  311. generally considered C<impolite> to stop applications that you did not
  312. start yourself.
  313.  
  314. =head2 new Variant object method: $object->Copy()
  315.  
  316. See L<Win32::OLE::Variant/Copy([DIM])>.
  317.  
  318. =head2 new Win32::OLE->Option() class method
  319.  
  320. The Option() class method can be used to inspect and modify
  321. L<Win32::OLE/Module Options>. The single argument form retrieves
  322. the value of an option:
  323.  
  324.   my $CP = Win32::OLE->Option('CP');
  325.  
  326. A single call can be used to set multiple options simultaneously:
  327.  
  328.   Win32::OLE->Option(CP => CP_ACP, Warn => 3);
  329.  
  330. Currently the following options exist: CP, LCID and C<Warn>.
  331.  
  332. =cut
  333.