diff options
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/Win32/OLE/Variant.pm')
| -rw-r--r-- | Master/tlpkg/tlperl/site/lib/Win32/OLE/Variant.pm | 577 |
1 files changed, 0 insertions, 577 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/Win32/OLE/Variant.pm b/Master/tlpkg/tlperl/site/lib/Win32/OLE/Variant.pm deleted file mode 100644 index 38fc6048209..00000000000 --- a/Master/tlpkg/tlperl/site/lib/Win32/OLE/Variant.pm +++ /dev/null @@ -1,577 +0,0 @@ -# The documentation is at the __END__ - -package Win32::OLE::Variant; -require Win32::OLE; # Make sure the XS bootstrap has been called - -use strict; -use vars qw(@ISA @EXPORT @EXPORT_OK); - -use Exporter; -@ISA = qw(Exporter); - -@EXPORT = qw( - Variant - VT_EMPTY VT_NULL VT_I2 VT_I4 VT_R4 VT_R8 VT_CY VT_DATE VT_BSTR - VT_DISPATCH VT_ERROR VT_BOOL VT_VARIANT VT_UNKNOWN VT_DECIMAL VT_UI1 - VT_ARRAY VT_BYREF - ); - -@EXPORT_OK = qw(CP_ACP CP_OEMCP nothing nullstring); - -# Automation data types. -sub VT_EMPTY {0;} -sub VT_NULL {1;} -sub VT_I2 {2;} -sub VT_I4 {3;} -sub VT_R4 {4;} -sub VT_R8 {5;} -sub VT_CY {6;} -sub VT_DATE {7;} -sub VT_BSTR {8;} -sub VT_DISPATCH {9;} -sub VT_ERROR {10;} -sub VT_BOOL {11;} -sub VT_VARIANT {12;} -sub VT_UNKNOWN {13;} -sub VT_DECIMAL {14;} # Officially not allowed in VARIANTARGs -sub VT_UI1 {17;} - -sub VT_ARRAY {0x2000;} -sub VT_BYREF {0x4000;} - - -# For backward compatibility -sub CP_ACP {0;} # ANSI codepage -sub CP_OEMCP {1;} # OEM codepage - -use overload - # '+' => 'Add', '-' => 'Sub', '*' => 'Mul', '/' => 'Div', - '""' => sub {$_[0]->As(VT_BSTR)}, - '0+' => sub {$_[0]->As(VT_R8)}, - fallback => 1; - -sub Variant { - return Win32::OLE::Variant->new(@_); -} - -sub nothing { - return Win32::OLE::Variant->new(VT_DISPATCH); -} - -sub nullstring { - return Win32::OLE::Variant->new(VT_BSTR); -} - -1; - -__END__ - -=head1 NAME - -Win32::OLE::Variant - Create and modify OLE VARIANT variables - -=head1 SYNOPSIS - - use Win32::OLE::Variant; - my $var = Variant(VT_DATE, 'Jan 1,1970'); - $OleObject->{value} = $var; - $OleObject->Method($var); - - -=head1 DESCRIPTION - -The IDispatch interface used by the Perl OLE module uses a universal -argument type called VARIANT. This is basically an object containing -a data type and the actual data value. The data type is specified by -the VT_xxx constants. - -=head2 Functions - -=over 8 - -=item nothing() - -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 - -The nothing() function is B<not> exported by default. - -=item nullstring() - -The nullstring() function returns a VT_BSTR variant with a NULL string -pointer. This is B<not> the same as a VT_BSTR variant with an empty -string "". The nullstring() value is the same as the vbNullString -constant in Visual Basic. - -The nullstring() function is B<not> exported by default. - -=item Variant(TYPE, DATA) - -This is just a function alias of the C<Win32::OLE::Variant->new()> -method (see below). This function is exported by default. - -=back - -=head2 Methods - -=over 8 - -=item new(TYPE, DATA) - -This method returns a Win32::OLE::Variant object of the specified -TYPE that contains the given DATA. The Win32::OLE::Variant object -can be used to specify data types other than IV, NV or PV (which are -supported transparently). See L<Variants> below for details. - -For VT_EMPTY and VT_NULL variants, the DATA argument may be omitted. -For all non-VT_ARRAY variants DATA specifies the initial value. - -To create a SAFEARRAY variant, you have to specify the VT_ARRAY flag in -addition to the variant base type of the array elements. In this cases -DATA must be a list specifying the dimensions of the array. Each element -can be either an element count (indices 0 to count-1) or an array -reference pointing to the lower and upper array bounds of this dimension: - - my $Array = Win32::OLE::Variant->new(VT_ARRAY|VT_R8, [1,2], 2); - -This creates a 2-dimensional SAFEARRAY of doubles with 4 elements: -(1,0), (1,1), (2,0) and (2,1). - -A special case is the creation of one-dimensional VT_UI1 arrays with -a string DATA argument: - - my $String = Variant(VT_ARRAY|VT_UI1, "String"); - -This creates a 6 element character array initialized to "String". For -backward compatibility VT_UI1 with a string initializer automatically -implies VT_ARRAY. The next line is equivalent to the previous example: - - my $String = Variant(VT_UI1, "String"); - -If you really need a single character VT_UI1 variant, you have to create -it using a numeric intializer: - - my $Char = Variant(VT_UI1, ord('A')); - -=item As(TYPE) - -C<As> converts the VARIANT to the new type before converting to a -Perl value. This take the current LCID setting into account. For -example a string might contain a ',' as the decimal point character. -Using C<$variant->As(VT_R8)> will correctly return the floating -point value. - -The underlying variant object is NOT changed by this method. - -=item ChangeType(TYPE) - -This method changes the type of the contained VARIANT in place. It -returns the object itself, not the converted value. - -=item Copy([DIM]) - -This method creates a copy of the object. If the original variant had -the VT_BYREF bit set then the new object will contain a copy of the -referenced data and not a reference to the same old data. The new -object will not have the VT_BYREF bit set. - - my $Var = Variant(VT_I4|VT_ARRAY|VT_BYREF, [1,5], 3); - my $Copy = $Var->Copy; - -The type of C<$Copy> is now VT_I4|VT_ARRAY and the value is a copy of -the other SAFEARRAY. Changes to elements of C<$Var> will not be reflected -in C<$Copy> and vice versa. - -The C<Copy> method can also be used to extract a single element of a -VT_ARRAY | VT_VARIANT object. In this case the array indices must be -specified as a list DIM: - - my $Int = $Var->Copy(1, 2); - -C<$Int> is now a VT_I4 Variant object containing the value of element (1,2). - -=item Currency([FORMAT[, LCID]]) - -This method converts the VARIANT value into a formatted currency string. The -FORMAT can be either an integer constant or a hash reference. Valid constants -are 0 and LOCALE_NOUSEROVERRIDE. You get the value of LOCALE_NOUSEROVERRIDE -from the Win32::OLE::NLS module: - - use Win32::OLE::NLS qw(:LOCALE); - -LOCALE_NOUSEROVERRIDE tells the method to use the system default currency -format for the specified locale, disregarding any changes that might have -been made through the control panel application. - -The hash reference could contain the following keys: - - NumDigits number of fractional digits - LeadingZero whether to use leading zeroes in decimal fields - Grouping size of each group of digits to the left of the decimal - DecimalSep decimal separator string - ThousandSep thousand separator string - NegativeOrder see L<Win32::OLE::NLS/LOCALE_ICURRENCY> - PositiveOrder see L<Win32::OLE::NLS/LOCALE_INEGCURR> - CurrencySymbol currency symbol string - -For example: - - use Win32::OLE::Variant; - use Win32::OLE::NLS qw(:DEFAULT :LANG :SUBLANG :DATE :TIME); - my $lcidGerman = MAKELCID(MAKELANGID(LANG_GERMAN, SUBLANG_NEUTRAL)); - my $v = Variant(VT_CY, "-922337203685477.5808"); - print $v->Currency({CurrencySymbol => "Tuits"}, $lcidGerman), "\n"; - -will print: - - -922.337.203.685.477,58 Tuits - -=item Date([FORMAT[, LCID]]) - -Converts the VARIANT into a formatted date string. FORMAT can be either -one of the following integer constants or a format string: - - LOCALE_NOUSEROVERRIDE system default date format for this locale - DATE_SHORTDATE use the short date format (default) - DATE_LONGDATE use the long date format - DATE_YEARMONTH use the year/month format - DATE_USE_ALT_CALENDAR use the alternate calendar, if one exists - DATE_LTRREADING left-to-right reading order layout - DATE_RTLREADING right-to left reading order layout - -The constants are available from the Win32::OLE::NLS module: - - use Win32::OLE::NLS qw(:LOCALE :DATE); - -The following elements can be used to construct a date format string. -Characters must be specified exactly as given below (e.g. "dd" B<not> "DD"). -Spaces can be inserted anywhere between formatting codes, other verbatim -text should be included in single quotes. - - d day of month - dd day of month with leading zero for single-digit days - ddd day of week: three-letter abbreviation (LOCALE_SABBREVDAYNAME) - dddd day of week: full name (LOCALE_SDAYNAME) - M month - MM month with leading zero for single-digit months - MMM month: three-letter abbreviation (LOCALE_SABBREVMONTHNAME) - MMMM month: full name (LOCALE_SMONTHNAME) - y year as last two digits - yy year as last two digits with leading zero for years less than 10 - yyyy year represented by full four digits - gg period/era string - -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 - -=item Dim() - -Returns a list of array bounds for a VT_ARRAY variant. The list contains -an array reference for each dimension of the variant's SAFEARRAY. This -reference points to an array containing the lower and upper bounds for -this dimension. For example: - - my @Dim = $Var->Dim; - -Now C<@Dim> contains the following list: C<([1,5], [0,2])>. - -=item Get(DIM) - -For normal variants C<Get> returns the value of the variant, just like the -C<Value> method. For VT_ARRAY variants C<Get> retrieves the value of a single -array element. In this case C<DIM> must be a list of array indices. E.g. - - my $Val = $Var->Get(2,0); - -As a special case for one dimensional VT_UI1|VT_ARRAY variants the C<Get> -method without arguments returns the character array as a Perl string. - - print $String->Get, "\n"; - -=item IsNothing() - -Tests if the object is an empty VT_DISPATCH variant. See also nothing(). - -=item IsNullString() - -Tests if the object is an empty VT_BSTR variant. See also nullstring(). - -=item LastError() - -The use of the C<Win32::OLE::Variant->LastError()> method is deprecated. -Please use the C<Win32::OLE->LastError()> class method instead. - -=item Number([FORMAT[, LCID]]) - -This method converts the VARIANT value into a formatted number string. The -FORMAT can be either an integer constant or a hash reference. Valid constants -are 0 and LOCALE_NOUSEROVERRIDE. You get the value of LOCALE_NOUSEROVERRIDE -from the Win32::OLE::NLS module: - - use Win32::OLE::NLS qw(:LOCALE); - -LOCALE_NOUSEROVERRIDE tells the method to use the system default number -format for the specified locale, disregarding any changes that might have -been made through the control panel application. - -The hash reference could contain the following keys: - - NumDigits number of fractional digits - LeadingZero whether to use leading zeroes in decimal fields - Grouping size of each group of digits to the left of the decimal - DecimalSep decimal separator string - ThousandSep thousand separator string - NegativeOrder see L<Win32::OLE::NLS/LOCALE_INEGNUMBER> - -=item Put(DIM, VALUE) - -The C<Put> method is used to assign a new value to a variant. The value will -be coerced into the current type of the variant. E.g.: - - my $Var = Variant(VT_I4, 42); - $Var->Put(3.1415); - -This changes the value of the variant to C<3> because the type is VT_I4. - -For VT_ARRAY type variants the indices for each dimension of the contained -SAFEARRAY must be specified in front of the new value: - - $Array->Put(1, 1, 2.7); - -It is also possible to assign values to *every* element of the SAFEARRAY at -once using a single Put() method call: - - $Array->Put([[1,2], [3,4]]); - -In this case the argument to Put() must be an array reference and the -dimensions of the Perl list-of-lists must match the dimensions of the -SAFEARRAY exactly. - -The are a few special cases for one-dimensional VT_UI1 arrays: The VALUE -can be specified as a string instead of a number. This will set the selected -character to the first character of the string or to '\0' if the string was -empty: - - my $String = Variant(VT_UI1|VT_ARRAY, "ABCDE"); - $String->Put(1, "123"); - $String->Put(3, ord('Z')); - $String->Put(4, ''); - -This will set the value of C<$String> to C<"A1CZ\0">. If the index is omitted -then the string is copied to the value completely. The string is truncated -if it is longer than the size of the VT_UI1 array. The result will be padded -with '\0's if the string is shorter: - - $String->Put("String"); - -Now C<$String> contains the value "Strin". - -C<Put> returns the Variant object itself so that multiple C<Put> calls can be -chained together: - - $Array->Put(0,0,$First_value)->Put(0,1,$Another_value); - -=item Time([FORMAT[, LCID]]) - -Converts the VARIANT into a formatted time string. FORMAT can be either -one of the following integer constants or a format string: - - LOCALE_NOUSEROVERRIDE system default time format for this locale - TIME_NOMINUTESORSECONDS don't use minutes or seconds - TIME_NOSECONDS don't use seconds - TIME_NOTIMEMARKER don't use a time marker - TIME_FORCE24HOURFORMAT always use a 24-hour time format - -The constants are available from the Win32::OLE::NLS module: - - use Win32::OLE::NLS qw(:LOCALE :TIME); - -The following elements can be used to construct a time format string. -Characters must be specified exactly as given below (e.g. "dd" B<not> "DD"). -Spaces can be inserted anywhere between formatting codes, other verbatim -text should be included in single quotes. - - h hours; 12-hour clock - hh hours with leading zero for single-digit hours; 12-hour clock - H hours; 24-hour clock - HH hours with leading zero for single-digit hours; 24-hour clock - m minutes - mm minutes with leading zero for single-digit minutes - s seconds - ss seconds with leading zero for single-digit seconds - t one character time marker string, such as A or P - tt multicharacter time marker string, such as AM or PM - -For example: - - my $v = Variant(VT_DATE, "April 1 99 2:23 pm"); - print $v->Time, "\n"; - print $v->Time(TIME_FORCE24HOURFORMAT|TIME_NOTIMEMARKER), "\n"; - print $v->Time("hh.mm.ss tt"), "\n"; - -will print: - - 2:23:00 PM - 14:23:00 - 02.23.00 PM - -=item Type() - -The C<Type> method returns the variant type of the contained VARIANT. - -=item Unicode() - -The C<Unicode> method returns a C<Unicode::String> object. This contains -the BSTR value of the variant in network byte order. If the variant is -not currently in VT_BSTR format then a VT_BSTR copy will be produced first. - -=item Value() - -The C<Value> method returns the value of the VARIANT as a Perl value. The -conversion is performed in the same manner as all return values of -Win32::OLE method calls are converted. - -=back - -=head2 Overloading - -The Win32::OLE::Variant package has overloaded the conversion to -string and number formats. Therefore variant objects can be used in -arithmetic and string operations without applying the C<Value> -method first. - -=head2 Class Variables - -The Win32::OLE::Variant class used to have its own set of class variables -like C<$CP>, C<$LCID> and C<$Warn>. In version 0.1003 and later of the -Win32::OLE module these variables have been eliminated. Now the settings -of Win32::OLE are used by the Win32::OLE::Variant module too. Please read -the documentation of the C<Win32::OLE->Option> class method. - - -=head2 Constants - -These constants are exported by default: - - VT_EMPTY - VT_NULL - VT_I2 - VT_I4 - VT_R4 - VT_R8 - VT_CY - VT_DATE - VT_BSTR - VT_DISPATCH - VT_ERROR - VT_BOOL - VT_VARIANT - VT_UNKNOWN - VT_DECIMAL - VT_UI1 - - VT_ARRAY - VT_BYREF - -VT_DECIMAL is not on the official list of allowable OLE Automation -datatypes. But even Microsoft ADO seems to sometimes return values -of Recordset fields in VT_DECIMAL format. - -=head2 Variants - -A Variant is a data type that is used to pass data between OLE -connections. - -The default behavior is to convert each perl scalar variable into -an OLE Variant according to the internal perl representation. -The following type correspondence holds: - - C type Perl type OLE type - ------ --------- -------- - int IV VT_I4 - double NV VT_R8 - char * PV VT_BSTR - void * ref to AV VT_ARRAY - ? undef VT_ERROR - ? Win32::OLE object VT_DISPATCH - -Note that VT_BSTR is a wide character or Unicode string. This presents a -problem if you want to pass in binary data as a parameter as 0x00 is -inserted between all the bytes in your data. The C<Variant()> method -provides a solution to this. With Variants the script writer can specify -the OLE variant type that the parameter should be converted to. Currently -supported types are: - - VT_UI1 unsigned char - VT_I2 signed int (2 bytes) - VT_I4 signed int (4 bytes) - VT_R4 float (4 bytes) - VT_R8 float (8 bytes) - VT_DATE OLE Date - VT_BSTR OLE String - VT_CY OLE Currency - VT_BOOL OLE Boolean - -When VT_DATE and VT_CY objects are created, the input parameter is treated -as a Perl string type, which is then converted to VT_BSTR, and finally to -VT_DATE of VT_CY using the C<VariantChangeType()> OLE API function. -See L<Win32::OLE/EXAMPLES> for how these types can be used. - -=head2 Variant arrays - -A variant can not only contain a single value but also a multi-dimensional -array of values (called a SAFEARRAY). In this case the VT_ARRAY flag must -be added to the base variant type, e.g. C<VT_I4 | VT_ARRAY> for an array of -integers. The VT_EMPTY and VT_NULL types are invalid for SAFEARRAYs. It -is possible to create an array of variants: C<VT_VARIANT | VT_ARRAY>. In this -case each element of the array can have a different type (including VT_EMPTY -and VT_NULL). The elements of a VT_VARIANT SAFEARRAY cannot have either of the -VT_ARRAY or VT_BYREF flags set. - -The lower and upper bounds for each dimension can be specified separately. -They do not have to have all the same lower bound (unlike Perl's arrays). - -=head2 Variants by reference - -Some OLE servers expect parameters passed by reference so that they -can be changed in the method call. This allows methods to easily -return multiple values. There is preliminary support for this in -the Win32::OLE::Variant module: - - my $x = Variant(VT_I4|VT_BYREF, 0); - my $y = Variant(VT_I4|VT_BYREF, 0); - $Corel->GetSize($x, $y); - print "Size is $x by $y\n"; - -After the C<GetSize> method call C<$x> and C<$y> will be set to -the respective sizes. They will still be variants. In the print -statement the overloading converts them to string representation -automatically. - -VT_BYREF is now supported for all variant types (including SAFEARRAYs). -It can also be used to pass an OLE object by reference: - - my $Results = $App->CreateResultsObject; - $Object->Method(Variant(VT_DISPATCH|VT_BYREF, $Results)); - -=head1 AUTHORS/COPYRIGHT - -This module is part of the Win32::OLE distribution. - -=cut |