Spis treści

# Usługa ScriptForge.UI

Usługa UI (interfejs użytkownika) upraszcza identyfikację i manipulowanie różnymi oknami tworzącymi całą aplikację LibreOffice:

- Wybór okien

- Przenoszenie i zmiana rozmiaru okien

- Ustawienia paska stanu

- Wyświetlanie pływającego paska postępu

- Tworzenie nowych okien

- Dostęp do podstawowych „dokumentów”

Usługa UI jest punktem wyjścia do otwierania, tworzenia lub dostępu do treści nowych lub istniejących dokumentów za pomocą skryptu użytkownika.

## Definicje

### WindowName

Okno można wyznaczać na różne sposoby poprzez:

- pełną ścieżkę i nazwę pliku

- ostatni składnik pełnej nazwy pliku lub nawet tylko ostatni składnik bez jego przyrostka

- tytuł okna

- w przypadku nowych dokumentów coś w rodzaju „Bez tytułu 1”

- jedno ze specjalnych okien "BASICIDE" i "WELCOMESCREEN"

W nazwie okna rozróżniana jest wielkość liter.

### Obiekt dokumentu

Poniższe metody CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument i OpenDocument tworzą obiekty dokumentu. Jeśli okno zawiera dokument, jest on reprezentowany przez instancję klasy Document. Odwrotnym przypadkiem jest IDE Basic, które nie jest dokumentem, a jedynie oknem. Dokument ma również typ: Calc, Impress, Writer, ...

Konkretne właściwości i metody stosowane w dokumentach są zaimplementowane w klasie dokumentu.

Implementacja klasy obiektów dokumentów odbywa się w powiązanej bibliotece SFDocuments. Zobacz usługę "Document".

## Wywoływanie usługi

Przed użyciem usługi UI należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

##### W języku Basic

        Dim ui As Variant
        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Set ui = CreateScriptService("UI")

##### W języku Python

        from scriptforge import CreateScriptService
        ui = CreateScriptService("UI")

## Właściwości

Nazwa | Tylko do odczytu | Typ | Opis
--- | --- | --- | ---
ActiveWindow | Tak | String | Prawidłowa i unikalna nazwa WindowName dla aktualnie aktywnego okna. Jeśli nie można zidentyfikować okna, zwracany jest ciąg znaków o zerowej długości.
Height | Tak | Integer | Zwraca wysokość aktywnego okna w pikselach.
Width | Tak | Integer | Zwraca szerokość aktywnego okna w pikselach.
X | Tak | Integer | Zwraca współrzędną X aktywnego okna, czyli odległość do lewej krawędzi ekranu w pikselach.
Y | Tak | Integer | Zwraca współrzędną Y aktywnego okna, czyli odległość do górnej krawędzi ekranu w pikselach. Wartość ta nie uwzględnia dekoracji okien dodanych przez system operacyjny, więc nawet gdy okno jest zmaksymalizowane, wartość ta może nie wynosić zero.

## Stałe

Nazwa | Wartość | Opis
--- | --- | ---
MACROEXECALWAYS | 2 | Makra są zawsze wykonywane
MACROEXECNEVER | 1 | Makra nigdy nie są wykonywane
MACROEXECNORMAL | 0 | Wykonanie makra zależy od ustawień użytkownika

### Przykład:

Poniższe przykłady pokazują MsgBox z nazwami wszystkich aktualnie otwartych dokumentów.

##### W języku Basic

         Dim openDocs As Object, strDocs As String
         Set openDocs = ui.Documents()
         strDocs = openDocs(0)
         For i = 1 To UBound(openDocs)
             strDocs = strDocs & Chr(10) & openDocs(i)
         Next i
         MsgBox strDocs

##### W języku Python

         ui = CreateScriptService("UI")
         bas = CreateScriptService("Basic")
         openDocs = ui.Documents()
         strDocs = "\n".join(openDocs)
         bas.MsgBox(strDocs)

Lista metod w usłudze UI
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Metody, które nie mają zastosowania w dokumentach Base, są oznaczone jako wyjątki gwiazdką (*).

## Activate

Aktywuj określone okno. Metoda zwraca True jeśli dane okno zostało odnalezione i można je aktywować. Jeśli żadne okno nie pasuje do wybranego wyboru, nie nastąpi żadna zmiana w rzeczywistym interfejsie użytkownika.

### Składnia:

svc.Activate(windowname: str): bool

### Parametry:

windowname: zobacz definicje powyżej.

### Przykład:

##### W języku Basic

          ui.Activate("C:\Documents\My file.odt")

