Contenuto

# Servizio ScriptForge.UI

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.

## Definizioni

### WindowName

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.

### 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.

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:

• 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

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)

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)

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)

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.

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)

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