Spis treści

# Tworzenie skryptów w języku Python za pomocą ScriptForge

## Różnice między językiem Basic a językiem Python

Biblioteka ScriptForge jest dostępna zarówno dla języka Basic, jak i Pythona. Większość usług, metod i właściwości działa identycznie w obu językach programowania. Jednak ze względu na różnice w działaniu każdego języka, użytkownicy ScriptForge muszą zdawać sobie sprawę z pewnych cech biblioteki podczas korzystania z Pythona:

- Nazwy metod i właściwości: w Pythonie wszystkie metody i właściwości mogą być używane w formacie pisanym małymi literami, ProperCased lub camelCased.

- Argumenty: wszystkie argumenty słów kluczowych przekazywane do metod są pisane małymi literami.

- Daty: wszystkie obiekty daty są przekazywane i zwracane jako datetime.datetime natywne obiekty Pythona.

- Tablice: jednowymiarowe tablice są przekazywane i zwracane jako krotki (co jest obiektem niezmiennym). Tablice dwuwymiarowe są przekazywane i zwracane jako krotki krotek.

- Brak: słowo kluczowe None w Pythonie jest odpowiednikiem słów Null, Empty lub Nothing w języku Basic.

- Obiekty UNO: wszystkie struktury UNO są wymieniane pomiędzy językiem Basic i Pythonem bez żadnych zmian.

- Debugowanie: za każdym razem, gdy w skryptach Pythona korzystających z ScriptForge wystąpi błąd, komunikat o błędzie dostarczony przez stos wykonawczy Pythona wyświetla linię kodu, która spowodowała błąd. W komunikatach o błędach Basic nie są wyświetlane te informacje.

Odwiedź Pomoc dotyczącą skryptów Pythona LibreOffice, aby uzyskać więcej informacji na temat skryptów Pythona przy użyciu LibreOffice.

## Edycja skryptów języka Python w środowiskach IDE

Wskazówki dotyczące pisania w języku Python — odnoszące się do publicznych metod i właściwości usług ScriptForge — można uzyskać z IDE obsługujących takie udogodnienia. Wizualnie, podczas edycji skryptu użytkownika:

- najechanie kursorem na instancję obiektu, metodę lub właściwość powoduje wyświetlenie jej szczegółowego opisu.

- znak „.” po instancji obiektu wyświetla rozwijane pole zawierające listę wszystkich dostępnych interfejsów.

- nawiasy kwadratowe po nazwie metody rozpoczynają dopełnianie kodu poprzez wyświetlenie jej argumentów.

Podpowiedzi dotyczące pisania są wyświetlane podczas edycji metod i właściwości z użyciem liter pisanych właściwą wielkością.

## Uruchamianie skryptów Pythona w LibreOffice

W zależności od tego, co chcesz osiągnąć, możesz wybrać jedno z następujących podejść do uruchamiania skryptów Pythona w LibreOffice:

- Uruchamianie skryptów w bieżącym procesie LibreOffice: skrypty Pythona są wykonywane w procesie LibreOffice za pomocą menu Narzędzia - Makra - Uruchom makro lub rozszerzenia APSO, aby wywołać skrypty użytkownika zapisane w folderze skryptów Pythona. Można również użyć powłoki Pythona APSO do interaktywnego uruchamiania skryptów Pythona.

- Uruchamianie skryptów niezależnie od procesu LibreOffice: skrypty Pythona są wykonywane z poziomu procesu zewnętrznego, który łączy się z trwającym procesem LibreOffice za pomocą pipe lub socket.

Jeśli planujesz uruchamiać skrypty z poziomu procesu LibreOffice, zaleca się zainstalowanie rozszerzenia APSO (Alternative Script Organizer for Python). Aby jednak tworzyć skrypty Pythona poza LibreOffice, możesz wybrać preferowane środowisko IDE dla Pythona.

### Uruchamianie skryptów z poziomu procesu LibreOffice

