Contenuto

# Servizio SFDocuments.Form

Il servizio Form fornisce metodi e proprietà per gestire i formulari nei documenti di LibreOffice. Questo servizio supporta i formulari dei documenti di Base, Calc e Writer e consente di:

- Aprire e attivare formulari.

- Navigare i record mostrati dal formulario.

- Ottenere l'accesso ai controlli presenti nel formulario.

- Ottenere l'accesso ai formulari secondari all'interno di un formulario principale.

Il servizio SFDocuments.Form è disponibile in LibreOffice dalla versione 7.2 in poi.

I formulari di solito sono usati nei documenti di LibreOffice per creare delle interfacce utente collegate a dei database relazionali. Perciò, il servizio Form fornisce un accesso rapido al database collegato attraverso il servizio SFDatabases.Database.

Il servizio SFDocuments.Form è strettamente collegato al servizio SFDocuments.FormControl.

## Definizioni

### FormDocument

I formulari di solito vengono creati nei documenti di Base, ma possono essere aggiunti anche ai documenti di Writer e Calc.

In Base, ogni formulario creato usando la funzionalità Inserisci - Formulario o attraverso la Procedura guidata per la creazione dei formulari in realtà è un documento (FormDocument) che può essere gestito dal servizio Form. I documenti di Base possono contenere un numero illimitato di formulari.

Di seguito è riportato un esempio che mostra la gerarchia di tutti gli elementi coinvolti nell'accesso ai formulari principali e secondari all'interno di un documento di Base. Supponendo di avere un file di Base denominato Employees.odb e di creare al suo interno un formulario per aggiungere nuovi impiegati al database. Il documento contiene un formulario principale denominato EmployeeData che fornisce l'accesso a una tabella. C'è poi un formulario secondario WorksAtPlant che consente di associare il nuovo impiegato a uno degli stabilimenti dell'azienda.

        Employees.odb (documento di Base)
         |
         |-- AddEmployee (FormDocument)
              |
              |-- EmployeeData (Formulario principale)
                   |
                   |-- WorksAtPlant (SubForm)

Un FormDocument può essere visto come un insieme di formulari che consentono l'accesso a degli insiemi di dati, come tabelle e ricerche di un database, dall'interno di documenti di LibreOffice. È possibile accedere ai nomi di tutti i formulari e dei formulari secondari all'interno di un FormDocument usando il Navigatore formulario.

### Formulari principali e secondari

Un documento formulario è composto da uno o più formulari che, a loro volta, possono contenere un numero qualsiasi di formulari secondari. Un formulario (Form) è un insieme astratto di controlli collegati a una determinata sorgente di dati che può essere la tabella di un database, una ricerca o un'istruzione SELECT in SQL.

Nei documenti di Calc e Writer, ogni formulario può essere collegato a insiemi di dati che si trovano in database diversi. Al contrario, nei documenti di Base il database contenuto nel documento è comune a tutti i formulari.

Per invocare il servizio SFDocuments.Form fate riferimento ai metodi Forms(), FormDocuments() e OpenFormDocument() del servizio SFDocuments.Document

## Invocazione del servizio

Prima di usare il servizio Form è 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

### Nei documenti di Writer

Il seguente frammento di codice mostra come accedere al formulario denominato Form1 che si trova all'interno di un file di Writer:

          Dim oDoc As Object, myForm As Object, ui as Object
          Set ui = CreateScriptService("UI")
          Set oDoc = ui.OpenDocument("/home/user/Documents/MyForm.odt")
          Set myForm = oDoc.Forms("Form1")

##### In Python

         from scriptforge import CreateScriptService
         ui = CreateScriptService('UI')
         doc = ui.OpenDocument('/home/user/Documents/MyForm.odt')
         my_form = doc.Forms('Form1')

È possibile accedere ai formulari usando i loro nomi o i loro indici, come mostrato di seguito:

         Set myForm = oDoc.Forms(0)

##### In Python

         my_form = doc.Forms(0)

Se provate ad accedere a un formulario (FormDocument) che in quel momento è aperto in Modo struttura, si genererà un'eccezione.

### Nei documenti di Calc

In un file di Calc un formulario deve avere un nome univoco all'interno del suo foglio. Perciò, il metodo Forms richiede due argomenti, il primo indica il nome del foglio ed il secondo specifica il nome del formulario.

          Dim oDoc As Object, myForm As Object, ui as Object
          Set ui = CreateScriptService("UI")
          Set oDoc = ui.OpenDocument("/home/user/Documents/MyForms.ods")
          Set myForm = oDoc.Forms("Sheet1", "Form1")

