Laga Python-skript med ScriptForge

Skilnadar mellom Basic og Python

Biblioteket ScriptForge er tilgjengeleg for både Basic og Python. Dei fleste tenester, metodar og eigenskapar fungerer på same måte i begge programmeringsspråka. På grunn av skilnadar i korleis kvart av språka fungerer, må brukarane av ScriptForge vera klar over nokre av eigenskapane ved bruk av Python:

Metodar og namn på eigenskapar: I Python kan alle metodar og eigenskapar brukast i format med små bokstavar, eigennamn eller camelCased.
Argument: Alle argument-nøkkelord som vert sende vidare til metodar vert skrivne med små bokstavar.
Datoar: Alle datoobjekt vert sende og returnerte som datetime.datetime opphavlege Python-objekt.
Matriser: Eindimensjonale matriser vert sende og returnerte som tuplar (som er eit objekt som ikkje kan endrast). Todimensjonale matriser vert sende og returnerte som tuplar av tuplar.
Ingen: Pythonnøkkelordet None er likeverdige med Basic sine Null, Empty og Nothing.
UNO-objekt: Alle UNO-strukturar kan utvekslast mellom Basic og Python utan endringar.
Feilsøking: Når det oppstår ein feil i Python-skript som brukar ScriptForge, viser feilmeldinga frå Python-køyringsstabelenen kodelinja som utløyste feilen. I Basic-feilmeldingar vert denne informasjonen ikkje vist.

Sjå Hjelp til LibreOffice Python-skript for å sjå fleire opplysningar om bruk av Python-skript i LibreOffice.

Redigera Python-skript i IDEs

Medan du redigerer eit brukarskript kan du få innskrivingstips for Python ‒ relateret til ScriptForge-tenester sine offentlege metodar og eigenskapar ‒ frå IDE-ar som støttar ein slik funksjon:

ved å halda musepeikaren over ein objektførekomst, ein metode eller ein eigenskap vert det vist ei detaljert forklaring.
eit "." etter ein objektførekomst viser ein nedtrekksboks med alle tilgjengelege grensesnitt.
parentes etter eit metodenamn byrjar kodefullføringa ved å visa argumenta.

Det vert vist skrivetips med store bokstavar når du redigerar metodar og eigenskapar.

Køyra Pythonskript i LibreOffice

Avhengig av kva du vil oppnå, kan du velja ein av desse måtane for å køyra Python-skript i LibreOffice:

Køyra skript i gjeldande LibreOffice-prosess: Python-skript vert køyrde inne i LibreOffice-prosessen ved hjelp av menyen Verktøy → Makroar → Køyr makro eller APSO-utvidinga for å kalla opp brukarskript som er lagra i pythonskriptmapp. Du kan også bruka APSO Python-skalet til å køyra Python-skript interaktivt.
Run Scripts separately from the LibreOffice process: Python scripts are executed from an external process that connects to an ongoing LibreOffice process using a pipe or a socket.

Viss du køyrer skript inne frå LibreOffice-prosessen, vert det tilrådd å installera utvidinga APSO (Alternative Script Organizer for Python). Viss du vil utvikla Python-skript utanfor LibreOffice, kan du velja den Python-IDE-en du likar best.

Å køyra skript frå innføre LibreOffice-prosessen

Med APSO-utvidinga

Den enklaste måten å koma i gang med Python-skripting i LibreOffice, er å installera APSO-utvidinga. Når du har installert ho, opnar du kva LibreOffice-komponent som helst og går til Verktøy → Makroar → Organiser Pythonskript.

I hovudvindauget for APSO går du til Meny → Python-skal.

Du kan også opna APSO med standardsnarvegen Alt + Skift + F11.

No kan du skriva inn Python-kommandoar. Skalet vil skriva ut dei tilsvarande utdataa når kvar kodelinje er utført.

For å bruka biblioteket ScriptForge må du importera metoden CreateScriptService. Med denne har du tilgang til dei tenestene som biblioteket har. Eksempelet nedanfor brukar tenest Basic for å visa ein meldingsboks.


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

Viss du vil køyra eksempelet ovanfor, skriv du inn kvar linje i Python-skalet éi etter éi, og trykkjer Enter etter at du har skrive inn kvar kodelinje.

No kan du byrja å køyra Python-kommandoar ved hjelp av alle ScriptForge-tenestene. Kodesnutten nedanfor brukar for eksempel UI-tenesta til å laga eit tomt Writer-dokument.


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

