LibreOffice Developer's Guide

https://wiki.documentfoundation.org/Documentation/DevGuide
Admin
LibreOffice Developer's Guide is comprehensive documentation for developers on how to extend and...
Tokens:587,461
Snippets:5,566
Trust Score:9.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Bundled Extension File Structure Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Extensions

Illustrates the expected file structure for a bundled extension after installation. Ensure unique directory names to prevent conflicts.

```text
+ Office/share/extensions
  + Foo
  |- f1
  |- f2

```

--------------------------------

### Complete URI Examples - Extension (All Users)

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework

Examples of URIs used to call scripts stored in extensions installed for all users.

```text
vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application
```

```text
vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=share:uno_packages/myExtension.oxt
```

```text
vnd.sun.star.script:myLibrary.myMethod?language=Java&location=share:uno_packages/myExtension.oxt
```

```text
vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=share:uno_packages/myExtension.oxt
```

```text
vnd.sun.star.script:myExtension.oxt|myScript|myModule.py$myFunction?language=Python&location=share:uno_packages
```

--------------------------------

### Text Conversion Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/OfficeDev/Frame-Controller-Model_Paradigm_in_OpenOffice.org

Demonstrates how to use the XTextConversion interface to convert sample Korean text. This example requires UNO bootstrapping to get the desktop object and create a text document.

```java
//***************************************************************************
// comment: Step 1: get the Desktop object from the office
// Step 2: open an empty text document
// Step 3: insert a sample text
// Step 4: convert sample text
// Step 5: insert converted text
//***************************************************************************
import com.sun.star.uno.UnoRuntime;
public class TextConversion {

    public static void main(String args[]) {
        // You need the desktop to create a document
        // The getDesktop method does the UNO bootstrapping, gets the
        // remote servie manager and the desktop object.
        com.sun.star.frame.XDesktop xDesktop = null;
        xDesktop = getDesktop();

        com.sun.star.text.XTextDocument xTextDocument = 
            createTextdocument( xDesktop );
        com.sun.star.i18n.XTextConversion xTextConversion = 
            getTextConversion();
        try {
            // Korean sample text
            String aHeader = "\u7b2c\u0020\u0031\u0020\u7ae0\u0020\ud55c\ubb38\uc758\u0020\uad6c\uc870\u0028\u69cb\u9020\u0029";
            String aText = "\uc6b0\uc120\u0020\ud55c\uc790\ub294\u0020\uc11c\uc220\uc5b4\u0020\u0028\u654d\u8ff0\u8a9e\u0029\uc758\u0020\uc704\uce58\uac00\u0020\uc6b0\ub9ac\ub9d0\uacfc\u0020\ub2e4\ub974\ub2e4\u002e";

```

--------------------------------

### Example Protocol URL Schemas

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

These are example URL schemas configured for the 'vnd.sun.star.framework.ExampleHandler'.

```text
 myProtocol_1://*
myProtocol_2://*
```

--------------------------------

### Running Python Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/First_Steps

Command to execute the Python FirstUnoContact example. Ensure you use the Python interpreter bundled with LibreOffice.

```Shell
"C:\Program Files\LibreOffice\program\python" FirstUnoContact.py
```

```Shell
/opt/libreoffice26.2/program/python FirstUnoContact.py
```

```Shell
/Applications/LibreOffice.App/Contents/Resources/python FirstUnoContact.py
```

--------------------------------

### Example Path Substitution Configuration

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/OfficeDev/Frame-Controller-Model_Paradigm_in_OpenOffice.org

Illustrates how to configure user-defined path variables with environment-specific rules. This example maps 'MyDocuments' to different directories based on the operating system.

```xml
<?xml version="1.0" encoding="utf-8"?>
<oor:component-data oor:name="Substitution" oor:context="org.openoffice.Office"
xsi:schemaLocation="http://openoffice.org/2001/registry component-update.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <node oor:name="SharePoints">
        <node oor:name="MyDocuments" oor:op="replace">
            <node oor:name="1" oor:op="replace">
                <prop oor:name="Directory"><value>file:///H:/documents</value></prop>
                <node oor:name="Environment">
                    <prop oor:name="OS"><value>Windows</value></prop>
                </node>
            </node>
            <node oor:name="2" oor:op="replace">
                <prop oor:name="Directory"><value>file:///net/home/user/documents</value></prop>
                <node oor:name="Environment">
                    <prop oor:name="OS"><value>UNIX</value></prop>
                </node>
            </node>
        </node>
    </node>
</oor:component-data>
```

--------------------------------

### ADO Driver Connection String Examples

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Database_Access

Examples of ADO-specific connection strings for the SDBC ADO driver, demonstrating different providers and data sources.

```text
sdbc:ado:PROVIDER=Microsoft.Jet.OLEDB.4.0;DATA SOURCE=c:\northwind.mdb
```