#### Korzystanie z rozszerzenia APSO

Najprostszym sposobem na rozpoczęcie pisania skryptów w Pythonie w LibreOffice jest zainstalowanie rozszerzenia APSO. Po jego zainstalowaniu otwórz dowolny komponent LibreOffice i przejdź do Narzędzia - Makra - Organizuj skrypty Pythona.

W głównym oknie APSO przejdź do Menu - Powłoka Pythona.

Ewentualnie możesz otworzyć APSO za pomocą domyślnego skrótu Alt + Shift + F11.

Teraz możesz zacząć wpisywać polecenia języka Python, a powłoka wypisze odpowiedni wynik po wykonaniu każdego wiersza kodu.

Aby rozpocząć korzystanie z biblioteki ScriptForge, należy zaimportować metodę CreateScriptService, dzięki której będzie można uzyskać dostęp do usług udostępnianych przez bibliotekę. Poniższy przykład wykorzystuje usługę Basic do wyświetlania okna komunikatu.

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

Aby uruchomić powyższy przykład, wpisz kolejno każdy wiersz kodu w powłoce Pythona i naciśnij klawisz Enter po wpisaniu każdego wiersza kodu.

Teraz możesz rozpocząć wykonywanie poleceń Pythona za pomocą dowolnej usługi ScriptForge. Na przykład poniższy fragment kodu wykorzystuje usługę UI do utworzenia pustego dokumentu Writer.

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

#### Tworzenie plików skryptów Pythona

Możesz tworzyć własne pliki Pythona i edytować je w preferowanym edytorze tekstu. Później możesz je wywołać z poziomu dowolnego komponentu LibreOffice.

Pierwszym krokiem jest ustalenie miejsca przechowywania skryptów użytkownika. Więcej informacji znajdziesz na stronie pomocy Organizacja i lokalizacja skryptów Pythona.

Teraz możesz utworzyć plik tekstowy w folderze skryptów użytkownika Pythona, na przykład my_script.py, i zacząć pisać swoje skrypty.

Oto prosty przykład, który pobiera wartość liczbową z komórki programu Calc i zwiększa ją o 1. Wystarczy wpisać poniższy kod do pliku my_script.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, )

Ten przykład tworzy funkcję increment_cell. Należy pamiętać, że g_exportedScripts to krotka wskazująca, które funkcje będą wyświetlane w LibreOffice jako skrypty użytkownika.

Aby uruchomić ten skrypt z poziomu dokumentu Calc:

1. Utwórz lub otwórz plik Calc.

2. Wpisz wartość liczbową do komórki „A1” w bieżącym arkuszu.

3. Przejdź do Narzędzia - Makra - Uruchom makra.

4. Wybierz Moje makra - my_script w selektorze bibliotek. Następnie wybierz funkcję increment_cell z listy Nazwa makra.

5. Kliknij Uruchom. Zauważ, że wartość w komórce „A1” została zwiększona o 1.

Możesz również użyć APSO do uruchomienia skryptów Pythona w podobny sposób:

1. Najpierw otwórz APSO, wybierając Narzędzia - Makra - Organizuj skrypty Pythona.

2. Na liście makr przejdź do Moje makra - my_script - increment_cell.

3. Kliknij Wykonaj.

### Uruchamianie skryptów oddzielnie od procesu LibreOffice

#### Określanie ścieżki instalacji

Pierwszym krokiem do uruchomienia skryptów z osobnego procesu jest znalezienie folderu, w którym zainstalowany jest LibreOffice. Można to zrobić na kilka sposobów, ale ScriptForge zapewnia szybki sposób na zidentyfikowanie ścieżki instalacji. W tym celu otwórz powłokę Pythona APSO i wpisz:

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

Wynik powyższego kodu to katalog bazowy, w którym zainstalowano LibreOffice. Teraz należy dodać podfolder „program” do wynikowej ścieżki. To jest folder bazowy, z którego będą uruchamiane skrypty Pythona z oddzielnego procesu.