Oppretta Python skriptfiler

Du kan laga dine eigne Python-filer og redigera dei med det tekstredigeringsprogrammet du likar best. Seinare kan du kalla dei opp frå kva LibreOffice-komponent som helst.

Det første steget er å finna ut kvar brukarskripta er lagra. Sjå hjelpsidene Pythonskript, organisering og lokalisering.

Nå kan du oppretta ei tekstfil i Python-brukarskriptmappa, for eksempel sf_test.py og byrja å skriva skripta dine.

Det neste er eit enkelt eksempel som hentar talverdien frå ei Calc-celle og aukar denne med 1. Berre skriv inn denne koden i fila sf_test.py.


    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 eksempelet opprettar funksjonen increment_cell. Merk at g_exportedScripts er ein tuple som fortel kva funksjonar som vert viste i LibreOffice som brukar-skript.

Slik køyrer du dette skriptet frå eit Calc-dokument:

Lag eller opna ei Calc-fil.
Skriv inn nokre talverdiar i cella «A1» i det gjeldande arket.
Gå til menyen Verktøy → Makroar → Køyr makro.
Vel «Mine makroar» → «sf_test» i bibliotekveljaren. Vel så funksjonen increment_cell i lista Makronamn.
Trykk på Run. Merk at verdien i cella «A1» vert auka med 1.

Du kan også bruka APSO for å køyra Python-skript på ein liknande måte:

Opna først APSO ved å gå til Verktøy → Makroar → Organiser Python-skript.
Naviger til Mine makroar → sf_test → increment_cell på makrolista .
Trykk på Køyr.

Å køyra skript uavhengig av LibreOffice-prosessen

Bestemma installasjonsstien

Det første steget for å køyra skript frå ein uavhengig prosess, finn du i mappa der LibreOffice er installert. Det er fleire måtar å gjere dette på, men ScriptForge har ein rask måte å identifisera installasjonsstien på. Opna APSO sitt Python-skal og skriv:


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

Utdataa frå koden ovanfor er basismappa der LibreOffice er installert. Nå må du leggja til «program»-undermappa i den resulterande stien. Dette er basismappa du vil køyra Python-skript frå i ein uavhengig prosess.

Gå for eksempel ut frå at du får /usr/lib/libreoffice/ som resultat av å køyra Python-koden ovanfor. Så får du vurdera om /usr/lib/libreoffice/program er den beste stien å køyra Python-skripta frå.

Start LibreOffice with pipe or socket settings

Viss du vil køyra Python-skript frå ein eigen prosess, må du starta LibreOffice med nokre få tilleggsinnstillingar som spesifiserer vertsnamnet og porten som den eksterne prosessen skal kommunisera med komponentprosessen LibreOffice gjennom.

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

./soffice --accept='pipe,name=libreoffice;urp;'

./soffice --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 libreoffice, or localhost and 2021, respectively.

Køyra eit eksternt Python-skal

Opna Python-skalet frå mappa program i installasjonsstien for LibreOffice. Følg stega ovanfor for å læra å finna installasjonsstien.

I Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

I 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='libreoffice')


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

Les bolken Setja opp PYTHONPATH nedanfor i tilfelle feil ved import av scriptforge.py eller 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.

No kan du køyra andre Python-kommandoar, og dei vil kunna kommunisera med LibreOffice-prosessen. For eksempel:


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

Setja opp PYTHONPATH

Avhengig av korleis operativsystemet er sett opp, må du setja miljøvariabelen PYTHONPATH for å kunna importera scriptforge.py-biblioteket, som igjen krev import av uno.py-biblioteket.

Bruk filsøkingsverktøyet i operativsystemet for å finna mappa der begge desse filene er sette inn.

For eksempel i eit standard Ubuntu-oppsett kan begge filene vera i:

scriptforge.py: Plassert i /usr/lib/libreoffice/program
uno.py: Plassert i /usr/lib/python3/dist-packages

I dette tilfellet set du omgivnadsvariabelen PYTHONPATH som vist her ffør du opnar Python-tolkaren:

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

Plasseringa av desse filene vil vera ulik for kvart operativsystem og LibreOffice-installasjonsmetode.

ScriptForge-biblioteket

LibreOffice Pythonskript hjelp

Start av LibreOffice med parametrane