Oprettelse af Python-scripts med ScriptForge

Forskelle mellem Basic og Python

Biblioteket ScriptForge er tilgængeligt for både Basic og Python. De fleste tjenester, metoder og egenskaber fungerer på samme måde i begge programmeringssprog. På grund af forskelle i, hvordan hvert sprog virker, skal ScriptForge-brugere være bevidst om nogle programmets karakteristika ved brug af Python:

Metoder og egenskabsnavne : I Python kan alle metoder og egenskaber bruges skrevet med småt, med stort begyndelsesbogstav af hvert ord i SammensatteOrd ("KamelFormat"), eller stort bogstav af nye ord i sammensatteOrd ("kamelFormat").
Arguments: All keyword arguments passed on to methods are lowercased.
Datoer: Alle dato-objekter videregives og returneres som datetime.datetime hjemmehørende Python-objekter.
Matrixer: En-dimensionelle matrixer videregives og returneres som tupler (er et uforanderligt objekt). To-dimensionelle matrixer videregives og returneres som tupler af tupler.
Ingen: Python's nøgleord None (Ingen)er ligeværdigt med Basic's Null (Nul), Empty (Tom) eller Nothing (Intet).
UNO-objekter: Alle UNO-strukturer udveksles mellem Basic og Python uden nogle ændringer.
Fejlsøgning: Nårsomhelst der sker en fejl i Python-scripts, der bruger ScriptForge, viser fejlbeskeden, der gives af Pythons kørselsstak, den kodelinje, der udløste fejlen. I Basic viser fejlbeskeder ikke denne oplysning.

Besøg Hjælp til LibreOffice Python-scripter og se flere oplysninger om Python-scriptarbejde med LibreOffice.

Redigering af Python-scripts i IDE'er

Mens du redigerer Python-scripts kan du få indskrivningstips ‒ relateret til ScriptForge-tjenesters offentlige metoder og egenskaber ‒ fra IDE'er som understøtter denne funktion. Visuelt mens du redigerer et brugerscript:

Når musemarkøren holdes over en objektinstans, en metode eller en egenskab, vises dens detaljerede beskrivelse.
Et "." efter en objektinstans viser et rullegardin-felt med alle de tilgængelige grænseflader.
Parentes efter et metodenavn starter kode-fuldførelse ved at vise metodens argumenter.

Skrivetips vises når metoder og egenskaber redigeres med korrekte store og små bogstaver.

Kørsel af Python-scripts under LibreOffice

Afhængigt af hvad du har tænkt at opnå, kan du vælge en af følgende måder at udføre Python-scripts i LibreOffice:

Udfør scripts i den aktuelle LibreOffice-proces: Python-scripts udføres inde fra LibreOffice-processen ved at bruge menuen Funktioner ▸ Makroer ▸ Udfør makro eller APSO-udvidelsen til at kalde brugerscripts gemt i mappen til Python-scripts. Du kan også bruge APSO Python-skallen til at udføre Python-scripts interaktivt.
Udfør scripts separat fra LibreOffice-processen: Python-scripts udføres fra en ekstern proces, som forbinder til en kørende LibreOffice-proces med brug af et rør (en pipe) eller en sokkel (en socket).

Hvis du planlægger at udføre scripts inde fra LibreOffice-processen, anbefales det at installere APSO-udvidelsen (Alternativ Python-scriptorganisator). Hvis du derimod vil udvikle Python-scripts udenfor LibreOffice, kan du vælge dit foretrukne Python-IDE.

Udførelse af scripts inde fra LibreOffice-processen

Brug af APSO-udvidelsen

Den letteste måde at komme i gang med at bruge Python-scipts i LibreOffice er ved at installere APSO-udvidelsen. Efter installation af den, åbn en hvilken som helst LibreOffice-komponent og gå til Funktioner ▸ Makroer ▸ Administrér Python-scripts.

I hovedvinduet for APSO går du til Menu ▸ Python-skal.

Alternativt kan du åbne APSO med standardgenvejen Alt + Skift + F11.

Nu kan du begynde at taste Pyton-kommandoer, og skallen vil vil udskrive det tilsvarende output efter at hver kodelinjer er udført.