##### W języku Python

          ui.Activate(r"C:\Documents\My file.odt")

## CreateBaseDocument

Tworzy i przechowuje nowy dokument LibreOffice Base osadzający pustą bazę danych danego typu. Metoda zwraca instancję usługi Document.

### Składnia:

svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc

### Parametry:

filename: identyfikuje plik do utworzenia. Musi być zgodny z notacją SF_FileSystem.FileNaming. Jeśli plik już istnieje, zostanie nadpisany bez ostrzeżenia.

embeddeddatabase: "HSQLDB" (domyślnie), "FIREBIRD" lub "CALC".

registrationname: nazwa używana do przechowywania nowej bazy danych w rejestrze baz danych. Kiedy = "" (domyślnie), rejestracja nie jest przeprowadzana. Jeśli nazwa już istnieje, zostanie nadpisana bez ostrzeżenia.

calcfilename: tylko wtedy, gdy embeddeddatabase = "CALC", calcfilename reprezentuje plik zawierający tabele w postaci arkuszy Calc. Plik musi istnieć. W przeciwnym razie zostanie zgłoszony błąd.

### Przykład:

##### W języku Basic

          Dim myBase As Object, myCalcBase As Object
          Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
          Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", _
              "CALC", , "C:\Databases\MyCalcFile.ods")

##### W języku Python

         myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
         myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
             "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")

## CreateDocument (*)

Utwórz nowy dokument LibreOffice danego typu lub w oparciu o zadany szablon. Metoda zwraca instancję klasy dokumentu lub jednej z jej podklas (Calc, Writer).

### Składnia:

svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc

### Parametry:

documenttype: "Calc", "Writer", itd. Jeśli nie ma, musi być obecny argument templatefile.

templatefile: pełna FileName szablonu, na którym ma zostać utworzony nowy dokument. Jeśli plik nie istnieje, argument jest ignorowany. Usługa FileSystem udostępnia właściwości TemplatesFolder i UserTemplatesFolder, które pomagają w budowaniu argumentu.

hidden: jeśli True, otwórz nowy dokument w tle (domyślnie = False). Aby zachować ostrożność: późniejsza aktywacja lub zamknięcie może nastąpić tylko programowo.

### Przykład:

W obu poniższych przykładach pierwsze wywołanie metody CreateDocument tworzy pusty dokument Calc, natomiast drugie tworzy dokument na podstawie pliku szablonu.

##### W języku Basic

          Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
          Set myDoc1 = ui.CreateDocument("Calc")
          Set FSO = CreateScriptService("FileSystem")
          Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

##### W języku Python

         myDoc1 = ui.CreateDocument("Calc")
         fs = CreateScriptService("FileSystem")
         myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))

## Documents

Lista aktualnie otwartych dokumentów. Okna specjalne są ignorowane. Lista ta składa się z jednowymiarowej tablicy od zera zawierającej nazwy plików — przy użyciu notacji ScriptForge.FileSystem.FileNaming — lub okna tytuły niezapisanych dokumentów.

### Składnia:

svc.Documents(): str[1..*]

### Przykład:

W obu poniższych przykładach metoda może zwrócić pustą tablicę, jeśli nie ma otwartych żadnych dokumentów.

##### W języku Basic

          Dim docList As Variant
          docList = ui.Documents

##### W języku Python

         docList = ui.Documents()

## GetDocument

Zwraca instancję klasy Document lub jednej z jej podklas (Calc, Writer, Base, FormDocument) odnoszącej się albo do danego okna, albo do aktywnego dokumentu.

### Składnia:

svc.GetDocument(windowname: str = ''): svc

svc.GetDocument(windowname: uno): svc

### Parametry:

windowname: zobacz definicje wyżej wymienione. W przypadku braku tego argumentu używane jest aktywne okno. Akceptowane są także obiekty UNO typu com.sun.star.lang.XComponent lub com.sun.star.comp.dba.ODatabaseDocument. Zatem przekazanie ThisComponent lub ThisDatabaseDocument jako argumentu tworzy nową usługę SFDocuments.Document, Base lub Calc.

### Przykład:

##### W języku Basic

          Dim myDoc As Object
          Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
          Set myBase = ui.GetDocument(ThisDatabaseDocument)

##### W języku Python

         from scriptforge import CreateScriptService
         bas = CreateScriptService("Basic")
         myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
         myDoc = ui.GetDocument(bas.ThisComponent)

Aby uzyskać dostęp do nazwy aktualnie aktywnego okna, zapoznaj się z właściwością ActiveWindow.

## Maximize

Maksymalizuje aktywne okno lub dane okno.

### Składnia:

