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

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

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

Właściwości

Stałe

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)
   

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.

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

CreateBaseDocument

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

CreateDocument (*)

Utwórz nowy dokument LibreOffice danego typu lub w oparciu o zadany szablon. Metoda zwraca obiekt dokumentu.

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

GetDocument

Zwraca otwarty obiekt dokumentu odnoszący się do aktywnego okna, danego okna lub 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.

Maximize

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

Minimize

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

OpenBaseDocument

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

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.

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

     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.

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.

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)
   

     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.

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

     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.

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 IDE Basic.

    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.

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

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.

svc.ShowProgressBar(title: str = '', text: str = '', percentage: str = -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()
   

WindowExists

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"):
         # ...