Guida di LibreOffice 25.2
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.
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à 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.
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
Prima di usare il servizio Form è necessario caricare o importare le librerie ScriptForge:
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")
   
     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)
   
     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.
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')
   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')
   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
   
     def OnEvent(event: uno):
         form = CreateScriptService('SFDocuments.FormEvent', event)
         pass
   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.
| 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. | 
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 | ||
|---|---|---|
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.
svc.Activate(): bool
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()
   
     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.
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.
svc.CloseFormDocument(): bool
      myForm.CloseFormDocument() ' Basic
   
      form.CloseFormDocument()  # Python
   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.
svc.Controls(opt controlname: str): any
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.
      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
   
      form = doc.Forms('myForm')
      form_names = form.Controls()
      form_control = form.Controls('myTextBox')  # SFDocuments.FormControl
   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.
svc.GetDatabase(opt user: str, opt password: str): svc
user, password: I parametri opzionali di login (predefinito = "").
      Dim myDb As Object ' SFDatabases.Database
      Set myDb = oForm.GetDatabase()
   
      db = form.GetDatabase()  # SFDatabases.Database
   Il cursore del formulario viene posizionato sul primo record. Restituisce True se l'operazione ha esito positivo.
svc.MoveFirst(): bool
      myForm.MoveFirst() ' Basic
   
      form.MoveFirst()  # Python
   Il cursore del formulario viene posizionato sull'ultimo record. Restituisce True se l'operazione ha esito positivo.
svc.MoveLast(): bool
      myForm.MoveLast() ' Basic
   
      form.MoveLast()  # Python
   Il cursore del formulario viene posizionato nell'area del nuovo record. Restituisce True se l'operazione ha esito positivo.
svc.MoveNew(): bool
      myForm.MoveNew() ' Basic
   
      form.MoveNew()  # Python
   Il cursore del formulario viene posizionato sul record successivo. Restituisce True se l'operazione ha esito positivo.
svc.MoveNext(opt offset: int): bool
offset: il numero di record di cui avanzare (predefinito = 1).
      myForm.MoveNext() ' Basic
   
      form.MoveNext()  # Python
   Il cursore del formulario viene posizionato sul record precedente. Restituisce True se l'operazione ha esito positivo.
svc.MovePrevious(opt offset: int): bool
offset: Il numero di record di cui indietreggiare (predefinito = 1).
      myForm.MovePrevious() ' Basic
   
      form.MovePrevious()  # Python
   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.
svc.Requery(): bool
      myForm.Requery() ' Basic
   
      form.Requery()  # Python
   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.
svc.Subforms(): str[0..*]
svc.Subforms(subform: str): svc
svc.Subforms(subform: int): svc
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.
      Dim myForm As Object, myList As Variant, mySubform As Object
      myList = myform.Subforms()
      Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form
   
      subform_names = form.Subforms()
     subform = form.Subforms('mySubform')  # SFDocuments.Form