Guida di LibreOffice 25.2
Il servizio UI (Interfaccia utente) semplifica l'identificazione e la manipolazione delle diverse finestre che compongono l'intera applicazione LibreOffice:
Selezione delle finestre
Spostamento e ridimensionamento delle finestre
Impostazioni della barra di stato
Visualizzazione di una barra di avanzamento mobile
Creazione di nuove finestre
Accesso ai "documenti" sottostanti
Il servizio UI è il punto di partenza per aprire, creare o accedere al contenuto di documenti, nuovi o esistenti, da uno script utente.
Una finestra può essere indicata usando diversi modi:
un percorso completo e il nome del file
l'ultimo componente del nome completo del file o anche solo l'ultimo componente senza il suo suffisso
il titolo della finestra
per i nuovi documenti, qualcosa tipo "Senza nome 1"
una delle finestre speciali "BASICIDE" e "WELCOMESCREEN"
Il nome della finestra distingue le lettere maiuscole e minuscole.
I metodi CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument e OpenDocument, descritti di seguito, generano oggetti documento. Quando una finestra contiene un documento, un'istanza della classe Document rappresenta quel documento. Come esempio contrario, nella nostra terminologia, la IDE Basic non è un documento ma una finestra. Inoltre un documento possiede un tipo: Calc, Impress, Writer, ...
Le proprietà e i metodi specifici applicabili ai documenti sono implementati in una classe document.
L'implementazione della classe di oggetti document si trova nella libreria associata SFDocuments. Vedere il suo servizio "Document".
Prima di usare il servizio UI è necessario caricare o importare le librerie ScriptForge:
    Dim ui As Variant
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Set ui = CreateScriptService("UI")
  
    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
  | Nome | Sola lettura | Tipo | Descrizione | 
|---|---|---|---|
| ActiveWindow | Sì | String | un WindowName valido e univoco per la finestra correntemente attiva. Quando la finestra non può essere identificata, viene restituita una stringa di lunghezza zero. | 
| Height | Sì | Integer | Restituisce l'altezza in pixel della finestra attiva. | 
| Width | Sì | Integer | Restituisce la larghezza in pixel della finestra attiva. | 
| X | Sì | Integer | Restituisce la coordinata X della finestra attiva, che è la distanza in pixel dal bordo sinistro dello schermo. | 
| Y | Sì | Integer | Restituisce la coordinata Y della finestra attiva, che è la distanza in pixel dal bordo superiore dello schermo. Questo valore non prende in considerazione le decorazioni aggiunte dal sistema operativo, perciò, anche quando la finestra è massimizzata, questo valore potrebbe non essere zero. | 
| Nome | Valore | Descrizione | 
|---|---|---|
| MACROEXECALWAYS | 2 | Le macro vengono sempre eseguite | 
| MACROEXECNEVER | 1 | Le macro non vengono mai eseguite | 
| MACROEXECNORMAL | 0 | L'esecuzione delle macro dipende dalle impostazioni utente | 
Gli esempi seguenti mostrano una finestra di dialogo MsgBox con i nomi di tutti i documenti attualmente aperti.
     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)
   | Elenco dei metodi del servizio UI | ||
|---|---|---|
| 
           Activate | ||
Notate che i metodi contrassegnati da (*) fanno eccezione e non sono applicabili ai documenti di Base.
Rende attiva la finestra specificata. Il metodo restituisce True se la finestra indicata viene trovata e può essere resa attiva. Se nessuna finestra corrisponde a quella selezionata, non si verifica alcuna modifica all'interfaccia utente.
svc.Activate(windowname: str): bool
windowname: vedete le definizioni precedenti.
      ui.Activate("C:\Documents\My file.odt")
    
      ui.Activate(r"C:\Documents\My file.odt")
    Crea e memorizza un nuovo documento di LibreOffice Base che incorpora un database vuoto del tipo indicato. Il metodo restituisce un'istanza del servizio Document.
svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc
filename: identifica il file da creare. Deve seguire la notazione di SF_FileSystem.FileNaming. Se esiste già, viene sovrascritto senza alcun avvertimento.
embeddeddatabase: "HSQLDB" (predefinito), "FIREBIRD" o "CALC".
registrationname: il nome usato per memorizzare il nuovo database nel registro dei database. Quando = "" (predefinito), non viene effettuata alcuna registrazione. Se il nome esiste già viene sovrascritto senza alcun avviso.
calcfilename : solamente se embeddeddatabase = "CALC", calcfilename rappresenta il file che contiene le tabelle nei fogli di Calc. Il file deve esistere, altrimenti si genera un errore.
      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")
   Crea un nuovo documento di LibreOffice del tipo specificato o sulla base del modello indicato. Il metodo restituisce un'istanza della classe di documento o una delle sue sottoclassi (Calc, Writer).
svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc
documenttype : "Calc", "Writer", ecc. Quando è assente, l'argomento templatefile deve essere presente.
templatefile: il FileName completo del modello in base al quale creare il nuovo documento. Se il file non esiste, l'argomento viene ignorato. Il servizio FileSystem fornisce le proprietà TemplatesFolder e UserTemplatesFolder che aiutano nella costruzione dell'argomento.
hidden: se è True, apre il nuovo documento in background (predefinito = False). Da usare con cautela: in seguito l'attivazione o la chiusura può avvenire solo tramite programmazione.
In entrambi gli esempi seguenti, la prima chiamata al metodo CreateDocument crea un documento di Calc vuoto, mentre la seconda crea un documento dal file di un modello.
      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"))
   L'elenco dei documenti attualmente aperti. Le finestre speciali sono ignorate. L'elenco è costituito da una matrice unidimensionale contenente o i nomi dei file - usando la notazione ScriptForge.FileSystem.FileNaming - o i titoli delle finestre per i documenti non ancora salvati.
svc.Documents(): str[1..*]
In entrambi gli esempi seguenti il metodo può restituire una matrice vuota, se non ci sono documenti aperti.
      Dim docList As Variant
      docList = ui.Documents
   
     docList = ui.Documents()
   Restituisce un'istanza della classe Document o di una delle sue sottoclassi (Calc, Writer, Base, FormDocument) che fa riferimento alla finestra specificata o al documento attivo.
svc.GetDocument(windowname: str = ''): svc
svc.GetDocument(windowname: uno): svc
windowname: vedete le definizioni sopra riportate. Se questo argomento è assente, viene usata la finestra attiva. Sono accettati anche gli oggetti UNO del tipo com.sun.star.lang.XComponent o com.sun.star.comp.dba.ODatabaseDocument. Perciò, passando come argomento ThisComponent o ThisDatabaseDocument si crea un nuovo servizioSFDocuments.Document, Base o 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)
   Per accedere al nome della finestra attualmente attiva, fate riferimento alla proprietà ActiveWindow.
Massimizza la finestra attiva o quella specificata.
svc.Maximize(windowname: str)
windowname: vedete le definizioni riportate in precedenza. Se questo argomento è omesso, viene massimizzata la finestra attiva.
      ui.Maximize("Untitled 1")
   
     ui.Maximize("Untitled 1")
   Minimizza la finestra attiva o la finestra indicata.
svc.Minimize(windowname: str)
windowname: vedete le definizioni riportate in precedenza. Se l'argomento è assente, viene minimizzata la finestra attiva.
     ui.Minimize()
   
     ui.Minimize()
   Apre un documento esistente di LibreOffice Base. Il metodo restituisce un oggetto Base.
svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc
filename: identifica il file da aprire. Deve rispettare la notazione SF_FileSystem.FileNaming.
registrationname: il nome da usare per trovare il database nel registro dei database. Viene ignorato se FileName <> "".
macroexecution: 0 = il comportamento è definito dalla configurazione dell'utente, 1 = le macro non sono eseguibili, 2 = le macro sono eseguibili. Il valore predefinito è 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)
   Per migliorare la leggibilità del codice è possibile usare delle costanti predefinite da passare all'argomento macroexecution, come nell'esempio precedente.
Apre un documento LibreOffice esistente usando le opzioni specificate. Restituisce un oggetto documento o una delle sue sottoclassi. Il metodo restituisce Nothing (in BASIC) o None (in Python) se l'apertura non riesce, anche se l'errore è causato da una decisione dell'utente.
svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc
filename: identifica il file da aprire. Deve rispettare la notazione FileNaming del servizio FileSystem.
password: da usare quando il documento è protetto. Se è sbagliata o assente e il documento è protetto, all'utente sarà richiesto di inserire una password.
readonly: predefinito = False.
hidden: se è True, apre il nuovo documento in background (predefinito = False). Da usare con cautela: in seguito l'attivazione o la chiusura può avvenire solo tramite programmazione.
macroexecution: 0 = il comportamento è definito dalla configurazione dell'utente, 1 = le macro non sono eseguibili, 2 = le macro sono eseguibili. Il valore predefinito è 0.
filtername: il nome del filtro che dovrebbe essere usato per caricare il documento. Quando presente, il filtro deve esistere.
filteroptions: una stringa facoltativa contenente le opzioni associate al filtro.
      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)
   Ridimensiona e/o sposta la finestra attiva. Gli argomenti assenti o negativi vengono ignorati. Se la finestra è minimizzata o massimizzata, la chiamata di Resize senza argomenti la ripristina.
svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)
left, top: le distanze dell'angolo superiore sinistro dai margini superiore e sinistro dello schermo, espresse in pixel.
width, height: le nuove dimensioni della finestra, in pixel.
Negli esempi seguenti, la larghezza (width) e l'altezza (height) della finestra vengono modificate mentre la parte superiore (top) e la sinistra (left) restano invariate.
      ui.Resize(Width := 500, Height := 500)
   
     ui.Resize(width = 500, height = 500)
   Per ridimensionare una finestra non attiva, per prima cosa attivatela usando il metodo Activate.
Esegue un comando UNO nella finestra corrente. Alcuni comandi tipici sono: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, ecc.
È possibile eseguire i comandi con o senza argomenti. Gli argomenti non vengono validati prima dell'esecuzione del comando. Se il comando o i suoi argomenti non sono validi, non accadrà nulla.
Per un elenco completo dei comandi UNO che è possibile eseguire in LibreOffice, fare riferimento alla pagina del Wiki Development/DispatchCommands.
svc.RunCommand(command: str, [args: any])
command: stringa con distinzione tra lettere minuscole e maiuscole contenente il comando UNO. L'inclusione del prefisso ".uno" è facoltativa. La correttezza del comando non viene verificata. Se non succede nulla dopo la sua chiamata, probabilmente il comando è sbagliato.
args: per ciascun argomento da passare al comando, specificare una coppia contenente il nome dell'argomento e il valore.
L'esempio seguente esegue il comando .uno:About nella finestra corrente.
    Set ui = CreateScriptService("UI")
    ui.RunCommand("About")
  Di seguito un esempio che esegue il comando UNO .uno:BasicIDEAppear e passa gli argomenti richiesti per aprire l'IDE di Basic alla linea specificata di un modulo.
    ' Argomenti passati al comando:
    ' 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)
  Fare attenzione che chiamando il comando BasicIDEAppear senza argomenti si aprirà semplicemente la .
    ui = CreateScriptService("UI")
    ui.RunCommand("About")
  
    ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", \
                  "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)
  In Python è anche possibile chiamare RunCommand usando gli argomenti con parole chiave:
    ui.RunCommand(".uno:BasicIDEAppear", Document = "LibreOffice Macros & Dialogs", \
                  LibName = "ScriptForge", Name = "SF_Session", Line = 600)
  Ogni componente di LibreOffice dispone di un proprio insieme di comandi. Un modo semplice per impararli è quello di accedere a Strumenti - Personalizza - Tastiera. Quando si posiziona il puntatore del mouse sopra una funzione nell'elenco Funzioni comparirà un suggerimento col comando UNO corrispondente.
Visualizza un testo e una barra di avanzamento nella barra di stato della finestra attiva. Ogni successiva chiamata nella stessa esecuzione della macro fa riferimento alla stessa barra di stato della stessa finestra, anche se la finestra non è più visibile. Una chiamata senza argomenti reimposta la barra di stato alla sua condizione normale.
svc.SetStatusbar(text: str = '', percentage: int = -1)
text: un testo opzionale da visualizzare davanti alla barra di avanzamento.
percentage: il grado opzionale di avanzamento, compreso tra 0 e 100.
      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      'Reimposta la barra di stato
      ui.SetStatusbar
   
     from time import sleep
     for i in range(101):
         ui.SetStatusbar("Test:", i)
         sleep(0.05)
     ui.SetStatusbar()
   Visualizza una finestra di dialogo non modale. Specifica il titolo, un testo esplicativo e una percentuale di progresso rappresentata su una barra di avanzamento. La finestra di dialogo rimarrà visibile fino a una chiamata del metodo senza argomenti, o fino a quando l'utente non la chiuderà manualmente.
svc.ShowProgressBar(title: str = '', text: str = '', percentage: int = -1)
title : il titolo che appare in alto nella finestra di dialogo. Predefinito = "ScriptForge".
text: un testo opzionale da visualizzare sopra la barra di avanzamento.
percentage: il grado opzionale di avanzamento, compreso tra 0 e 100.
      Dim i As Integer
      For i = 0 To 100
          ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
          Wait 50
      Next i
      'Chiude la finestra della Barra di avanzamento
      ui.ShowProgressBar
   
     from time import sleep
     for i in range(101):
         ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
         sleep(0.05)
     #Chiude la finestra della Barra di avanzamento
     ui.ShowProgressBar()
   Restituisce True se la finestra indicata non può essere identificata.
svc.WindowExists(windowname: str): bool
windowname: vedete le definizioni precedenti.
      If ui.WindowExists("C:\Document\My file.odt") Then
          ' ...
   
     if ui.WindowExists(r"C:\Document\My file.odt"):
         # ...