Contenuto
Indice 🔎︎

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

## Invocare il servizio

##### In Basic

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

##### In Python

        from scriptforge import CreateScriptService
        svcUI = 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.

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

         svcUI = CreateScriptService("UI")
         sBasic = CreateScriptService("Basic")
         openDocs = svcUI.Documents()
         strDocs = "\n".join(openDocs)
         sBasic.MsgBox(strDocs)

Elenco dei metodi del servizio UI
Activate CreateBaseDocument CreateDocument (*) GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) | Resize 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

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

## CreateBaseDocument

Crea e memorizza un nuovo documento di LibreOffice Base incorporando un database vuoto del tipo indicato. Il metodo restituisce un'istanza del servizio Document.

### Sintassi:

svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: 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: uno tra "HSQLDB" (predefinito) o "FIREBIRD".

registrationname: il nome usato per memorizzare il nuovo database nel registro dei database. Quando = "" (predefinito), non viene effettuata alcuna registrrazione. Se il nome esiste già viene sovrascritto senza alcun avvertimento.

### Esempio:

##### In Basic

          Dim myBase As Object
          Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")

##### In Python

         myBase = svcUI.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")

## 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 = svcUI.CreateDocument("Calc")
         FSO = CreateScriptService("FileSystem")
         myDoc2 = svcUI.CreateDocument(templatefile = FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

## GetDocument

Restituisce un oggetto documento che fa riferimento o alla finestra attiva o a quella specificata.

### Sintassi:

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

### Parametri:

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

### Esempio:

##### In Basic

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

##### In Python

         myDoc = svcUI.GetDocument(r"C:\Documents\My file.odt")

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

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

         svcUI.Minimize()

## OpenBaseDocument

Apre un documento esistente di LibreOffice Base. 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. Se il file esiste già, viene sovrascritto senza alcun avvertimento

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

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

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

## OpenDocument (*)

Apre un documento esistente di LibreOffice usando le opzioni specificate. Restituisce un oggetto documento o una delle sue sottoclassi. Il metodo restituisce Nothing (in Basic) / None (in Python) se l'apertura fallisce, anche nel caso in cui il fallimento è dovuto a 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 ed 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

         svcUI.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: Distances of the top-left corner from top and left edges of the screen, in pixels.

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 alto (top) e sinistra (left) sono lasciati immodificati.

##### In Basic

          ui.Resize(, ,500, 500)

##### In Python

         svcUI.Resize(width = 500, height = 500)

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

## SetStatusbar (*)

Visualizza un testo e una barra di avanzamento nella barra di stato della finestra attiva. Ogni successiva chiamata all'interno della 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):
             svcUI.SetStatusbar("Test:", i)
             sleep(0.05)
         svcUI.SetStatusbar()

## ShowProgressBar

Visualizza una finestra di dialogo non modale. Specifica il titolo, un testo esplicativo ed una percentuale di progresso rappresentata su di una barra di avanzamento. La finestra di dialogo rimarrà visibile fino ad 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):
             svcUI.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
             sleep(0.05)
         #Chiude la finestra della Barra di avanzamento
         svcUI.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 svcUI.WindowExists(r"C:\Document\My file.odt"):
             # ...

Argomenti correlati

Servizio SFDocuments.Document