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

     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.

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
   

     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à

Proprietà dell'evento

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

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

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.

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.

CloseFormDocument

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
   

Questo metodo chiude solo i formulari che si trovano nei documenti di Base. Se il formulario è memorizzato in un documento di Writer o di Calc la chiamata a CloseFormDocument non avrà effetto.

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.

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
   

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.

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
   

MoveFirst

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
   

MoveLast

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
   

MoveNew

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
   

MoveNext

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
   

MovePrevious

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
   

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.

svc.Requery(): bool

      myForm.Requery() ' Basic
   

      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.

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
   

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.