```text
sdbc:ado:Provider=msdaora;data source=testdb
```

--------------------------------

### Start LibreOffice with Socket Connection

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Professional_UNO

Command line to start LibreOffice and accept connections via a socket. Ensure the port is not in use by another application.

```bash
soffice --accept=socket,host=localhost,port=2002;urp
```

--------------------------------

### Start LibreOffice in Listening Mode (Command Line)

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Professional_UNO

Use this command to start LibreOffice and make it listen on a socket for interprocess connections. Ensure the string is quoted on Unix shells.

```bash
soffice --accept=socket,host=0,port=2002;urp;
```

--------------------------------

### Start LibreOffice with Pipe Connection

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Professional_UNO

Command line to start LibreOffice and accept connections via a named pipe. The pipe name must be unique and consistent between client and server.

```bash
soffice --accept=pipe,name=pipe_name;urp
```

--------------------------------

### External Image URL Substitution Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Shows an example of how the %origin% placeholder is substituted with a UNO path during runtime for external images.

```text
vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/images
```

--------------------------------

### Toolbar Item Configuration Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Example demonstrating how to configure a toolbar item with a URL and title. The URL 'private:separator' is used to create a visual separator.

```xml
<value xml:lang="en-US">string</value>
```

--------------------------------

### Connecting with User Credentials

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Database_Access

This example shows how to create a database connection using `getConnectionWithInfo`, providing user credentials and other necessary information through a sequence of PropertyValue structs. Remember to dispose of the connection to prevent memory leaks.

```java
// create the DriverManager
Object driverManager = xMultiServiceFactory.createInstance("com.sun.star.sdbc.DriverManager");

// query for the interface XDriverManager
com.sun.star.sdbc.XDriverManager xDriverManager;

xDriverManager = UnoRuntime.queryInterface(
    XDriverManager.class, driverManager);

if (xDriverManager != null) {
    // first create the database URL
    String adabasURL = "sdbc:adabas::MYDB0";

    // create the necessary sequence of PropertyValue structs for user and password
    com.sun.star.beans.PropertyValue [] adabasProps = new com.sun.star.beans.PropertyValue[] {
        new com.sun.star.beans.PropertyValue("user", 0, "Scott",
            com.sun.star.beans.PropertyState.DIRECT_VALUE),
        new com.sun.star.beans.PropertyValue("password", 0, "huutsch",
            com.sun.star.beans.PropertyState.DIRECT_VALUE)
        };

    // now create a connection to Adabas
    XConnection xConnection = xDriverManager.getConnectionWithInfo(adabasURL, adabasProps);

    if (adabasConnection != null) {
        System.out.println("Connection was created!");

        // now we dispose the connection to close it
        XComponent xComponent = (XComponent)UnoRuntime.queryInterface(
            XComponent.class, xConnection );

        if (xComponent != null) {
            // connection must be disposed to avoid memory leaks
            xComponent.dispose();
            System.out.println("Connection disposed!");
        }
    } else {
        System.out.println("Connection could not be created!");
    }
}
```

--------------------------------

### Text Conversion Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Office_Development

This example demonstrates how to use the XTextConversion interface to convert text. It involves getting the desktop object, creating a text document, and performing the conversion.

```java
//***************************************************************************
// comment: Step 1: get the Desktop object from the office
// Step 2: open an empty text document
// Step 3: insert a sample text
// Step 4: convert sample text
// Step 5: insert converted text
//***************************************************************************
import com.sun.star.uno.UnoRuntime;
public class TextConversion {

    public static void main(String args[]) {
        // You need the desktop to create a document
        // The getDesktop method does the UNO bootstrapping, gets the
        // remote servie manager and the desktop object.
        com.sun.star.frame.XDesktop xDesktop = null;
        xDesktop = getDesktop();

        com.sun.star.text.XTextDocument xTextDocument = 
            createTextdocument( xDesktop );
        com.sun.star.i18n.XTextConversion xTextConversion = 
            getTextConversion();
        try {
            // Korean sample text
            String aHeader = "\u7b2c\u0020\u0031\u0020\u7ae0\u0020\ud55c\ubb38\uc758\u0020\uad6c\uc870\u0028\u69cb\u9020\u0029";
            String aText = "\uc6b0\uc120\u0020\ud55c\uc790\ub294\u0020\uc11c\uc220\uc5b4\u0020\u0028\u654c\u8ff0\u8a9e\u0029\uc758\u0020\uc704\uce58\uac00\u0020\uc6b0\ub9ac\ub9d0\uacfc\u0020\ub2e4\ub974\ub2e4\u002e";

```

--------------------------------

### Using the Desktop and Termination Listener

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Office_Development

Demonstrates connecting to the Office, creating a Desktop reference, and registering a termination listener to manage office shutdown. It shows how to test termination when 'at work' and when not.

