Pomoc LibreOffice 24.8
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.
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.
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".
Przed użyciem usługi UI należy załadować lub zaimportować bibliotekę ScriptForge:
    Dim ui As Variant
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Set ui = CreateScriptService("UI")
  
    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
  | 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. | 
| 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 | 
Poniższe przykłady pokazują MsgBox z nazwami wszystkich aktualnie otwartych dokumentów.
     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
   
     ui = CreateScriptService("UI")
     bas = CreateScriptService("Basic")
     openDocs = ui.Documents()
     strDocs = "\n".join(openDocs)
     bas.MsgBox(strDocs)
   | Lista metod w usłudze UI | ||
|---|---|---|
| 
           Activate | ||
Metody, które nie mają zastosowania w dokumentach Base, są oznaczone jako wyjątki gwiazdką (*).
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.
svc.Activate(windowname: str): bool
windowname: zobacz definicje powyżej.
      ui.Activate("C:\Documents\My file.odt")
    
      ui.Activate(r"C:\Documents\My file.odt")
    Tworzy i przechowuje nowy dokument LibreOffice Base osadzający pustą bazę danych danego typu. Metoda zwraca instancję usługi Document.
svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc
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.
      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")
   
     myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
     myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
         "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")
   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).
svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc
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.
W obu poniższych przykładach pierwsze wywołanie metody CreateDocument tworzy pusty dokument Calc, natomiast drugie tworzy dokument na podstawie pliku szablonu.
      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"))
   
     myDoc1 = ui.CreateDocument("Calc")
     fs = CreateScriptService("FileSystem")
     myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))
   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.
svc.Documents(): str[1..*]
W obu poniższych przykładach metoda może zwrócić pustą tablicę, jeśli nie ma otwartych żadnych dokumentów.
      Dim docList As Variant
      docList = ui.Documents
   
     docList = ui.Documents()
   Zwraca instancję klasy Document lub jednej z jej podklas (Calc, Writer, Base, FormDocument) odnoszącej się albo do danego okna, albo do aktywnego dokumentu.
svc.GetDocument(windowname: str = ''): svc
svc.GetDocument(windowname: uno): svc
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.
      Dim myDoc As Object
      Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
      Set myBase = ui.GetDocument(ThisDatabaseDocument)
   
     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.
Maksymalizuje aktywne okno lub dane okno.
svc.Maximize(windowname: str)
windowname: zobacz definicje wyżej wymienione. W przypadku braku tego argumentu aktywne okno jest maksymalizowane.
      ui.Maximize("Untitled 1")
   
     ui.Maximize("Untitled 1")
   Minimalizuje aktywne okno lub podane okno.
svc.Minimize(windowname: str)
windowname: zobacz definicje wyżej wymienione. W przypadku braku tego argumentu aktywne okno jest minimalizowane.
     ui.Minimize()
   
     ui.Minimize()
   Otwórz istniejący dokument LibreOffice Base. Metoda zwraca obiekt Base.
svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc
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.
      Dim myBase As Object
      Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)
   
     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.
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.
svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc
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.
      Dim myDoc As Object, FSO As Object
      Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)
   
     myDoc = ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)
   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.
svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)
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.
W poniższych przykładach width i height okna zostały zmienione, natomiast top i left pozostały niezmienione.
      ui.Resize(Width := 500, Height := 500)
   
     ui.Resize(width = 500, height = 500)
   Aby zmienić rozmiar nieaktywnego okna, najpierw aktywuj je metodą Activate.
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.
svc.RunCommand(command: str, [args: any])
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.
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 .
    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.
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.
svc.SetStatusbar(text: str = '', percentage: int = -1)
text: opcjonalny tekst wyświetlany przed paskiem postępu.
percentage: opcjonalny stopień postępu od 0 do 100.
      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      ' Resetuje pasek stanu
      ui.SetStatusbar
   
     from time import sleep
     for i in range(101):
         ui.SetStatusbar("Test:", i)
         sleep(0.05)
     ui.SetStatusbar()
   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.
svc.ShowProgressBar(title: str = '', text: str = '', percentage: int = -1)
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.
      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
   
     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()
   Zwraca wartość True, jeśli można było zidentyfikować dane okno.
svc.WindowExists(windowname: str): bool
windowname: zobacz definicje powyżej.
      If ui.WindowExists("C:\Document\My file.odt") Then
          ' ...
   
     if ui.WindowExists(r"C:\Document\My file.odt"):
         # ...