For at begynde at bruge ScriptForge-biblioteket, må du importere CreateScriptService-metoden. Med denne har du tilgang til de tjenester, som biblioteket tilbyder. Eksemplet herunder bruger Basic-tjenesten til at vise et beskedfelt.


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

For at udføre eksemplet ovenfor, skriv hver linje ind i Python-skallen, én efter én, hvor du trykker Enter-tasten hver gang du har tastet en kodelinje.

Nu kan du begynde at udføre Python-kommandoer med en hvilken som helst af ScriptForge-tjenesterne. For eksempel bruger kodestykket herunder tjenesten UI (User Interface = brugerflade) til at oprette et tomt Writer-dokument.


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

Oprettelse af Python-scriptfiler

Du kan oprette dine egne Pythonfiler og redigere dem med din foretrukne teksteditor. Senere kan du kalde dem fra en hvilken som helst LibreOffice-komponent.

Det første skridt er at finde ud af, hvor dine brugerscripts er gemt. Se hjælpesiden Administration og placering af Python-scripts.

Nu kan du oprette en tekstfil i din Python-brugerscriptmappe, for eksempel mit_script.py, og begynde at skrive dine scipts.

Det næste er et simpel eksempel, som henter en numerisk værdi fra en Calc-celle og forøger den med 1. Bare skriv følgende kode i mit_script.py-filen.


    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, )

Dette eksempel opretter funktionen increment_cell. Bemærk at g_exportedScripts er en tupel, som fortæller, hvilke funktioner der vil blive vist i LibreOffice som bruger-scripts.

Sådan udfører du dette script fra et Calc-dokument:

Opret eller åbn en Calc-fil.
Skriv en numerisk værdi i celle "A1" i den aktuelle ark.
Gå til Funktioner ▸ Makroer ▸ Udfør makro.
Vælg Mine makroer ▸ mit_script i biblioteksvælgeren. Vælg så increment_cell-funktionen under listen Makronavn.
Klik på Udfør. Bemærk at værdien i celle "A1" blev forøget med 1.

Du kan også bruge APSO til at udføre Python-scripts på en lignende måde:

Åbn først APSO ved at gå til Funktioner ▸ Makroer ▸ Administrér Python-scripts.
I makrolisten navigerer du til Mine makroer ▸ mit_script ▸ increment_cell.
Klik på Udfør.

Running Scripts separately from the LibreOffice process

Determining the Installation Path

The first step to run scripts from a separate process is to find the folder where LibreOffice is installed. There are several ways to do that, but ScriptForge provides a quick way to identify your installation path. For that, open APSO's Python shell and type:


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

The output from the code above is the base directory where LibreOffice is installed. Now you need to add the "program" subfolder to the resulting path. This is the base folder from which you will run Python scripts from a separate process.

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 LibreOffice with pipe or socket settings

To run Python scripts from a separate process, you need to start LibreOffice with a few additional options that specify pipe name or the hostname and port through which the external process will communicate with the LibreOffice component process.

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

On Linux / Mac OS:

libreoffice --accept='pipe,name=aPipeName;urp;'

On Windows:

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

as a flatpak:

flatpak run org.libreOffice.LibreOffice accept='socket,host=localhost,port=2021;urp;'

Either command above will start LibreOffice with a communication channel open so that other processes can exchange messages with it.

Note that the previous example opens LibreOffice 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 name, or host and port parameters, which in this example are aPipeName, or localhost and 2021, respectively.

Running an External Python Shell

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

On Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

On Windows:

$ 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 LibreOffice. But first you need to set up the pipe or the socket connection. The ScriptForge() statement below must precede the very first call to CreateScriptService().

Run either:


   from scriptforge import ScriptForge, CreateScriptService
   ScriptForge(pipe='aPipeName')


    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 pipe or host and port settings so that the Python shell can communicate with an ongoing LibreOffice process opened with the same pipe or socket settings.

Now you can run other Python commands and they will be able to communicate with the LibreOffice 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 LibreOffice installation method.

Biblioteket ScriptForge

Hjælp til LibreOffice Pythonscripts

Start af LibreOffice-software med parametere