Creating Python Scripts with ScriptForge

Differences between Basic and Python

A ScriptForge programkönyvtár elérhető Basic és Python nyelven is. A legtöbb szolgáltatás, metódus és tulajdonság azonos módon működik mindkét programozási nyelven. Az egyes nyelvek működésének különbségei miatt azonban a ScriptForge felhasználóknak tisztában kell lenniük a programkönyvtár néhány jellemzőjével, ha Python nyelvet használnak:

Methods and Property names: In Python, all methods and properties can be used in lowercased, ProperCased or camelCased formats.
Arguments: All keyword arguments passed on to methods are lowercased.
Dates: All date objects are passed and returned as datetime.datetime native Python objects.
Arrays: One-dimensional arrays are passed and returned as tuples (which is an immutable object). Two-dimensional arrays are passed and returned as tuples of tuples.
None: Python's None keyword is equivalent to Basic's Null, Empty or Nothing.
UNO objects: All UNO structures are exchanged between Basic and Python without any changes.
Hibakeresés: Amikor hiba lép fel a ScriptForge-t használó Python parancsfájlokban, a Python végrehajtási verem által biztosított hibaüzenet megjeleníti a hibát kiváltó kódsort. A Basicben a hibaüzenetek nem jelenítik meg ezt az információt.

Visit Collabora Office Python Scripts Help for more information on Python scripting using Collabora Office.

Running Python scripts on Collabora Office

Depending on what you intend to achieve, you may choose one of the following approaches to running Python scripts in Collabora Office:

Parancsfájlok futtatása az aktuális Collabora Office folyamaton belül: A Python parancsfájlok a Collabora Office folyamaton belül az Eszközök - Makrók - Makró futtatása menü vagy az APSO kiterjesztés segítségével a Python parancsfájlok mappában tárolt felhasználói parancsfájlok meghívásával futtathatók. Az APSO Python shell segítségével interaktívan is futtathat Python parancsfájlokat.
Run Scripts separately from the Collabora Office process: Python scripts are executed from an external process that connects to an ongoing Collabora Office process using a socket.

Ha a Collabora Office folyamaton belülről tervez parancsfájlokat futtatni, ajánlott telepíteni a APSO (Alternative Script Organizer for Python) bővítményt. A Python parancsfájlok Collabora Office folyamaton kívülről történő fejlesztéséhez azonban kiválaszthatja az Ön által preferált Python IDE-t.

Running Scripts from inside the Collabora Office process

Using the APSO extension

A legegyszerűbben az APSO bővítmény telepítésével kezdheti el a Python parancsfájlok írását a Collabora Office programban. Telepítése után nyissa meg bármelyik Collabora Office komponenst, és használja az Eszközök - Makrók - Python parancsfájlok rendezése menüparancsot.

In APSO's main window go to Menu - Python Shell.

Alternatively you can open APSO using the default shortcut Alt + Shift + F11.

Now you can start typing Python commands and the shell will print the corresponding output after each line of code is executed.

A ScriptForge könyvtár használatának megkezdéséhez importálnunk kell a CreateScriptService metódust, amellyel hozzáférhetünk a könyvtár által nyújtott szolgáltatásokhoz. Az alábbi példa a Basic szolgáltatást használja egy üzenetmező megjelenítésére.


    from scriptforge import CreateScriptService
    bas = CreateScriptService("Basic")
    bas.MsgBox("Hello!")

To run the example above, enter each line in the Python shell, one by one, pressing the Enter key after you type each line of code.

Now you can start executing Python commands using any of the ScriptForge services. For example, the code snippet below uses the UI service to create a blank Writer document.


    ui = CreateScriptService("UI")
    doc = ui.CreateDocument("Writer")

Creating Python script files

You can create your own Python files and edit them with your preferred text editor. Later you can call them from within any Collabora Office component.

The first step is to locate where your user scripts are stored. For that, refer to Python Scripts Organization and Location help page.

Now you can create a text file inside your Python user scripts folder, for instance sf_test.py, and start typing your scripts.

Next is a simple example that gets the numeric value from a Calc cell and increments it by 1. Simply type the following code into the sf_test.py file.


    from scriptforge import CreateScriptService
    doc = CreateScriptService("Calc")
    
    def increment_cell(args=None):
        value = doc.GetValue("A1")
        value += 1
        doc.SetValue("A1", value)
    
    g_exportedScripts = (increment_cell, )

