Difference between revisions of "Documentation/DevGuide/ProUNO/Basic/Instantiating UNO Services"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (Robot: Changing Category:Professional UNO)
(8 intermediate revisions by 5 users not shown)
Line 7: Line 7:
 
|NextPage=Documentation/DevGuide/ProUNO/Basic/Getting Information about UNO Objects
 
|NextPage=Documentation/DevGuide/ProUNO/Basic/Getting Information about UNO Objects
 
}}
 
}}
 +
{{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/Basic/{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:Instantiating UNO Services}}
 
{{DISPLAYTITLE:Instantiating UNO Services}}
 
<!--<idltopic>com.sun.star.lang.ServiceManager</idltopic>-->
 
<!--<idltopic>com.sun.star.lang.ServiceManager</idltopic>-->
 
In Basic, instantiate services using the Basic Runtime Library (RTL) function <code>createUnoService()</code>. This function expects a fully qualified service name and returns an object supporting this service, if it is available:
 
In Basic, instantiate services using the Basic Runtime Library (RTL) function <code>createUnoService()</code>. This function expects a fully qualified service name and returns an object supporting this service, if it is available:
 
+
<source lang="oobas">
 
   oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
 
   oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
 
+
</source>
 
This call instantiates the <idl>com.sun.star.ucb.SimpleFileAccess</idl> service. To ensure that the function was successful, the returned object can be checked with the <code>IsNull</code> function:
 
This call instantiates the <idl>com.sun.star.ucb.SimpleFileAccess</idl> service. To ensure that the function was successful, the returned object can be checked with the <code>IsNull</code> function:
 
+
<source lang="oobas">
 
   oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
 
   oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
 
   bError = IsNull( oSimpleFileAccess )' bError is set to False
 
   bError = IsNull( oSimpleFileAccess )' bError is set to False
Line 20: Line 21:
 
   oNoService = CreateUnoService( "com.sun.star.nowhere.ThisServiceDoesNotExist" )
 
   oNoService = CreateUnoService( "com.sun.star.nowhere.ThisServiceDoesNotExist" )
 
   bError = IsNull( oNoService )' bError is set to True
 
   bError = IsNull( oNoService )' bError is set to True
 
+
</source>
 
Instead of using <code>CreateUnoService()</code> to instantiate a service, it is also possible to get the global UNO <idl>com.sun.star.lang.ServiceManager</idl> of the {{PRODUCTNAME}} process by calling <code>GetProcessServiceManager()</code>. Once obtained, use <code>createInstance()</code> directly:
 
Instead of using <code>CreateUnoService()</code> to instantiate a service, it is also possible to get the global UNO <idl>com.sun.star.lang.ServiceManager</idl> of the {{PRODUCTNAME}} process by calling <code>GetProcessServiceManager()</code>. Once obtained, use <code>createInstance()</code> directly:
 
+
<source lang="oobas">
 
   oServiceMgr = GetProcessServiceManager()
 
   oServiceMgr = GetProcessServiceManager()
 
   oSimpleFileAccess = oServiceMgr.createInstance( "com.sun.star.ucb.SimpleFileAccess" )
 
   oSimpleFileAccess = oServiceMgr.createInstance( "com.sun.star.ucb.SimpleFileAccess" )
Line 29: Line 30:
 
    
 
    
 
   oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
 
   oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
 
+
</source>
 
The advantage of <code>GetProcessServiceManager()</code> is that additional information and pass in arguments is received when services are instantiated using the service manager. For instance, to initialize a service with arguments, the <code>createInstanceWithArguments()</code> method of <idl>com.sun.star.lang.XMultiServiceFactory</idl> has to be used at the service manager, because there is no appropriate Basic RTL function to do that. Example:
 
The advantage of <code>GetProcessServiceManager()</code> is that additional information and pass in arguments is received when services are instantiated using the service manager. For instance, to initialize a service with arguments, the <code>createInstanceWithArguments()</code> method of <idl>com.sun.star.lang.XMultiServiceFactory</idl> has to be used at the service manager, because there is no appropriate Basic RTL function to do that. Example:
 
+
<source lang="oobas">
 
   Dim args(1)
 
   Dim args(1)
 
   args(0) = "Important information"
 
   args(0) = "Important information"
Line 37: Line 38:
 
   oService = oServiceMgr.createInstanceWithArguments _
 
   oService = oServiceMgr.createInstanceWithArguments _
 
       ( "com.sun.star.nowhere.ServiceThatNeedsInitialization", args() )
 
       ( "com.sun.star.nowhere.ServiceThatNeedsInitialization", args() )
 
+
</source>
 
The object returned by <code>GetProcessServiceManager()</code> is a normal Basic UNO object supporting <idl>com.sun.star.lang.ServiceManager</idl>. Its properties and methods are accessed as described above.
 
The object returned by <code>GetProcessServiceManager()</code> is a normal Basic UNO object supporting <idl>com.sun.star.lang.ServiceManager</idl>. Its properties and methods are accessed as described above.
  
In addition, the Basic RTL provides special properties as API entry points. They are described in more detail in [[Documentation/DevGuide/Basic/Features of OpenOffice.org Basic|Features of OpenOffice.org Basic]]:
+
=== Using new-style service constructors ===
 +
 
 +
Beginning with OpenOffice.org 3.2 OpenOffice.org Basic supports UNO new-style service constructors.
 +
For more details see section [[Documentation/DevGuide/ProUNO/Services|Services]].
 +
For the sample service used above constructors could be defined like this:
 +
 
 +
<source lang="idl">
 +
  module com { module sun { module star { module nowhere {
 +
 
 +
  service ServiceThatNeedsInitialization: XFoo {
 +
      create1([in] long arg);
 +
      create2([in] string important1, [in] string important2);
 +
  };
 +
 
 +
  }; }; }; };
 +
</source>
 +
 
 +
UNO services are mapped to OpenOffice.org Basic objects. They have to be addressed by
 +
using the complete UNO namespace path. The constructors can be accessed as methods of
 +
these service objects:
 +
 
 +
<source lang="oobas">
 +
  Dim oServiceObj
 +
  oServiceObj = com.sun.star.nowhere.ServiceThatNeedsInitialization
 +
  Dim oInstance As Object
 +
  oInstance = oServiceObj.create2( "Useless", "Invalid" )
 +
</source>
 +
 
 +
Of course the service object doesn't need to be stored in a variable before,
 +
the instantiation can also be done in one single statement:
 +
 
 +
<source lang="oobas">
 +
  Dim oInstance As Object
 +
  oInstance = com.sun.star.nowhere.ServiceThatNeedsInitialization.create1( 42 )
 +
</source>
 +
 
 +
Internally the UNO default context is used to create the and passed to the service.
 +
It's also possible to use an own context instead by adding it as first argument:
 +
 
 +
<source lang="oobas">
 +
  Dim oMyContext As Object
 +
  oMyContext = GetContextFromSomewhere()
 +
  oInstance = oServiceObj.create1( oMyContext, 42 )
 +
</source>
 +
 
 +
If a new-style service only has an implicit constructor it's mapped to a method
 +
"create" without parameters in OpenOffice.org Basic.
 +
 
 +
=== Build in properties ===
 +
 
 +
The Basic RTL provides special properties as API entry points. They are described in more detail in [[Documentation/DevGuide/Basic/Features of OpenOffice.org Basic|Features of OpenOffice.org Basic]]:
  
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
Line 48: Line 99:
 
|ThisComponent  
 
|ThisComponent  
 
|Only exists in Basic code which is embedded in a Writer, Calc, Draw or Impress document. It contains the document model the Basic code is embedded in.  
 
|Only exists in Basic code which is embedded in a Writer, Calc, Draw or Impress document. It contains the document model the Basic code is embedded in.  
 +
|-
 +
|ThisDatabaseDocument
 +
|Only exists in Basic code which is embedded in a Base document. It contains the document model the Basic code is embedded in, i.e. the Base document.  Useful when a macro is started by an event from a Form document contained in the Base document.
 
|-
 
|-
 
|StarDesktop  
 
|StarDesktop  
|The <idl>com.sun.star.frame.Desktop</idl> singleton of the office application. It loads document components and handles the document windows. For instance, the document in the top window can be retrieved usingoDoc = StarDesktop.CurrentComponent  
+
|The <idl>com.sun.star.frame.Desktop</idl> singleton of the office application. It loads document components and handles the document windows. For instance, the document in the top window can be retrieved using <code>oDoc = StarDesktop.CurrentComponent</code>.
 
|}
 