```cpp
#include <sal/main.h>
#include <cppuhelper/bootstrap.hxx>
#include <cppuhelper/implbase1.hxx>
#include <com/sun/star/uno/XComponentContext.hpp>
#include <com/sun/star/lang/XMultiComponentFactory.hpp>
#include <com/sun/star/frame/XDesktop.hpp>
#include <com/sun/star/frame/XTerminateListener.hpp>
#include <com/sun/star/frame/TerminationVetoException.hpp>

#include <iostream>

using namespace ::cppu;
using namespace ::css::uno;
using namespace ::css::lang;
using namespace ::css::frame;

namespace
{
bool atWork = false;
}

class TerminateListener : public WeakImplHelper1<XTerminateListener>
{
public:
    // XTerminateListener
    virtual void SAL_CALL notifyTermination(const EventObject& event) SAL_OVERRIDE
    {
        std::cout << "About to terminate...\n";
    }

    virtual void SAL_CALL queryTermination(const EventObject& event) SAL_OVERRIDE
    {
        // Test if we can terminate now
        if (atWork)
        {
            std::cout << "Terminate while we are at work? You can't be serious ;-)!\n";
            throw TerminationVetoException();
        }
    }

    // XEventListener
    virtual void SAL_CALL disposing(const EventObject& event) SAL_OVERRIDE {}
};

SAL_IMPLEMENT_MAIN()
{
    try
    {
        // Connect to, or create, an instance of the Office.
        Reference<XComponentContext> xContext(bootstrap());
        std::cout << "Connected to a running office...\n";

        // Get a reference to the multi-component factory, and use it
        // to create a Desktop reference.
        Reference<XMultiComponentFactory> xMCF(xContext->getServiceManager());
        Reference<XDesktop> xDesktop(
            xMCF->createInstanceWithContext("com.sun.star.frame.Desktop", xContext),
            UNO_QUERY_THROW);

        // Create our termination request listener, and register it.
        TerminateListener listener;
        Reference<XTerminateListener> xTerminateListener(listener, UNO_QUERY_THROW);
        xDesktop->addTerminateListener(xTerminateListener);

        // Try to terminate while we are at work.
        atWork = true;
        bool terminated = xDesktop->terminate();
        std::cout << "The Office "
                  << (terminated ? "has been terminated" : "is still running, we are at work.")
                  << '\n';

        // Try to terminate when we are NOT at work.
        atWork = false;
        terminated = xDesktop->terminate();
        std::cout << "The Office "
                  << (terminated ? "has been terminated"
                                 : "is still running. Something else prevents termination, such as the quickstarter.")
                  << '\n';
    }
    catch (const RuntimeException& e)
    {
        std::cerr << e.Message << '\n';
        return 1;
    }
    return 0;
}
```

--------------------------------

### Instantiate Service and Query Interface in C++

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/First_Steps

Demonstrates creating a service instance and querying for the XComponentLoader interface in C++.

```cpp
// instantiate a sample service with the servicemanager.
Reference< XInterface > rInstance =
rServiceManager->createInstanceWithContext(
OUString::createFromAscii("com.sun.star.frame.Desktop" ),
rComponentContext );

// Query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader( rInstance, UNO_QUERY );
```

--------------------------------

### Implement XTypeProvider getImplementationId

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Provides a unique identifier for the implementation. Returns an empty sequence in this example, but should be a unique GUID.

```cpp
Sequence< sal_Int8 > MyService1Impl::getImplementationId()
{
    return css::uno::Sequence<sal_Int8>();
}

```

--------------------------------

### Help Integration Configuration Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

This example demonstrates the configuration for integrating add-on help into LibreOffice's Help menu. It specifies properties like 'oor:name', 'URL', 'Title', and 'ImageIdentifier' for menu items.

```xml
vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/image
```

--------------------------------

### Print Structured Filter Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Database_Access

An example demonstrating how to retrieve and print the structured filter of a query. This involves accessing the database context, a specific data source, connection, queries, and then using the SQLQueryComposer to get the structured filter.

```java
// prints the structured filter
public static void printStructeredFilter(XMultiServiceFactory _rMSF) throws com.sun.star.uno.Exception {
    XNameAccess xNameAccess = (XNameAccess)UnoRuntime.queryInterface(
        XNameAccess.class, _rMSF.createInstance("com.sun.star.sdb.DatabaseContext"));
    // we use the first datasource
    XDataSource xDS = UnoRuntime.queryInterface(
        XDataSource.class, xNameAccess.getByName("Bibliography"));
    XConnection con = xDS.getConnection("", "");
    XQueriesSupplier xQuerySup = UnoRuntime.queryInterface(
        XQueriesSupplier.class, con);

    XNameAccess xQDefs = xQuerySup.getQueries();

    XPropertySet xQuery = UnoRuntime.queryInterface(
        XPropertySet.class,xQDefs.getByName("Query1"));
    String sCommand = (String)xQuery.getPropertyValue("Command");

    XSQLQueryComposerFactory xQueryFac = UnoRuntime.queryInterface(
        XSQLQueryComposerFactory.class, con);

    XSQLQueryComposer xQComposer = xQueryFac.createQueryComposer();
    xQComposer.setQuery(sCommand);

    PropertyValue aFilter [][] = xQComposer.getStructuredFilter();
    for (int i=0; i<aFilter.length; ) {
        System.out.println("( ");
        for (int j=0; j<aFilter[i].length; ++j)
            System.out.println("Name: " + aFilter[i][j].Name + " Value: " + aFilter[i][j].Value);
            System.out.println(")");
            ++i;
            if (i<aFilter.length )
                System.out.println(" OR ");
        }
    }
}
```