Załóżmy na przykład, że po uruchomieniu powyższego kodu Pythona otrzymasz ścieżkę /usr/lib/libreoffice/. W takim przypadku ścieżkę /usr/lib/libreoffice/program należy traktować jako ścieżkę do uruchamiania skryptów Pythona.

#### Uruchom LibreOffice z ustawieniami pipe lub socket

Aby uruchamiać skrypty Pythona z poziomu osobnego procesu, należy uruchomić LibreOffice z kilkoma dodatkowymi opcjami określającymi nazwę potoku lub nazwę hosta i port, za pośrednictwem których proces zewnętrzny będzie komunikował się z procesem komponentu LibreOffice.

Otwórz wiersz poleceń swojego systemu operacyjnego, przejdź do folderu programu w katalogu instalacyjnym LibreOffice i wpisz:

W systemach Linux lub macOS:

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

W systemie Windows:

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

jako Flatpak:

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

Obie powyższe komendy uruchomią LibreOffice z otwartym kanałem komunikacyjnym, aby inne procesy mogły wymieniać z nim komunikaty.

Zwróć uwagę, że poprzedni przykład otwiera centrum startowe LibreOffice. Jeśli chcesz otworzyć konkretny komponent, na przykład Writer, możesz dodać flagę --writer do polecenia w następujący sposób.

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

Zwróć uwagę na parametry name lub host i port, którymi w tym przykładzie są odpowiednio aPipeName lub localhost i 2021.

#### Uruchamianie zewnętrznej powłoki Pythona

Uruchom powłokę Pythona z folderu program w ścieżce instalacji LibreOffice. Wykonaj kroki powyżej, aby dowiedzieć się, jak znaleźć ścieżkę instalacji.

W systemach Linux lub macOS:

$ cd /usr/lib/libreoffice/program

$ python

W systemie Windows:

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

$ python.exe

Spowoduje to otwarcie powłoki Pythona i będzie można zacząć wpisywać polecenia, które zostaną wykonane przez LibreOffice. Najpierw jednak musisz skonfigurować połączenie pipe lub socket. Poniższe polecenie ScriptForge() musi poprzedzać pierwsze wywołanie CreateScriptService().

Uruchom jedno z poniższych:

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

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

Przeczytaj sekcję Ustawianie PYTHONPATH poniżej w przypadku wystąpienia błędów podczas importowania scriptforge.py lub uno.py.

Druga linia kodu powyżej definiuje ustawienia pipe lub host i port, dzięki czemu powłoka Pythona może komunikować się z trwającym procesem LibreOffice otwartym przy użyciu tych samych ustawień potoku lub gniazda.

Teraz możesz uruchamiać inne polecenia Pythona, które będą mogły komunikować się z procesem LibreOffice. Na przykład:

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

#### Ustawianie PYTHONPATH

W zależności od konfiguracji systemu operacyjnego konieczne będzie ustawienie zmiennej środowiskowej PYTHONPATH w celu zaimportowania biblioteki scriptforge.py, co z kolei wymaga zaimportowania biblioteki uno.py.

Użyj narzędzia do wyszukiwania plików w swoim systemie operacyjnym, aby ustalić katalog, w którym znajdują się oba pliki.

Na przykład w domyślnej instalacji Ubuntu oba pliki mogą znajdować się w następującym miejscu:

- scriptforge.py: znajduje się w /usr/lib/libreoffice/program

- uno.py: znajduje się w /usr/lib/python3/dist-packages

W takim przypadku przed uruchomieniem interpretera Pythona należy ustawić zmienną środowiskową PYTHONPATH w następujący sposób:

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

Lokalizacja tych plików będzie się różnić w zależności od systemu operacyjnego i metody instalacji LibreOffice.

Tematy pokrewne

Biblioteka ScriptForge

Pomoc skryptów Pythona LibreOffice

Uruchamianie oprogramowania LibreOffice z parametrami

Prosimy o wsparcie!