svc.Maximize(windowname: str)

### Parametry:

windowname: zobacz definicje wyżej wymienione. W przypadku braku tego argumentu aktywne okno jest maksymalizowane.

### Przykład:

##### W języku Basic

          ui.Maximize("Untitled 1")

##### W języku Python

         ui.Maximize("Untitled 1")

## Minimize

Minimalizuje aktywne okno lub podane okno.

### Składnia:

svc.Minimize(windowname: str)

### Parametry:

windowname: zobacz definicje wyżej wymienione. W przypadku braku tego argumentu aktywne okno jest minimalizowane.

### Przykład:

##### W języku Basic

         ui.Minimize()

##### W języku Python

         ui.Minimize()

## OpenBaseDocument

Otwórz istniejący dokument LibreOffice Base. Metoda zwraca obiekt Base.

### Składnia:

svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc

### Parametry:

filename: identyfikuje plik do otwarcia. Musi podążać za notacją SF_FileSystem.FileNaming.

registrationname: nazwa używana do wyszukiwania bazy danych w rejestrze baz danych. Argument ten jest ignorowany, jeśli FileName <> "".

macroexecution: 0 = zachowanie jest zdefiniowane przez konfigurację użytkownika, 1 = makra nie są wykonywalne, 2 = makra są wykonywalne. Wartość domyślna to 0.

### Przykład:

##### W języku Basic

          Dim myBase As Object
          Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)

##### W języku Python

         myBase = ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)

Aby poprawić czytelność kodu, możesz użyć wstępnie zdefiniowanych stałych dla argumentu macroexecution, jak w powyższych przykładach.

## OpenDocument (*)

Otwiera istniejący dokument LibreOffice z podanymi opcjami. Zwraca obiekt dokumentu lub jedną z jego podklas. Metoda zwraca Nothing (w BASIC) lub None (w Pythonie), jeśli otwarcie nie powiodło się, nawet jeżeli niepowodzenie jest spowodowane decyzją użytkownika.

### Składnia:

svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc

### Parametry:

filename: identyfikuje plik do otwarcia. Musi być zgodny z notacją FileNaming usługi FileSystem.

password: do użycia, gdy dokument jest chroniony. Jeśli jest nieprawidłowy lub nie ma go, gdy dokument jest chroniony, użytkownik zostanie poproszony o podanie hasła.

readonly: domyślnie = False.

hidden: jeśli True, otwórz nowy dokument w tle (domyślnie = False). Aby zachować ostrożność: późniejsza aktywacja lub zamknięcie może nastąpić tylko programowo.

macroexecution: 0 = zachowanie jest zdefiniowane przez konfigurację użytkownika, 1 = makra nie są wykonywalne, 2 = makra są wykonywalne. Wartość domyślna to 0.

filtername: nazwa filtra, który ma zostać użyty przy ładowaniu dokumentu. Jeśli jest obecny, filtr musi istnieć.

filteroptions: opcjonalny ciąg opcji skojarzony z filtrem.

### Przykład:

##### W języku Basic

          Dim myDoc As Object, FSO As Object
          Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)

##### W języku Python

         myDoc = ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)

## Resize

Zmienia rozmiar i/lub przesuwa aktywne okno. Brakujące i negatywne argumenty są ignorowane. Jeśli okno jest zminimalizowane lub zmaksymalizowane, wywołanie funkcji Resize bez argumentów przywraca je.

### Składnia:

svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)

### Parametry:

left, top: odległość lewego górnego rogu od górnej i lewej krawędzi ekranu (w pikselach).

width, height: nowe wymiary okna w pikselach.

### Przykład:

W poniższych przykładach width i height okna zostały zmienione, natomiast top i left pozostały niezmienione.

##### W języku Basic

          ui.Resize(Width := 500, Height := 500)

##### W języku Python

         ui.Resize(width = 500, height = 500)

Aby zmienić rozmiar nieaktywnego okna, najpierw aktywuj je metodą Activate.

## RunCommand

Uruchamia polecenie UNO w bieżącym oknie. Kilka typowych poleceń to: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, itp.

Polecenia można uruchamiać z argumentami lub bez nich. Argumenty nie są sprawdzane przed uruchomieniem polecenia. Jeśli polecenie lub jego argumenty są nieprawidłowe, nic się nie stanie.

Pełną listę poleceń UNO, które można uruchomić w LibreOffice, można znaleźć na stronie Wiki Development/DispatchCommands.

### Składnia:

svc.RunCommand(command: str, [args: any])

### Parametry:

command: ciąg znaków zawierający nazwę polecenia UNO, w którym rozróżniana jest wielkość liter. Dodanie przedrostka ".uno:" do polecenia jest opcjonalne. Samo polecenie nie jest sprawdzane pod kątem poprawności. Jeśli po wywołaniu polecenia nic się nie dzieje, prawdopodobnie polecenie jest nieprawidłowe.

args: dla każdego argumentu, który ma być przekazany do polecenia, określ parę zawierającą nazwę i wartość argumentu.

### Przykład:

##### W języku Basic

Poniższy przykład uruchamia polecenie .uno:About w bieżącym oknie.

        Set ui = CreateScriptService("UI")
        ui.RunCommand("About")

Poniżej znajduje się przykład, który uruchamia polecenie UNO .uno:BasicIDEAppear i przekazuje argumenty wymagane do otwarcia IDE Basic w określonej linii modułu.

        ' Argumenty przekazywane do polecenia:
        ' Document  = "LibreOffice Macros & Dialogs"
        ' LibName = "ScriptForge"
        ' Name = "SF_Session"
        ' Line = 600
        ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", _
                      "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

Pamiętaj, że wywołanie polecenia BasicIDEAppear bez argumentów spowoduje po prostu otwarcie IDE Basic.

##### W języku Python

        ui = CreateScriptService("UI")
        ui.RunCommand("About")

        ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", \
                      "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)

W języku Python możliwe jest także wywołanie RunCommand przy użyciu argumentów słów kluczowych:

        ui.RunCommand(".uno:BasicIDEAppear", Document = "LibreOffice Macros & Dialogs", \
                      LibName = "ScriptForge", Name = "SF_Session", Line = 600)

Każdy komponent LibreOffice ma dostępny własny zestaw poleceń. Jednym z łatwych sposobów nauki poleceń jest przejście do Narzędzia - Dostosuj - Klawiatura. Kiedy najedziesz myszką na funkcję na liście Function, pojawi się podpowiedź z odpowiednim poleceniem UNO.

## SetStatusbar (*)

Wyświetl tekst i pasek postępu na pasku stanu aktywnego okna. Wszelkie kolejne wywołania w tym samym uruchomieniu makra odnoszą się do tego samego paska stanu tego samego okna, nawet jeśli okno nie jest już widoczne. Wywołanie bez argumentów resetuje pasek stanu do normalnego stanu.

### Składnia:

svc.SetStatusbar(text: str = '', percentage: int = -1)

### Parametry:

text: opcjonalny tekst wyświetlany przed paskiem postępu.

percentage: opcjonalny stopień postępu od 0 do 100.

### Przykład:

##### W języku Basic

          Dim i As Integer
          For i = 0 To 100
              ui.SetStatusbar("Progress ...", i)
              Wait 50
          Next i
          ' Resetuje pasek stanu
          ui.SetStatusbar

##### W języku Python

         from time import sleep
         for i in range(101):
             ui.SetStatusbar("Test:", i)
             sleep(0.05)
         ui.SetStatusbar()

## ShowProgressBar

Wyświetla niemodalne okno dialogowe. Określ jego tytuł, tekst objaśniający i procent postępu, który będzie reprezentowany na pasku postępu. Okno dialogowe pozostanie widoczne do momentu wywołania metody bez argumentów lub do momentu ręcznego zamknięcia okna dialogowego przez użytkownika.

### Składnia:

svc.ShowProgressBar(title: str = '', text: str = '', percentage: int = -1)

### Parametry:

title: tytuł pojawiający się w górnej części okna dialogowego. Domyślnie = "ScriptForge".

text: opcjonalny tekst wyświetlany nad paskiem postępu.

percentage: opcjonalny stopień postępu od 0 do 100.

### Przykład:

##### W języku Basic

          Dim i As Integer
          For i = 0 To 100
              ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
              Wait 50
          Next i
          ' Zamyka okno paska postępu
          ui.ShowProgressBar

##### W języku Python

         from time import sleep
         for i in range(101):
             ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
             sleep(0.05)
         # Zamyka okno paska postępu
         ui.ShowProgressBar()

## WindowExists

Zwraca wartość True, jeśli można było zidentyfikować dane okno.

### Składnia:

svc.WindowExists(windowname: str): bool

### Parametry:

windowname: zobacz definicje powyżej.

### Przykład:

##### W języku Basic

          If ui.WindowExists("C:\Document\My file.odt") Then
              ' ...

##### W języku Python

         if ui.WindowExists(r"C:\Document\My file.odt"):
             # ...

Tematy pokrewne

Usługa ScriptForge.Basic

Usługa SFDocuments.Calc

Usługa SFDocuments.Document