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:

tip

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.

tip

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 documenti formulario.

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. Supponete di avere un file di Base denominato Employees.odb e di creare al suo interno un documento formulario per aggiungere nuovi impiegati al database. Il documento formulario 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)
  
note

Un documento formulario (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.

tip

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


Invocare il servizio

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("~/Documents/MyForm.odt")
      Set myForm = oDoc.Forms("Form1")
   
In Python

     from scriptforge import CreateScriptService
     svc = CreateScriptService('UI') 
     doc = svc.OpenDocument('~/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)
   
warning

Se provate ad accedere a un formulario (FormDocument) che in quel momento è aperto in Modo struttura, verrà sollevata 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("~/Documents/MyForms.ods")
      Set myForm = oDoc.Forms("Sheet1", "Form1")
   

Questo si ottiene allo stesso modo usando Python:


     svc = CreateScriptService('UI')
     doc = svc.OpenDocument('~/Documents/MyForms.ods')
     my_form = doc.Forms('Sheet1', 'Form1')
   

Nei documenti di Base

L'accesso ad un FormDocument all'interno di un documento di Base avviene usando il suo nome. L'esempio seguente apre il documento formulario denominato thisFormDocument ed 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)
   
note

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
   
note

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 un documento 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


tip

Per saperne di pi√Ļ sulle stringhe in formato URI, fate riferimento alle Specifiche URI del Framework di Scripting.


Elenco dei metodi del servizio Form

Activate
CloseFormDocument
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:

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()
   
note

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


CloseFormDocument

Chiude il documento 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
   
note

Questo metodo chiude solo i documenti formulario 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:

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:

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
   
warning

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.


Sosteneteci!