Questo si ottiene allo stesso modo usando Python:

         ui = CreateScriptService('UI')
         doc = ui.OpenDocument('/home/user/Documents/MyForms.ods')
         my_form = doc.Forms('Sheet1', 'Form1')

### Nei documenti di Base

L'accesso a un FormDocument all'interno di un documento di Base avviene usando il suo nome. L'esempio seguente apre il documento del formulario denominato thisFormDocument e accede al formulario MainForm:

          Dim oDb As Object, myForm As Object
          Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
          'L'istruzione seguente è necessaria solo se il formulario non è stato ancora aperto
          oDb.OpenFormDocument("thisFormDocument")
          Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
          ' O, in alternativa, per accedere al formulario usando il suo indice...
          Set myForm = oDb.Forms("thisFormDocument", 0)

Per eseguire qualsiasi azione su di un formulario usando il servizio Form, il FormDocument deve essere stato aperto o manualmente dall'utente o da programma in uno script dell'utente. Quest'ultima operazione può essere eseguita chiamando il metodo OpenFormDocument del servizio Base.

Per accedere ad un determinato formulario secondario di un formulario usate il metodo SubForms. Fate attenzione che nell'esempio seguente mySubForm è una nuova istanza del servizio Form.

         Dim mySubForm As Object
         Set mySubForm = myForm.SubForms("mySubForm")

Gli esempi precedenti si traducono in Python come:

         db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
         # L'istruzione seguente è necessaria solo se il formulario non è stato ancora aperto
         form_doc = db.OpenFormDocument('thisFormDocument')
         form = form_doc.Forms('thisFormDocument', 'MainForm')
         # O, in alternativa, per accedere al formulario usando il suo indice...
         form = form_doc.Forms('thisFormDocument', 0)
         sub_form = form.SubForms('mySubForm')

### Eventi del formulario

Per invocare il servizio Form quando si verifica un evento del formulario:

          Sub OnEvent(ByRef poEvent As Object)
              Dim myForm As Object
              Set myForm = CreateScriptService("SFDocuments.FormEvent", poEvent)
              '(...)
          End sub

##### In Python

         def OnEvent(event: uno):
             form = CreateScriptService('SFDocuments.FormEvent', event)
             pass

Il servizio FormEvent è usato esclusivamente per creare istanze dei servizi SFDocuments.Form e SFDocuments.FormControl nel momento in cui si verifica un evento di un formulario o di un controllo.

Si raccomanda di liberare le risorse dopo aver usato il servizio Form.

         myForm.Dispose() ' Basic

         form.Dispose()  # Python

Questa operazione viene eseguita implicitamente quando il documento del formulario viene chiuso usando il metodo CloseFormDocument() descritto in seguito.

## Proprietà

Nome | Sola lettura | Tipo | Descrizione
--- | --- | --- | ---
AllowDeletes | No | Boolean | Specifica se il formulario permette l'eliminazione di record.
AllowInserts | No | Boolean | Specifica se il formulario permette l'aggiunta di record.
AllowUpdates | No | Boolean | Specifica se il formulario permette la modifica di record.
BaseForm | Sì | String | Specifica il nome, all'interno della gerarchia del formulario di Base, che contiene il formulario corrente.
Bookmark | No | Variant | Specifica in modo univoco il record corrente della tabella, della ricerca o dell'istruzione SQL sottostante al formulario.
CurrentRecord | No | Long | Identifica il record corrente nell'insieme dei dati visualizzati nel formulario. Se il numero della riga è positivo, il cursore si sposta a quel determinato numero di riga rispetto all'inizio dell'insieme dei risultati. Il conteggio delle righe inizia da 1. Se il numero della riga indicata è negativo, il cursore si sposta ad una riga in posizione assoluta con riferimento alla fine dell'insieme dei risultati. La riga -1 si riferisce all'ultima riga di un insieme di risultati.
Filter | No | String | Specifica un sottoinsieme di record da visualizzare usando la clausola WHERE di SQL priva della parola chiave WHERE.
LinkChildFields | Sì | String | Specifica il modo in cui i record di un formulario secondario sono collegati ai record del formulario principale.
LinkParentFields | Sì | String | Specifica il modo in cui i record di un formulario secondario sono collegati ai record del formulario principale.
Name | Sì | String | Il nome del formulario corrente.
OrderBy | No | String | Specifica in quale ordine devono essere visualizzati i record usando la clausola ORDER BY di SQL priva delle parole chiave ORDER BY.
Parent | Sì | Object | L'elemento padre del formulario corrente. Può essere sia un SFDocuments.Form o un oggetto SFDocuments.Document.
RecordSource | No | String | Specifica la sorgente dei dati, usando il nome di una tabella, di una ricerca o un'istruzione SQL.
XForm | Sì | Oggetto della libreria UNO | L'oggetto UNO che rappresenta le interazioni con il formulario. Per informazioni dettagliate fate riferimento a XForm e DataForm nella documentazione delle API.

## Proprietà dell'evento

Le seguenti proprietà restituiscono un insieme di stringhe in formato URI, che indicano lo script attivato dall'evento.

Nome | Sola lettura | Descrizione della IDE di Basic
--- | --- | ---
OnApproveCursorMove | No | Prima della modifica del record
OnApproveParameter | No | Compila parametri
OnApproveReset | No | Prima di ripristinare
OnApproveRowChange | No | Prima dell'azione sul record
OnApproveSubmit | No | Prima dell'invio
OnConfirmDelete | No | Conferma eliminazione
OnCursorMoved | No | Dopo la modifica del record
OnErrorOccurred | No | Si è verificato un errore
OnLoaded | No | Durante il caricamento
OnReloaded | No | Durante il ricaricamento
OnReloading | No | Prima di ricaricare
OnResetted | No | Dopo aver ripristinato
OnRowChanged | No | Dopo l'azione sul record
OnUnloaded | No | Durante lo scaricamento
OnUnloading | No | Prima di scaricare

Per saperne di più sulle stringhe in formato URI, fare riferimento alle Specifiche URI del framework di scripting.

Elenco dei metodi del servizio Form
Activate Controls GetDatabase MoveFirst | MoveLast MoveNext MoveNew | MovePrevious Requery SubForms

## Activate

Imposta lo stato attivo sull'istanza corrente di Form. Restituisce True se il passaggio allo stato attivo è riuscito.

Il comportamento del metodo Activate dipende dal tipo di documento in cui si trova il formulario:

- Nei documenti di Writer: imposta lo stato attivo su quel documento.

- Nei documenti di Calc: imposta lo stato attivo sul foglio a cui appartiene il formulario.

- Nei documenti di Base: imposta lo stato attivo sul documento (FormDocument) a cui il formulario (Form) si riferisce.

### Sintassi:

svc.Activate(): bool

### Esempio:

L'esempio seguente presuppone che vogliate attivare il formulario denominato FormA che si trova nel foglio Sheet1 del file di Calc attualmente aperto. In primo luogo accede al documento usando il servizio Document e ThisComponent quindi attiva il formulario.

         'Acquisisce il formulario da attivare
         Dim oDoc as Object, myForm as Object
         Set oDoc = CreateScriptService("Document", ThisComponent)
         Set myForm = oDoc.Forms("Sheet1", "FormA")
         'Attiva il formulario
         myForm.Activate()

##### In Python

         doc = CreateScriptService('Document', XSCRIPTCONTEXT.getDocument())
         form = doc.Forms('Sheet1', 'FormA')
         form.Activate()

ThisComponent si applica ai documenti di Calc e Writer. Per i documenti di Base usate ThisDataBaseDocument.

## CloseFormDocument

Questo metodo è deprecato, usare ScriptForge.FormDocument.CloseDocument al suo posto.

Chiude il documento del formulario contenente l'effettiva istanza di Form. L'istanza di Form viene eliminata.

### Sintassi:

svc.CloseFormDocument(): bool

### Esempio:

          myForm.CloseFormDocument() ' Basic

##### In Python

          form.CloseFormDocument()  # Python

## Controls

Il valore restituito dal metodo Controls dipende dagli argomenti forniti:

- Se il metodo viene chiamato senza argomenti, restituirà l'elenco dei controlli contenuti nel formulario. Notare che l'elenco restituito non contiene i controlli di alcun formulario secondario.

- Se viene fornito l'argomento opzionale ControlName, il metodo restituisce un'istanza della classe FormControl che fa riferimento al controllo specificato.

### Sintassi:

svc.Controls(opt controlname: str): any

### Parametri:

controlname: Il nome valido di un controllo, in forma di stringa sensibile alle differenze tra lettere minuscole e maiuscole. Se assente, viene restituito l'elenco dei nomi dei controlli in forma di matrice con indice a partire da zero.

