Difference between revisions of "Documentation/DevGuide/ProUNO/Bridge/Using Automation Objects from UNO"
m (→Properties with Arguments) |
|||
(2 intermediate revisions by the same user not shown) | |||
Line 9: | Line 9: | ||
{{DISPLAYTITLE:Using Automation Objects from UNO}} | {{DISPLAYTITLE:Using Automation Objects from UNO}} | ||
__NOTOC__ | __NOTOC__ | ||
− | 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 <idl>com.sun.star.script.XInvocation</idl>. < | + | 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 <idl>com.sun.star.script.XInvocation</idl>. <idls>com.sun.star.script.XInvocation</idls> is a scripting interface that is intended for dynamically performing calls similar to <code>IDispatch</code>. Since StarBasic uses <idls>com.sun.star.script.XInvocation</idls> to communicate with objects, Automation objects can be used from StarBasic. |
=== Instantiation === | === Instantiation === | ||
− | To obtain an instance of an Automation object it is easiest to use the service <idl>com.sun.star.bridge.oleautomation.Factory</idl>. It provides an < | + | To obtain an instance of an Automation object it is easiest to use the service <idl>com.sun.star.bridge.oleautomation.Factory</idl>. It provides an <idls>com.sun.star.lang.XMultiServiceFactory</idls> interface which is used to get the desired object. For example: |
− | < | + | <syntaxhighlight lang="cpp"> |
//C++ | //C++ | ||
Line 31: | Line 31: | ||
... | ... | ||
} | } | ||
− | </ | + | </syntaxhighlight> |
In StarBasic it looks quite simple: | In StarBasic it looks quite simple: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
'StarBasic | 'StarBasic | ||
Line 49: | Line 49: | ||
objApp = CreateObject("Word.Application") | objApp = CreateObject("Word.Application") | ||
'call methods on the Automation object | 'call methods on the Automation object | ||
− | </ | + | </syntaxhighlight> |
==== Accessing Automation Objects ==== | ==== Accessing Automation Objects ==== | ||
− | All Automation objects are accessed through <idl>com.sun.star.script.XInvocation</idl> interface. The function | + | All Automation objects are accessed through <idl>com.sun.star.script.XInvocation</idl> interface. The function <idlm>com.sun.star.script.XInvocation:getIntrospection</idlm> is not implemented. To call a method, <idlm>com.sun.star.script.XInvocation:invoke</idlm> is used. <idlm>com.sun.star.script.XInvocation:invoke</idlm> is also used to access properties with additional arguments. The methods <idlm>com.sun.star.script.XInvocation:setValue</idlm> and <idlm>com.sun.star.script.XInvocation:getValue</idlm> set or retrieve a property value. These methods can only be used with properties that do not have additional arguments. |
− | + | <idlm>com.sun.star.script.XInvocation:hasMethod</idlm> returns true for a name that represents a method or a property with arguments. And last, <idlm>com.sun.star.script.XInvocation:hasProperty</idlm> returns true for a name that represents a property with no arguments. Refer to the IDL documentation for more information about <idls>com.sun.star.script.XInvocation</idls>. | |
==== Properties with Arguments ==== | ==== Properties with Arguments ==== | ||
− | Unlike UNO properties, Automation properties can have arguments. Therefore, | + | Unlike UNO properties, Automation properties can have arguments. Therefore, <idlm>com.sun.star.script.XInvocation:setValue</idlm> and <idlm>com.sun.star.script.XInvocation:getValue</idlm> method are not suitable for those properties. Instead <idlm>com.sun.star.script.XInvocation:invoke</idlm> is used. If a property takes arguments, then <idlm>com.sun.star.script.XInvocation:hasProperty</idlm> returns false and <idlm>com.sun.star.script.XInvocation:hasMethod</idlm> returns true. <idlm>com.sun.star.script.XInvocation:invoke</idlm> 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 <idl>com.sun.star.bridge.oleautomation.PropertyPutArgument</idl>. Similar to <code>IDispatch::Invoke</code>, the property value must be the last in the argument list. For example: | 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 <idl>com.sun.star.bridge.oleautomation.PropertyPutArgument</idl>. Similar to <code>IDispatch::Invoke</code>, the property value must be the last in the argument list. For example: | ||
− | < | + | <syntaxhighlight lang="idl"> |
// MIDL | // MIDL | ||
[propget,...] HRESULT Item([in] VARIANT val1, [out, retval] VARIANT* pVal); | [propget,...] HRESULT Item([in] VARIANT val1, [out, retval] VARIANT* pVal); | ||
[propput,...] HRESULT Item([in] VARIANT val1, [in] VARIANT newVal); | [propput,...] HRESULT Item([in] VARIANT val1, [in] VARIANT newVal); | ||
− | </ | + | </syntaxhighlight> |
− | < | + | |
+ | <syntaxhighlight lang="cpp"> | ||
// C++ | // C++ | ||
Sequence< sal_Int16> seqIndices; | Sequence< sal_Int16> seqIndices; | ||
Line 85: | Line 86: | ||
Sequence<Any> seqGet(arGet, 1); | Sequence<Any> seqGet(arGet, 1); | ||
Any retVal = obj->invoke(OUString::createFromAscii("Item"), seqGet, seqIndices, seqOut); | Any retVal = obj->invoke(OUString::createFromAscii("Item"), seqGet, seqIndices, seqOut); | ||
− | </ | + | </syntaxhighlight> |
− | In StarBasic, < | + | In StarBasic, <idls>com.sun.star.bridge.oleautomation.PropertyPutArgument</idls> is implicitly used: |
− | < | + | <syntaxhighlight lang="oobas"> |
'StarBasic | 'StarBasic | ||
Line 94: | Line 95: | ||
Dim propval As Variant | Dim propval As Variant | ||
propval = obj.Item(0) | propval = obj.Item(0) | ||
− | </ | + | </syntaxhighlight> |
− | The property value that is obtained in a property get operation is the return value of | + | The property value that is obtained in a property get operation is the return value of <idlm>com.sun.star.script.XInvocation:invoke</idlm>. |
==== Optional Parameters, Default Values, Variable Argument Lists ==== | ==== 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 | + | The bridge supports all these special parameters. Optional parameters can be left out of the argument list of <idlm>com.sun.star.script.XInvocation:invoke</idlm>. 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 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 | + | If a method takes a variable argument list, then one can provide the respective UNO arguments as ordinary arguments to <idlm>com.sun.star.script.XInvocation:invoke</idlm>. <code>IDispatch::Invoke</code> would require those arguments in a <code>SAFEARRAY</code>. |
==== Named Arguments ==== | ==== Named Arguments ==== | ||
− | To provide named arguments in an | + | To provide named arguments in an <idlm>com.sun.star.script.XInvocation:invoke</idlm> call, one has to use instances of <idl>com.sun.star.bridge.oleautomation.NamedArgument</idl> for each argument. This is the struct in UNOIDL: |
− | < | + | <syntaxhighlight lang="idl"> |
module com { module sun { module star { module bridge { module oleautomation { | module com { module sun { module star { module bridge { module oleautomation { | ||
struct NamedArgument | struct NamedArgument | ||
Line 117: | Line 118: | ||
string Name; | string Name; | ||
− | /** The value of the argument | + | /** The value of the argument whose name is the one as contained in the |
member <member>Name</member>. | member <member>Name</member>. | ||
*/ | */ | ||
Line 124: | Line 125: | ||
}; }; }; }; }; | }; }; }; }; }; | ||
− | </ | + | </syntaxhighlight> |
− | 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 < | + | 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 <idls>com.sun.star.script.XInvocation</idls> could be as follows: |
* all provided: {A, B, C, D, E} | * all provided: {A, B, C, D, E} |
Latest revision as of 14:11, 23 December 2020
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). |