|}
  
 +
{{Tip|<tt>ThisComponent</tt> is recommended over <tt>StarDesktop.CurrentComponent</tt>, for convenience in developing and debugging from the IDE. If the BasicIDE is active, StarDesktop.CurrentComponent refers to the BasicIDE itself while ThisComponent always refers to the component that was active before the BasicIDE became the top window.}}
 
{{PDL1}}
 
{{PDL1}}
  
[[Category:Documentation/Developers Guide/Professional UNO]]
+
[[Category:Documentation/Developer's Guide/Professional UNO]]

Revision as of 20:21, 14 July 2018



In Basic, instantiate services using the Basic Runtime Library (RTL) function createUnoService(). This function expects a fully qualified service name and returns an object supporting this service, if it is available:

  oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )

This call instantiates the com.sun.star.ucb.SimpleFileAccess service. To ensure that the function was successful, the returned object can be checked with the IsNull function:

  oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
  bError = IsNull( oSimpleFileAccess )' bError is set to False
 
  oNoService = CreateUnoService( "com.sun.star.nowhere.ThisServiceDoesNotExist" )
  bError = IsNull( oNoService )' bError is set to True

Instead of using CreateUnoService() to instantiate a service, it is also possible to get the global UNO com.sun.star.lang.ServiceManager of the OpenOffice.org process by calling GetProcessServiceManager(). Once obtained, use createInstance() directly:

  oServiceMgr = GetProcessServiceManager()
  oSimpleFileAccess = oServiceMgr.createInstance( "com.sun.star.ucb.SimpleFileAccess" )
 
  ' is the same as
 
  oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )

The advantage of GetProcessServiceManager() is that additional information and pass in arguments is received when services are instantiated using the service manager. For instance, to initialize a service with arguments, the createInstanceWithArguments() method of com.sun.star.lang.XMultiServiceFactory has to be used at the service manager, because there is no appropriate Basic RTL function to do that. Example:

  Dim args(1)
  args(0) = "Important information"
  args(1) = "Even more important information"
  oService = oServiceMgr.createInstanceWithArguments _
      ( "com.sun.star.nowhere.ServiceThatNeedsInitialization", args() )

The object returned by GetProcessServiceManager() is a normal Basic UNO object supporting com.sun.star.lang.ServiceManager. Its properties and methods are accessed as described above.

Using new-style service constructors

Beginning with OpenOffice.org 3.2 OpenOffice.org Basic supports UNO new-style service constructors. For more details see section Services. For the sample service used above constructors could be defined like this:

  module com { module sun { module star { module nowhere {
 
  service ServiceThatNeedsInitialization: XFoo { 
      create1([in] long arg);
      create2([in] string important1, [in] string important2);
  };
 
  }; }; }; };

UNO services are mapped to OpenOffice.org Basic objects. They have to be addressed by using the complete UNO namespace path. The constructors can be accessed as methods of these service objects:

  Dim oServiceObj
  oServiceObj = com.sun.star.nowhere.ServiceThatNeedsInitialization
  Dim oInstance As Object
  oInstance = oServiceObj.create2( "Useless", "Invalid" )

Of course the service object doesn't need to be stored in a variable before, the instantiation can also be done in one single statement:

  Dim oInstance As Object
  oInstance = com.sun.star.nowhere.ServiceThatNeedsInitialization.create1( 42 )

Internally the UNO default context is used to create the and passed to the service. It's also possible to use an own context instead by adding it as first argument:

  Dim oMyContext As Object
  oMyContext = GetContextFromSomewhere()
  oInstance = oServiceObj.create1( oMyContext, 42 )

If a new-style service only has an implicit constructor it's mapped to a method "create" without parameters in OpenOffice.org Basic.

Build in properties

The Basic RTL provides special properties as API entry points. They are described in more detail in Features of OpenOffice.org Basic:

OpenOffice.org Basic RTL Property Description
ThisComponent Only exists in Basic code which is embedded in a Writer, Calc, Draw or Impress document. It contains the document model the Basic code is embedded in.
ThisDatabaseDocument Only exists in Basic code which is embedded in a Base document. It contains the document model the Basic code is embedded in, i.e. the Base document. Useful when a macro is started by an event from a Form document contained in the Base document.
StarDesktop The com.sun.star.frame.Desktop singleton of the office application. It loads document components and handles the document windows. For instance, the document in the top window can be retrieved using oDoc = StarDesktop.CurrentComponent.
Tip.png ThisComponent is recommended over StarDesktop.CurrentComponent, for convenience in developing and debugging from the IDE. If the BasicIDE is active, StarDesktop.CurrentComponent refers to the BasicIDE itself while ThisComponent always refers to the component that was active before the BasicIDE became the top window.
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages