Value Objects
The Automation Value Object
The object can be obtained from any uno object by calling the Bridge_GetValueObject on it. It holds a value and a type description, hence it resembles a UNO any or a VARIANT. A Value Object can stand in for all kinds of arguments in a call to a UNO method from a automation language. A Value Object is used when the bridge needs additional information for the parameter conversion. This is the case when a UNO method takes an any as argument. In many cases, however, one can do without a Value Object if one provides an argument which maps exactly to the expected UNO type according to the default mapping. For example, a UNO method takes an any as argument which is expected to contain a short. Then it would be sufficient to provide a Long in Visual Basic. But in JScript there are no types and implicitly a four byte integer would be passed to the call. Then the any would not contain a short and the call may fail. In that case the Value Object would guarantee the proper conversion.
A Value Object also enables in/out and out parameter in languages which only know in-parameters in functions. JScript is a particular case because one can use Array objects as well as Value Objects for those parameters.
A Value Object exposes four functions that can be accessed through IDispatch
. These are:
void Set( [in]VARIANT type, [in]VARIANT value);
Assigns a type and a value.
void Get( [out,retval] VARIANT* val);
Returns the value contained in the object. Get is used when the Value Object was used as inout or out parameter.
void InitOutParam();
Tells the object that it is used as out parameter.
void InitInOutParam( [in]VARIANT type, [in]VARIANT value);
Tells the object that it is used as inout parameter and passes the value for the in parameter, as well as the type.
When the Value Object is used as in or inout parameter then specify the type of the value. The names of types correspond to the names used in UNO IDL, except for the “object” name. The following table shows what types can be specified.
Name (used with Value Object) | UNO IDL |
---|---|
char | char |
boolean | boolean |
byte | byte |
unsigned | unsigned byte |
short | short |
unsigned short | unsigned short |
long | long |
unsigned long | unsigned long |
string | string |
float | float |
double | double |
any | any |
object | some UNO interface |
To show that the value is a sequence, put brackets before the names, for example:
[]char - sequence<char> [][]char - sequence < sequence <char > > [][][]char - sequence < sequence < sequence < char > > >
The Value Objects
are provided by the bridge and can be obtained from the service manager object. The service manager is a registered COM component with the ProgId “com.sun.star.ServiceManager” (The Service Manager Component). For example:
// JScript var valueObject= objSericeManager.Bridge_GetValueObject();
To use a Value Object
as in parameter, specify the type and pass the value to the object:
// UNO IDL void doSomething( [in] sequence< short > ar);
// JScript var value= objServiceManager.Bridge_GetValueObject(); var array= new Array(1,2,3); value.Set("[]short",array); object.doSomething( value);
In the previous example, the Value Object
was defined to be a sequence of short values. The array could also contain Value Objects
again:
var value1= objServiceManager.Bridge_GetValueObject(); var value2= objServiceManager.Bridge_GetValueObject(); value1.Set("short", 100); value2.Set("short", 111); var array= new Array(); array[0]= value1; array[1]= value2; var allValue= objServiceManager.Bridge_GetValueObject(); allValue.Set("[]short", array); object.doSomething( allValue);
If a function takes an out parameter, tell the Value Object
like this:
// UNO IDL void doSomething( [out] long);
// JScript var value= objServiceManager.Bridge_GetValueObject(); value.InitOutParam(); object.doSomething( value); var out= value.Get();
When the Value Object
is an inout
parameter, it needs to know the type and value as well:
//UNO IDL void doSomething( [inout] long);
//JScript var value= objServiceManager.Bridge_GetValueObject(); value.InitInOutParam("long", 123); object.doSomething(value); var out= value.Get();
UNO Value Object (as of OOo 3.4)
The UNO Value Object is basically the same as the Automation Value Object. It can be provided as argument in calls on automation objects. The value object is an uno service and implements com.sun.star.bridge.oleautomation.XValueObject. The type description is provided by flags which resemble the VARTYPE
as used by VARIANTs
. All possible type flags are provided as properties by the XValueObject interface.
'OOo Basic 'function expects a VARIANT of VT_I1 (signed char) Dim value As Object value = createUnoService("com.sun.star.bridge.oleautomation.ValueObject") value.set(value.VT_I1, 100) automation_object.func(value) 'function expects a VARIANT of SAFEARRAY of VT_I2 Dim valueI2 As Object Dim arI2(1) As Long arI2(0) = 1000 arI2(1) = 1000 valueI2 = createUnoService("com.sun.star.bridge.oleautomation.ValueObject") valueI2.set(valueI2.VT_I2 Or valueI2.VT_ARRAY, arI2) automation_object.func(valueI2)
If a Value Object is provided as out or in/out parameter then the type will be changed after the function has returned. Therefore the argument type must be of Variant. For example:
Dim valueLong As Variant valueLong = createUnoService("com.sun.star.bridge.oleautomation.ValueObject") valueLong.set(valueLong.VT_INT, 1000) automation_object.outLong(valueLong)
Content on this page is licensed under the Public Documentation License (PDL). |