--------------------------------

### Create UNO Service Instance

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Professional_UNO

Demonstrates how to create an instance of a UNO service using the service manager and obtain its XInterface.

```java
XInterface xint= (XInterface)
serviceManager.createInstance("com.sun.star.bridge.oleautomation.Factory");
```

--------------------------------

### Get extension location in C++

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Extensions

Retrieves the URL for an installed extension using its identifier. Ensure the 'PackageInformationProvider' singleton is accessed correctly.

```cpp
namespace css = com::sun::star;
css::uno::Reference< css::uno::XComponentContext > mxContext;
...
css::uno::Reference< css::deployment::XPackageInformationProvider >
xInfoProvider( css::deployment::PackageInformationProvider::get( mxContext ) );

// "MY_PACKAGE_ID" is the identifier of the package whose location we want
rtl::OUString sLocation = xInfoProvider->getPackageLocation(
rtl::OUString::createFromAscii( "MY_PACKAGE_ID" ) );
...
```

--------------------------------

### C++ Protocol Handler Configuration Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

This XML (XCU) configures a C++ protocol handler named 'org.openoffice.Office.addon.example' to handle URLs starting with 'org.openoffice.Office.addon.example:'.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="ProtocolHandler" oor:package="org.openoffice.Office">
    <node oor:name="HandlerSet">
        <node oor:name="org.openoffice.Office.addon.example" oor:op="replace">
            <prop oor:name="Protocols" oor:type="oor:string-list">
                <value>org.openoffice.Office.addon.example:*</value>
            </prop>
        </node>
    </node>
</oor:component-data>
```

--------------------------------

### OpenOffice 3.x Update Information Example (description.xml)

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Extensions

This XML snippet shows the structure for referencing update information for a German Windows OpenOffice 3.3.0 installation.

```xml
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="https://www.w3.org/2005/Atom" xml:lang="en-US">
<title>Product Update Feed</title>
<link rel="alternate" type="text/html" href="http://update.services.openoffice.org/ooo/snapshot.html"/>
<updated>2011-01-01T08:00:02Z</updated>
<author>
        <name>The OpenOffice Project</name>
        <uri>https://openoffice.org</uri>
        <email>updatefeed@openoffice.org</email>
</author>
<id>urn:uuid:76676544</id>
<entry>
        <title>Update available</title>
        <link rel="alternate" type="text/html" href="http://update.services.openoffice.org/ooo/snapshot.html"/>
        <id>urn:uuid:76676544</id>
        <!-- IMPORTANT: category MUST be equal with UpdateID in version.ini -->
        <category term="OpenOffice.org_3_de" label="OpenOffice.org update"/>
        <updated>2011-01-01T08:00:02Z</updated>
        <summary>Text below download information (should be localized)</summary>
        <content type="application/xml" xmlns:inst="http://installation.openoffice.org/description">
                <inst:id>OpenOffice.org_3_de</inst:id>
                <inst:version>'new version information'</inst:version>
                <!-- buildid must be higher as installed version -->
                <inst:buildid>9580</inst:buildid>
                <inst:os>Windows</inst:os>
                <inst:arch>x86</inst:arch>
                <!-- app/octet-stream generates direct download as background-process -->
                <!--<inst:update type="application/octet-stream" src="http://download.services.openoffice.org/files/localized/de/3.3.0/OOo_3.3.0_Win_x86_install-wJRE_de.exe"/>-->
                <!-- text/html opens src-link in default browser -->
                <inst:update type="text/html" src="http://download.openoffice.org"/>
        </content>
</entry>
</feed>
```

--------------------------------

### Configure LibreOffice Listening Mode (Pre-1.x Setup.xml)

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Professional_UNO

For versions before OpenOffice.org 1.x, modify the Setup.xml file to enable listening mode. This involves extending the ooSetupConnectionURL element.

```xml
<ooSetupConnectionURL cfg:type="string"/>
```

```xml
<ooSetupConnectionURL cfg:type="string">
socket,port=2083;urp;
</ooSetupConnectionURL>
```

--------------------------------

### Help Content Provider Examples

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Universal_Content_Providers

Illustrates various valid URL formats for accessing help content, including system and language parameters, and search queries.

```url
_vnd.sun.star.help://?System=WIN &Language=de_
```

```url
_vnd.sun.star.help://swriter?System=WIN &Language=de&Query=text&HitCount=120&Scope=Heading_
```

```url
_vnd.sun.star.help://portal/4711?System=UNIX &Language=en_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal_
```

--------------------------------

### Create XDatabaseMetaData Object

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Database_Access

Obtain an XDatabaseMetaData object from an existing Connection to query database information. This example shows how to get the maximum table name length.

```java
// xConnection is a Connection object
XDatabaseMetaData dbmd = xConnection.getMetaData();
int maxLen = dbmd.getMaxTableNameLength();
```

--------------------------------

### External Image URL Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Illustrates how to specify an external user-defined image for a toolbar item using the '%origin%' placeholder. This placeholder is substituted at runtime with the component's installation folder.

```xml
%origin%/image
```

--------------------------------

### Complete PyUNO Bootstrap and Proxy Setup

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Advanced_UNO

This function bootstraps the UNO environment and sets up UNO proxies for Invocation and Converter services. It handles potential errors during service creation.

```c++
static PyObject* newBootstrapPyUNO (PyObject* self, PyObject* args)
{
  char* ini_file_location;
  Reference<XComponentContext> tmp_cc;
  Any a;

  if (!PyArg_ParseTuple (args, "s", &ini_file_location))
    return NULL;
  tmp_cc = Util::bootstrap (ini_file_location) ;
  Reference<XMultiServiceFactory> tmp_msf (tmp_cc->getServiceManager (), UNO_QUERY);
  if (!tmp_msf.is ()) 
    {
      PyErr_SetString (PyExc_RuntimeError, "Couldn't bootstrap from inifile");
      return NULL;
    }
  Reference<XSingleServiceFactory> tmp_ssf (tmp_msf->createInstance (
      OUString ("com.sun.star.script.Invocation"), UNO_QUERY);
  Reference<XTypeConverter> tmp_tc (tmp_msf->createInstance (
      OUString ("com.sun.star.script.Converter"), UNO_QUERY);
  if (!tmp_tc.is ()) 
    {
      PyErr_SetString (PyExc_RuntimeError, "Couldn't create XTypeConverter");
      return NULL;
    }
  if (!tmp_ssf.is ()) 
    {
      PyErr_SetString (PyExc_RuntimeError, "Couldn't create XInvocation");
      return NULL;
    }
  a <<= tmp_cc;

  return PyUNO_new (a, tmp_ssf, tmp_tc) ;

}
```

--------------------------------

### Get extension location in Basic

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Extensions

Obtains the installation path of an extension using its identifier via the 'PackageInformationProvider' singleton. The returned URL points to the extension's directory, not the .oxt file itself.

```basic
Dim pip As Object, extensionLocation As String
Const extensionIdentifier = "org.toto.test3"

pip = GetDefaultContext.getByName("/singletons/com.sun.star.deployment.PackageInformationProvider")
extensionLocation = pip.getPackageLocation(extensionIdentifier)
' display a human readable address
MsgBox(ConvertFromURL(extensionLocation))
```

--------------------------------

### XML Filter Configuration Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Spreadsheet_Documents

This XML snippet shows the configuration for the MS Excel 97 filter within TypeDetection.xml. It includes details about installation status, UI name, and data mapping.

```xml
<Filter cfg:name="MS Excel 97">
<Installed cfg:type="boolean">true</Installed>
<UIName cfg:type="string" cfg:localized="true">
    <cfg:value xml:lang="en-US">Microsoft Excel 97/2000/XP</cfg:value>
</UIName>
<Data cfg:type="string">5,calc_MS_Excel_97,com.sun.star.sheet.SpreadsheetDocument,,3,,0,,</Data>
</Filter>
```

--------------------------------

### Demonstrate Progress Bar Functionality

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/LibreOffice_Basic

Initializes and sets up constants for a progress bar demonstration. This snippet sets the minimum, maximum, and step values for the progress bar.

```vb
Sub ProgressBarDemo()
  Dim oProgressBar as Object, oProgressBarModel As Object, oDialog as Object
  Dim ProgressValue As Long
  REM Dialog1 contains progress bar ProgressBar1 saved in standard library
  DialogLibraries.loadLibrary("Standard")
  oDialog = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
  REM progress bar settings
  Const ProgressValueMin = 0
  Const ProgressValueMax = 40
  Const ProgressStep = 4

```

--------------------------------

### Job Initialization with Environment Data

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

This URL starts a job with environment information. Optional dispatch arguments and generic configuration data can be passed. Configuration data specific to the job is not initialized if not provided.

```text
vnd.sun.star.job:alias=Job_1
```

--------------------------------

### Mouse Motion Listener Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Graphical_User_Interfaces

This snippet shows how to implement a mouse motion listener to change the mouse pointer when entering a control. It requires setup for the control's peer and a custom pointer.

```java
public void mouseEntered(MouseEvent _mouseEvent) {
    try {
        // retrieve the control that the event has been invoked at...
        XControl xControl = UnoRuntime.queryInterface(XControl.class, _mouseEvent.Source);
        Object tk = m_xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", m_xContext);
        XToolkit xToolkit = UnoRuntime.queryInterface(XToolkit.class, tk);
        // create the peer of the control by passing the windowpeer of the parent
        // in this case the windowpeer of the control
        xControl.createPeer(xToolkit, m_xWindowPeer);
        // create a pointer object "in the open countryside" and set the type accordingly...
        Object oPointer = this.m_xMCF.createInstanceWithContext("com.sun.star.awt.Pointer", this.m_xContext);
        XPointer xPointer = UnoRuntime.queryInterface(XPointer.class, oPointer);
        xPointer.setType(com.sun.star.awt.SystemPointer.REFHAND);
        // finally set the created pointer at the windowpeer of the control
        xControl.getPeer().setPointer(xPointer);
    } catch (com.sun.star.uno.Exception ex) {
        throw new java.lang.RuntimeException("cannot happen...", ex);
    }
}
```

--------------------------------

### Initialize UNO Service Manager and Create Document

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Professional_UNO

This snippet shows the initial steps to connect to the UNO service manager and create a new writer document. Ensure the UNO environment is set up before running.

```vbscript
'The service manager is always the starting point
'If there is no office running then an office is started up
Set objServiceManager= WScript.CreateObject("com.sun.star.ServiceManager")

'Create the CoreReflection service that is later used to create structs
Set objCoreReflection= objServiceManager.createInstance("com.sun.star.reflection.CoreReflection")

'Create the Desktop
Set objDesktop= objServiceManager.createInstance("com.sun.star.frame.Desktop")

'Open a new empty writer document
Dim args()
Set objDocument= objDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, args)
```

--------------------------------

### Example ScriptEditorForYourLanguage Implementation

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework

A sample implementation of the ScriptEditor interface for a custom language. It provides methods for editing, getting templates, and specifying file extensions. The execute() and indicateErrorLine() methods are not used by the Macro Organizer.

```java
import com.sun.star.script.framework.provider.ScriptEditor;
import com.sun.star.script.provider.XScriptContext;
import com.sun.star.script.framework.container.ScriptMetaData;

import javax.swing.*;

public class ScriptEditorForYourLanguage implements ScriptEditor
{
    public Object execute() throws Exception
    {
        return null;
    }

    public void indicateErrorLine( int lineNum )
    {
        return;
    }

    public void edit(XScriptContext context, ScriptMetaData entry)
    {
        JFrame frame = new JFrame();
        frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);

        JTextArea ta = new JTextArea();
        entry.loadSource();
        ta.setText(entry.getSource());

        frame.getContentPane().add(ta);
        frame.setSize(400, 400);
        frame.show();
    }

    public String getTemplate()
    {
        return "the code for a YourLanguage script";
    }

    public String getExtension()
    {
        return "yl";
    }
}
```

--------------------------------

### UNO Client Connection Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

This example demonstrates connecting a UNO client to a running LibreOffice instance using a socket connection. It shows how to resolve a remote object and interact with it by reading and writing byte arrays.

```bash
I:\tmp>java UnoExeClient uno:socket,host=localhost,port=2083;urp;test
 Available bytes : 5
 read 2:1,2
 Available bytes : 3
 read 3:3,4,5
 Terminating client
```

--------------------------------

### Document Package Structure with Multiple Libraries

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/LibreOffice_Basic

Details the package structure for a LibreOffice document containing multiple Basic libraries and one Dialog library. This example showcases a more complex setup with custom-named libraries and dialogs.

```text
<Package> ExampleDocument2
 |
 |--<DIR> Basic
 |  |
 |  |--<DIR> Standard      ' Folder: Contains library "Standard"
 |  |  |
 |  |  |--Module1.xml      ' Stream: Basic module file
 |  |  |--Module2.xml      ' Stream: Basic module file
 |  |  |--script-lb.xml    ' Stream: Basic library index file
 |
 |  |--<DIR> Library1      ' Folder: Contains library "Library1"
 |  |  |
 |  |  |--Module1.xml      ' Stream: Basic module file
 |  |  |--script-lb.xml    ' Stream: Basic library index file
 |
 |  |--script-lc.xml       ' Stream: Basic library container index file
 |
 |--<DIR> Dialogs
 |  |
 |  |--<DIR> Standard      ' Folder: Contains library "Standard"
 |  |  |
 |  |  |--Dialog1.xml      ' Stream: Dialog file
 |  |  |--dialog-lb.xml    ' Stream: Dialog library index file
 |
 |  |--<DIR> Library1      ' Folder: Contains library "Library1"
 |  |  |
 |  |  |--Dialog1.xml      ' Stream: Dialog file
 |  |  |--Dialog2.xml      ' Stream: Dialog file
 |  |  |--dialog-lb.xml    ' Stream: Dialog library index file
 |
 |  |--dialog-lc.xml       ' Stream: Dialog library container index file
 |
 | ' From here the folders and streams have nothing to do with libraries
 |--<DIR> Meta-Inf
 |--content.xml
 |--settings.xml
 |--styles.xml

```

--------------------------------

### Frame Setup and Component Linking

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/OfficeDev/Frame-Controller-Model_Paradigm_in_OpenOffice.org

Methods for setting up the container window and linking a component's window and controller to the frame. The initialize method expects a top-level window.

```uno
// methods for container window
void initialize ( [in] com::sun::star::awt::XWindow xWindow);
com::sun::star::awt::XWindow getContainerWindow ();

// methods for component window and controller
boolean setComponent ( [in] com::sun::star::awt::XWindow xComponentWindow,
                        [in] com::sun::star::frame::XController xController );
com::sun::star::awt::XWindow getComponentWindow ();
com::sun::star::frame::XControllergetController ();
```

--------------------------------

### Bootstrap and Connect to Service Manager

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Demonstrates bootstrapping a local component context and connecting to either a local or remote service manager based on command-line arguments. It handles URL resolution for remote connections.

```java
public static void main(String[] args) throws java.lang.Exception {
    if (args.length != 1) {
        System.out.println("usage: RunComponent local|uno-url");
        System.exit(1);
    }
    XComponentContext xLocalComponentContext =
        Bootstrap.createInitialComponentContext(null);

    // initial serviceManager
    XMultiComponentFactory xLocalServiceManager = xLocalComponentContext.getServiceManager();

    XMultiComponentFactory xUsedServiceManager = null;
    XComponentContext xUsedComponentContext = null;
    if (args[0].equals("local")) {
        xUsedServiceManager = xLocalServiceManager;
        xUsedComponentContext = xLocalComponentContext;

        System.out.println("Using local servicemanager");
        // now the local servicemanager is used !
    }
    else {
        // otherwise interpret the string as uno-url
        Object xUrlResolver = xLocalServiceManager.createInstanceWithContext(
            "com.sun.star.bridge.UnoUrlResolver", xLocalComponentContext);
        XUnoUrlResolver urlResolver = UnoRuntime.queryInterface(
            XUnoUrlResolver.class, xUrlResolver);
        Object initialObject = urlResolver.resolve(args[0]);
        xUsedServiceManager = UnoRuntime.queryInterface(
            XMultiComponentFactory.class, initialObject);

```

--------------------------------

### Install Extension for All Users using unopkg

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Extensions

Use the --shared option with the unopkg command to install an extension for all users. This requires write access to the office installation's share directory.

```bash
[<OfficePath>/program] $ unopkg add --shared my_extension.oxt

```

--------------------------------

### Collapse Cursor to Start

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Text_Documents

Collapse the text cursor to its starting position, effectively making it a point.

```Java
void collapseToStart()
```

--------------------------------

### Run UNO Component

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Executes a registered UNO component using the `uno` tool. This command should produce 'hello world !' output.

```bash
uno -s MyMain -ro types.rdb -ro services.rdb -ro test.rdb
```

--------------------------------

### Multi-line Code Listing

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/IDL_Documentation_Guidelines

The <listing> markup is used for multiple line code examples. This example is in StarBASIC.

```StarBASIC
aCmp = StarDesktop.loadComponentFromURL( ... )
if ( isnull(aCmp) )
....
endif
```

--------------------------------

### C++ UNO Component Implementation Example

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Provides a comprehensive example of a C++ UNO component, including interface inheritance, service information, and initialization. The implementation details for XSomething, XServiceInfo, and XInitialization are omitted.

```cpp
#include <cppuhelper/implbase3.hxx> // "3" implementing three interfaces
#include <cppuhelper/factory.hxx>
#include <cppuhelper/implementationentry.hxx>

#include <com/sun/star/lang/XServiceInfo.hpp>
#include <com/sun/star/lang/XInitialization.hpp>
#include <com/sun/star/lang/IllegalArgumentException.hpp>
#include <my_module/XSomething.hpp>

using namespace ::rtl; // for OUString
using namespace ::com::sun::star; // for sdk interfaces
using namespace ::com::sun::star::uno; // for basic types

namespace my_sc_impl
{

class MyService2Impl : public ::cppu::WeakImplHelper3<
      ::my_module::XSomething, lang::XServiceInfo, lang::XInitialization >
{
    OUString m_arg;
public:
    // focus on three given interfaces,
    // no need to implement XInterface, XTypeProvider, XWeak

    // XInitialization will be called upon createInstanceWithArguments[AndContext]()
    virtual void SAL_CALL initialize( Sequence< Any > const & args );
    // XSomething
    virtual OUString SAL_CALL methodOne( OUString const & str );
    // XServiceInfo
    virtual OUString SAL_CALL getImplementationName();
    virtual sal_Bool SAL_CALL supportsService( OUString const & serviceName );
    virtual Sequence< OUString > SAL_CALL getSupportedServiceNames();
};

// Implementation of XSomething, XServiceInfo and XInitilization omitted here:
...

// component operations from service1_impl.cxx
extern Sequence< OUString > SAL_CALL getSupportedServiceNames_MyService1Impl();
extern OUString SAL_CALL getImplementationName_MyService1Impl();
extern Reference< XInterface > SAL_CALL create_MyService1Impl(
                                        Reference< XComponentContext > const & xContext );
// component operations for MyService2Impl
static Sequence< OUString > getSupportedServiceNames_MyService2Impl()
{
    Sequence<OUString> names(1);
    names[0] = OUString("my_module.MyService2");
    return names;
}

static OUString getImplementationName_MyService2Impl()
{
    return OUString( "my_module.my_sc_implementation.MyService2" );
}

Reference< XInterface > SAL_CALL create_MyService2Impl(
    Reference< XComponentContext > const & xContext )
{
      return static_cast< lang::XTypeProvider * >( new MyService2Impl() );
}
/* shared lib exports implemented without helpers in service_impl1.cxx */
namespace my_sc_impl
{
static struct ::cppu::ImplementationEntry s_component_entries [] =
{
    {
        create_MyService1Impl, getImplementationName_MyService1Impl,
        getSupportedServiceNames_MyService1Impl, ::cppu::createSingleComponentFactory,
        0, 0
    },
    {
        create_MyService2Impl, getImplementationName_MyService2Impl,
        getSupportedServiceNames_MyService2Impl, ::cppu::createSingleComponentFactory,
        0, 0
    },
    { 0, 0, 0, 0, 0, 0 }
};
}

extern "C"
{
void * SAL_CALL component_getFactory(
    char const * implName, lang::XMultiServiceFactory * xMgr,
    registry::XRegistryKey * xRegistry )
{
    return ::cppu::component_getFactoryHelper(
        implName, xMgr, xRegistry, ::my_sc_impl::s_component_entries );
}

// getImplementationEnvironment and component_writeInfo are described later, we omit  them here
...
}

```

--------------------------------

### Simple License Configuration in description.xml

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Extensions

Defines how a license is presented to the user during extension installation. Use 'accept-by="user"' to require all users to agree, or 'accept-by="admin"' for only the installer to agree. Ensure license text files are UTF-8 encoded.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<description xmlns="http://openoffice.org/extensions/description/2006"
xmlns:xlink="http://www.w3.org/1999/xlink">
<registration>
    <simple-license accept-by="user" >
    <license-text xlink:href="registration/license_de.txt" lang="de" />
    <license-text xlink:href="registration/license_en_US.txt" lang="en-US" />
    </simple-license>
</registration>
</description>
```

--------------------------------

### Example Dispatched URL for C++ Handler

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

This shows an example of a dispatched URL that the C++ protocol handler can route.

```text
 org.openoffice.Office.addon.example:Function1
```

--------------------------------

### UNO Executable Usage

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Illustrates the command-line syntax for the UNO executable. It shows options for specifying components by implementation name or service name, registry configurations, and remote connection methods.

```bash
uno (-c ComponentImplementationName -l LocationUrl | -s ServiceName)
    [-ro ReadOnlyRegistry1] [-ro ReadOnlyRegistry2] ... [-rw ReadWriteRegistry]
 [-u uno:(socket[,host=HostName][,port=nnn]|pipe[,name=PipeName]);urp;Name [--singleaccept] [--singleinstance]]
 [-- Argument1 Argument2 ...]
```

--------------------------------

### Complete URI Examples - My Macros

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework

Examples of URIs used to call scripts stored in the 'My Macros' location.

```text
vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application
```

```text
vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=user
```

```text
vnd.sun.star.script:myLibrary.myMethod?language=Java&location=user
```

```text
vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=user
```

```text
vnd.sun.star.script:myModule.py$myFunction?language=Python&location=user
```

--------------------------------

### Install UNO Extension

Source: https://wiki.documentfoundation.org/Documentation/DevGuide/Writing_UNO_Components

Use the unopkg tool to add an extension to LibreOffice. Ensure LibreOffice is not running before installation.

```bash
[<OfficePath>/program] $ unopkg add /foo/bar/example_addon.zip
```
Tokens:
Raw