Using Automation Objects from UNO
This language binding offers a way of accessing Automation objects from UNO. For an Automation object to be usable, it must be properly registered on the system and have a programmatic identifier (ProgId) with which an instance can be created. From UNO, all Automation objects are accessed via com.sun.star.script.XInvocation. XInvocation is a scripting interface that is intended for dynamically performing calls similar to IDispatch. Since StarBasic uses XInvocation to communicate with objects, Automation objects can be used from StarBasic.
Instantiation
To obtain an instance of an Automation object it is easiest to use the service com.sun.star.bridge.oleautomation.Factory. It provides an XMultiServiceFactory interface which is used to get the desired object. For example:
//C++
Reference<XInterface> xInt = serviceManager->createInstance(
OUString::createFromAscii("com.sun.star.bridge.oleautomation.Factory"));
Reference<XMultiServiceFactory> automationFactory(xInt, UNO_QUERY);
if(automationFactory.is())
{
Reference<XInterface> xIntApp = automationFactory->createInstance(
OUString::createFromAscii("Word.Application"));
Reference< XInvocation > xInvApp( xIntApp, UNO_QUERY);
// call methods on the Automation object.
...
}
In StarBasic it looks quite simple:
'StarBasic
Dim automationFactory As Object
automationFactory = createUnoService("com.sun.star.bridge.oleautomation.Factory")
Dim objApp As Object
objApp = automationFactory.createInstance("Word.Application")
'call methods on the Automation object
</source>
StarBasic function CreateObject offers a simpler code:
<source lang="oobas">
Dim objApp As Object
objApp = CreateObject("Word.Application")
'call methods on the Automation object
Accessing Automation Objects
All Automation objects are accessed through com.sun.star.script.XInvocation interface. The function getIntrospection is not implemented. To call a method, invoke is used. invoke is also used to access properties with additional arguments. The methods setValue and getValue set or retrieve a property value. These methods can only be used with properties that do not have additional arguments.
hasMethod returns true for a name that represents a method or a property with arguments. And last, hasProperty returns true for a name that represents a property with no arguments. Refer to the IDL documentation for more information about XInvocation.
Properties with Arguments
Unlike UNO properties, Automation properties can have arguments. Therefore, setValue and getValue method are not suitable for those properties. Instead invoke is used. If a property takes arguments, then hasProperty returns false and hasMethod returns true. invoke must also be used if the arguments of the property are optional and not provided in the call.
The bridge must recognize a write operation on a property. To achieve this, the caller has to provide the actual property value (not additional arguments) in a structure of type com.sun.star.bridge.oleautomation.PropertyPutArgument. Similar to IDispatch::Invoke, the property value must be the last in the argument list. For example:
// MIDL
[propget,...] HRESULT Item([in] VARIANT val1, [out, retval] VARIANT* pVal);
[propput,...] HRESULT Item([in] VARIANT val1, [in] VARIANT newVal);
// C++
Sequence< sal_Int16> seqIndices;
Sequence<Any> seqOut;
//Prepare arguments
Any arArgs[2];
arArgs[0] <<= makeAny((sal_Int32) 0);
arArgs[1] <<= PropertyPutArgument(makeAny((sal_Int32) 0));
Sequence<Any> seqArgs(arArgs, 2);
//obj is a XInvocation of an Automation object
obj->invoke(OUString::createFromAscii("Item"), seqArgs, seqIndices, seqOut);
//now get the property value
Any arGet[1];
arGet[0] <<= makeAny((sal_Int32) 0);
Sequence<Any> seqGet(arGet, 1);
Any retVal = obj->invoke(OUString::createFromAscii("Item"), seqGet, seqIndices, seqOut);
In StarBasic, PropertyPutArgument is implicitly used:
'StarBasic
obj.Item(0) = 0
Dim propval As Variant
propval = obj.Item(0)
The property value that is obtained in a property get operation is the return value of invoke.
Optional Parameters, Default Values, Variable Argument Lists
The bridge supports all these special parameters. Optional parameters can be left out of the argument list of invoke. However, if a value is omitted, then all following arguments from the parameter list must also be omitted. This only applies for positional arguments and not for named arguments.
If the Automation object specifies a default value for an optional parameter, then the bridge supplies it, if no argument was provided by the caller.
If a method takes a variable argument list, then one can provide the respective UNO arguments as ordinary arguments to invoke. IDispatch::Invoke would require those arguments in a SAFEARRAY.
Named Arguments
To provide named arguments in an invoke call, one has to use instances of com.sun.star.bridge.oleautomation.NamedArgument for each argument. This is the struct in UNOIDL:
module com { module sun { module star { module bridge { module oleautomation {
struct NamedArgument
{
/** The name of the argument, for which
<member>NamedArgument::Value</member> is intended.
*/
string Name;
/** The value of the argument whose name is the one as contained in the
member <member>Name</member>.
*/
any Value;
};
}; }; }; }; };
In a call both, named arguments and positional arguments can be used together. The order is, first the positional arguments (the ordinary arguments), followed by named arguments. When named arguments are used, then arguments can be omitted even if arguments are provided that follow the omitted parameter. For example, assume that a method takes five arguments, which are all optional, then the argument lists for XInvocation could be as follows:
- all provided: {A, B, C, D, E}
- arguments omitted: {A,B,C,D} or {A,B} but not {A, C, D}
- named arguments : {nA, nC, nB, nD}, {nC, nD}
- mixed arguments: { A, B, nD}, {A, nC}
Named arguments can also be used with properties that have additional arguments. However, the property value itself cannot be a named argument, since it is already regarded as a named argument. Therefore, it is always the last argument.
| Content on this page is licensed under the Public Documentation License (PDL). |