This example creates the increment_cell function. Note that g_exportedScripts is a tuple that tells which functions will be displayed in Collabora Office as user scripts.

To run this script from within a Calc document:

Create or open a Calc file.
Enter some numeric value into cell "A1" in the current sheet.
Go to Tools - Macros - Run Macros .
Choose My Macros - sf_test in the library selector. Then choose the increment_cell function under the Macro Name list.
Click Run. Note that the value in cell "A1" was incremented by 1.

You can also use APSO to run Python scripts in a similar manner:

First open APSO by going to Tools - Macros - Organize Python Scripts.
In the macro list, navigate to My Macros - sf_test - increment_cell.
Kattintson a Végrehajtás gombra.

Running Scripts separately from the Collabora Office process

Determining the Installation Path

A parancsfájlok különálló folyamatból történő futtatásának első lépése, hogy megkeresse azt a mappát, ahová a Collabora Office telepítve van. Ennek több módja is van, de a ScriptForge egy gyors módszert kínál a telepítési útvonal azonosítására. Ehhez nyissa meg az APSO Python héját, és írja be a következőt:


    from scriptforge import CreateScriptService
    fs = CreateScriptService("FileSystem")
    fs.FileNaming = "SYS"
    inst_dir = fs.InstallFolder
    print(inst_dir)

A fenti kód kimenete az alapkönyvtár, ahová a Collabora Office telepítve van. Most hozzá kell adnia a "program" almappát a kapott elérési útvonalhoz. Ez az az alapmappa, ahonnan a Python parancsfájlokat egy külön folyamatból fogja futtatni.

For example, suppose you get /usr/lib/libreoffice/ as the result from running the Python code above. Then you need to consider /usr/lib/libreoffice/program as the path to run your Python scripts.

Start Collabora Office with socket settings

A Python-parancsfájlok különálló folyamatból történő futtatásához el kell indítania a Collabora Office programot néhány további opcióval, amelyek megadják azt a gépnevet és portot, amelyen keresztül a külső folyamat kommunikálni fog a Collabora Office komponensfolyamatával.

Open the your operating system's command prompt, navigate to the program folder of your Collabora Office installation directory and type:

./soffice --accept='socket,host=localhost,port=2021;urp;'

The command above will start Collabora Office with a communication channel open so that other processes can exchange messages with it.

Note that the previous example opens Collabora Office start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows.

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Take note of the host and port parameters, which in this example are localhost and 2021, respectively.

Running an External Python Shell

Start the Python shell from within the program folder inside your Collabora Office installation path. Follow the steps above to learn how to find your installation path.

On Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

Windowson:

$ cd C:\Program Files\LibreOffice\program\

$ python.exe

This will open the Python shell and now you can start typing commands that will be executed by Collabora Office. But first you need to set up the socket connection.


    from scriptforge import ScriptForge, CreateScriptService
    ScriptForge(hostname='localhost', port=2021)

Read the section Setting PYTHONPATH below in case of errors importing scriptforge.py or uno.py.

The second line of code above defines the host and port settings so that the Python shell can communicate with an ongoing Collabora Office process opened with the same socket settings.

Now you can run other Python commands and they will be able to communicate with the Collabora Office process. For example:


    ui = CreateScriptService("UI")
    bas = CreateScriptService("Basic")
    doc = ui.OpenDocument("~/Documents/myFile.ods")
    bas.MsgBox(doc.DocumentType)

Setting PYTHONPATH

Depending on your operating system's configuration you will need to set the environment variable PYTHONPATH in order to import the scriptforge.py library, which in turn requires importing the uno.py library.

Use your operating system's file search tool to determine the directory where both these files are located.

For instance, on a default Ubuntu installation both files may be located at:

scriptforge.py: Located in /usr/lib/libreoffice/program
uno.py: Located in /usr/lib/python3/dist-packages

In this case, set the environment variable PYTHONPATH as follows before starting the Python interpreter:

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

The location of these files will be different for each operating system and Collabora Office installation method.

A ScriptForge programkönyvtár

Collabora Office Python parancsfájlok súgója

Starting Collabora Office Software With Parameters