Servizio ScriptForge.UI

Il servizio UI (Interfaccia utente) semplifica l'identificazione e la manipolazione delle diverse finestre che compongono l'intera applicazione LibreOffice:

tip

Il servizio UI è il punto di partenza per aprire, creare o accedere al contenuto di documenti, nuovi o esistenti, da uno script utente.


Definizioni

WindowName

Una finestra può essere indicata usando diversi modi:

Il nome della finestra distingue le lettere maiuscole e minuscole.

Oggetto Document

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.

tip

L'implementazione della classe di oggetti document si trova nella libreria associata SFDocuments. Vedere il suo servizio "Document".


Invocazione del servizio

Prima di usare il servizio UI è necessario caricare o importare le librerie ScriptForge:

note

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService


In Basic

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

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

Proprietà

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.

Documents

Sì

String array

L'elenco dei documenti attualmente aperti. Le finestre speciali sono ignorate. Questo elenco consiste in una matrice unidimensionale, con indice a partire da zero, dei nomi di file (nella notazione di SF_FileSystem.FileNaming) o dei titoli delle finestre per i documenti non ancora salvati.

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.

Costanti

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

Esempio:

Gli esempi seguenti mostrano una finestra di dialogo MsgBox con i nomi di tutti i documenti attualmente aperti.

In 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
In Python

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

Elenco dei metodi del servizio UI

Activate
CreateBaseDocument
CreateDocument (*)
GetDocument
Maximize

Minimize
OpenBaseDocument
OpenDocument (*)
Resize

RunCommand
SetStatusBar (*)
ShowProgressBar
WindowExists

warning

Notate che i metodi contrassegnati da (*) fanno eccezione e non sono applicabili ai documenti di Base.


Activate

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.

Sintassi:

svc.Activate(windowname: str): bool

Parametri:

windowname: vedete le definizioni precedenti.

Esempio:

In Basic

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

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

CreateBaseDocument

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.

Sintassi:

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

Parametri:

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.

Esempio:

In 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")
In 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 (*)

Crea un nuovo documento di LibreOffice del tipo specificato, basato sul modello indicato. Il metodo restituisce un oggetto documento.

Sintassi:

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

Parametri:

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.

Esempio:

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.

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

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

GetDocument

Restituisce un oggetto document aperto che fa riferimento alla finestra attiva, a una finestra indicata o al documento attivo.

Sintassi:

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

svc.GetDocument(windowname: uno): svc

Parametri:

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.

Esempio:

In Basic

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

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

Per accedere al nome della finestra attualmente attiva, fate riferimento alla proprietà ActiveWindow.


Maximize

Massimizza la finestra attiva o quella specificata.

Sintassi:

svc.Maximize(windowname: str)

Parametri:

windowname: vedete le definizioni riportate in precedenza. Se questo argomento è omesso, viene massimizzata la finestra attiva.

Esempio:

In Basic

      ui.Maximize("Untitled 1")
In Python

     ui.Maximize("Untitled 1")

Minimize

Minimizza la finestra attiva o la finestra indicata.

Sintassi:

svc.Minimize(windowname: str)

Parametri:

windowname: vedete le definizioni riportate in precedenza. Se l'argomento è assente, viene minimizzata la finestra attiva.

Esempio:

In Basic

     ui.Minimize()
In Python

     ui.Minimize()

OpenBaseDocument

Apre un documento LibreOffice Base esistente. Il metodo restituisce un oggetto documento.

Sintassi:

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

Parametri:

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.

Esempio:

In Basic

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

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

Per migliorare la leggibilità del codice è possibile usare delle costanti predefinite da passare all'argomento macroexecution, come nell'esempio precedente.


OpenDocument (*)

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.

Sintassi:

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

Parametri:

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.

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.

Esempio:

In Basic

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

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

Resize

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.

Sintassi:

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

Parametri:

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.

Esempio:

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.

In Basic

      ui.Resize(, ,500, 500)
In Python

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

Per ridimensionare una finestra non attiva, per prima cosa attivatela usando il metodo Activate.


RunCommand

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.

tip

Per un elenco completo dei comandi UNO che è possibile eseguire in LibreOffice, fare riferimento alla pagina del Wiki Development/DispatchCommands.


Sintassi:

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

Parametri:

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.

Esempio:

In Basic

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

In Python

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

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.


SetStatusbar (*)

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.

Sintassi:

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

Parametri:

text: un testo opzionale da visualizzare davanti alla barra di avanzamento.

percentage: il grado opzionale di avanzamento, compreso tra 0 e 100.

Esempio:

In Basic

      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      'Reimposta la barra di stato
      ui.SetStatusbar
In Python

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

ShowProgressBar

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.

Sintassi:

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

Parametri:

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.

Esempio:

In Basic

      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
In Python

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

WindowExists

Restituisce True se la finestra indicata non può essere identificata.

Sintassi:

svc.WindowExists(windowname: str): bool

Parametri:

windowname: vedete le definizioni precedenti.

Esempio:

In Basic

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

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

Argomenti correlati

Servizio ScriptForge.Basic

Servizio SFDocuments.Calc

Servizio SFDocuments.Document

Sosteneteci!