### Esempio:

          Dim myForm As Object, myList As Variant, myControl As Object
          Set myForm = myDoc.Forms("myForm")
          myList = myform.Controls()
          Set myControl = myform.Controls("myTextBox") ' SFDocuments.FormControl

##### In Python

          form = doc.Forms('myForm')
          form_names = form.Controls()
          form_control = form.Controls('myTextBox')  # SFDocuments.FormControl

## GetDatabase

Restituisce un'istanza di SFDatabases.Database che fornisce l'accesso per l'esecuzione di comandi SQL sul database a cui è connesso il formulario corrente e/o che è memorizzato nel documento corrente di Base.

Ogni formulario dispone di una propria connessione al database, fatta eccezione per i documenti di Base in cui tutti condividono la stessa connessione.

### Sintassi:

svc.GetDatabase(opt user: str, opt password: str): svc

### Parametri:

user, password: I parametri opzionali di login (predefinito = "").

### Esempio:

          Dim myDb As Object ' SFDatabases.Database
          Set myDb = oForm.GetDatabase()

##### In Python

          db = form.GetDatabase()  # SFDatabases.Database

## MoveFirst

Il cursore del formulario viene posizionato sul primo record. Restituisce True se l'operazione ha esito positivo.

### Sintassi:

svc.MoveFirst(): bool

### Esempio:

          myForm.MoveFirst() ' Basic

##### In Python

          form.MoveFirst()  # Python

## MoveLast

Il cursore del formulario viene posizionato sull'ultimo record. Restituisce True se l'operazione ha esito positivo.

### Sintassi:

svc.MoveLast(): bool

### Esempio:

          myForm.MoveLast() ' Basic

##### In Python

          form.MoveLast()  # Python

## MoveNew

Il cursore del formulario viene posizionato nell'area del nuovo record. Restituisce True se l'operazione ha esito positivo.

### Sintassi:

svc.MoveNew(): bool

### Esempio:

          myForm.MoveNew() ' Basic

##### In Python

          form.MoveNew()  # Python

## MoveNext

Il cursore del formulario viene posizionato sul record successivo. Restituisce True se l'operazione ha esito positivo.

### Sintassi:

svc.MoveNext(opt offset: int): bool

### Parametri:

offset: il numero di record di cui avanzare (predefinito = 1).

### Esempio:

          myForm.MoveNext() ' Basic

##### In Python

          form.MoveNext()  # Python

## MovePrevious

Il cursore del formulario viene posizionato sul record precedente. Restituisce True se l'operazione ha esito positivo.

### Sintassi:

svc.MovePrevious(opt offset: int): bool

### Parametri:

offset: Il numero di record di cui indietreggiare (predefinito = 1).

### Esempio:

          myForm.MovePrevious() ' Basic

          form.MovePrevious()  # Python

## Requery

Ricarica i dati correnti dal database ed aggiorna il formulario. Il cursore del formulario viene posizionato sul primo record. Restituisce True se l'operazione ha esito positivo.

### Sintassi:

svc.Requery(): bool

### Esempio:

          myForm.Requery() ' Basic

##### In Python

          form.Requery()  # Python

## Subforms

Il valore restituito dal metodo Subforms dipende dagli argomenti forniti:

- Se il metodo viene chiamato senza argomenti, restituisce l'elenco dei formulari secondari contenuti nel formulario corrente o nell'istanza del formulario secondario.

- Se viene fornito l'argomento opzionale subform, il metodo restituisce una nuova istanza di SFDocuments.Form basata sul formulario o sul formulario secondario di cui è stato specificato il nome o l'indice.

### Sintassi:

svc.Subforms(): str[0..*]

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

### Parametri:

subform: Un formulario secondario dell'istanza corrente della classe Form indicata con il suo nome o indice.

Se questo argomento è assente, il metodo restituisce un elenco dei formulari secondari disponibili in una matrice con indice a partire da zero. Se il formulario contiene un solo formulario secondario potete impostare subform = 0 per accedervi.

### Esempio:

          Dim myForm As Object, myList As Variant, mySubform As Object
          myList = myform.Subforms()
          Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form

##### In Python

          subform_names = form.Subforms()
         subform = form.Subforms('mySubform')  # SFDocuments.Form

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.

Argomenti correlati

Servizio SFDatabases.Database

Servizio SFDocuments.Document

Servizio ScriptForge.UI