Guida di LibreOffice 25.2
Il servizio FormControl fornisce accesso ai controlli che appartengono a un formulario, un formulario secondario o a un controllo tabella di un documento contenente formulari (FormDocument). Ogni istanza del servizio FormControl si riferisce a un singolo controllo del formulario. Questo servizio permette agli utenti di:
Ottenere e impostare le proprietà del controllo rappresentato dall'istanza di FormControl.
Accedere al valore corrente visualizzato dal controllo.
Impostare lo stato attivo sul controllo desiderato.
Per usare il servizio FormControl in un particolare formulario, formulario secondario o controllo tabella, tutti i controlli devono avere nomi univoci.
Anche i Pulsanti di scelta che condividono lo stesso gruppo devono avere dei nomi di controllo univoci.
Lo scopo principale del servizio FormControl è quello di impostare ed ottenere le proprietà ed i valori visualizzati dai controlli di un formulario.
Tutti i controlli possiedono una proprietà Value. Però i suoi contenuti variano a seconda del tipo di controllo. Per maggiori informazioni consultate la proprietà Value Property di seguito.
È anche possibile formattare i controlli tramite le proprietà XControlModel e XControlView.
Il servizio SFDocuments.FormControl è strettamente collegato al servizio SFDocuments.Form.
Prima di usare il servizio FormControl è necessario caricare o importare le librerie ScriptForge:
Il servizio FormControl viene invocato da un'istanza esistente del servizio Form attraverso il suo metodo Controls.
      Dim oDoc as Object, myForm As Object, myControl As Object
      Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
      Set myForm = oDoc.Forms("formDocumentName", "formName") ' SFDocuments.Form
      Set myControl = myForm.Controls("myTextBox") ' SFDocuments.FormControl
      myControl.Value = "Current time = " & Now()
   
      from scriptforge import CreateScriptService
      from time import localtime, strftime
      bas = CreateScriptService('ScriptForge.Basic')
      doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
      form = doc.Forms('formDocumentName', 'formName')  # SFDocuments.Form
      control = form.Controls('myTextBox')  # SFDocuments.FormControl
      control.Value = 'Ora corrente = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())
   Per saperne di più su come aprire un documento contenente formulari (FormDocument) e ottenere l'accesso ai suoi formulari, fare riferimento alla pagina di aiuto del servizio SFDocuments.Form.
In alternativa, un'istanza di FormControl può essere richiamata tramite il servizio SFDocuments.FormEvent, che restituisce l'istanza della classe SFDocuments.FormControl che ha attivato l'evento.
      Sub OnEvent(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
          ' oControl ora rappresenta l'istanza della classe FormControl che ha attivato l'evento corrente
          ' ...
      End Sub
   
      def onEvent(event: uno):
          control = CreateScriptService('SfDocuments.FormEvent', event)
   Notare che negli esempi precedenti il prefisso "SFDocuments." potrebbe essere omesso.
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.
Il servizio FormControl è disponibile per i seguenti tipi di controllo:
| Button | GroupBox | PatternField | 
| Nome | Sola lettura | Tipo | Applicabile a | Descrizione | 
|---|---|---|---|---|
| Action | No | String | Button | Specifica l'azione attivata quando il pulsante viene premuto. I valori accettati sono: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord. | 
| Caption | No | String | Button, CheckBox, FixedText, GroupBox, RadioButton | Specifica il testo visualizzato dal controllo. | 
| ControlSource | Sì | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Specifica quale campo dell'insieme di dati è mappato al controllo corrente. | 
| ControlType | Sì | String | Tutto | Uno dei tipi di controllo elencati in precedenza. | 
| Default | No | Boolean | Button | Specifica se uno dei pulsanti di comando è il pulsante OK predefinito. | 
| DefaultValue | No | Variant | CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Specifica il valore predefinito usato per inizializzare un controllo in un nuovo record. | 
| Enabled | No | Boolean | Tutti (eccetto HiddenControl) | Specifica se il controllo è accessibile con il cursore. | 
| Format | No | String | DateField, TimeField, FormattedField (read-only) | Specifica il formato usato per visualizzare date e orari. Deve essere una tra le seguenti stringhe: Per le date: "Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY" , "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD". Per gli orari: "24h short", "24h long", "12h short", "12h long". | 
| ListCount | Sì | Long | ComboBox, ListBox | Restituisce il numero di righe in una Casella di riepilogo o in una Casella combinata. | 
| ListIndex | No | Long | ComboBox, ListBox | Specifica quali elementi sono selezionati in una Casella di riepilogo o in una Casella combinata. In caso di selezioni multiple, viene restituito l'indice del primo elemento o viene impostato un solo elemento. | 
| ListSource | No | Variant | ComboBox, ListBox | Specifica i dati contenuti in una Casella di riepilogo o in una Casella combinata come matrice di valori stringa con indice in base zero. Insieme a ListSourceType, può contenere anche il nome di una tabella, di una ricerca o un'istruzione SQL completa. | 
| ListSourceType | No | Integer | ComboBox, ListBox | Specifica il tipo di dati contenuti in una Casella combinata o in una Casella di riepilogo. Deve essere una delle costanti com.sun.star.form.ListSourceType.*. | 
| Locked | No | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Specifica se il controllo è di sola lettura. | 
| MultiSelect | No | Boolean | ListBox | Specifica se l'utente può selezionare più elementi in una Casella di riepilogo. | 
| Name | Sì | String | Tutto | Il nome del controllo. | 
| Parent | Sì | Object | Tutto | A seconda del tipo di elemento padre, un formulario, un formulario secondario o un controllo tabella, restituisce l'oggetto istanza della classe SFDocuments.Form o SFDocuments.FormControl. | 
| Picture | No | String | Button, ImageButton, ImageControl | Specifica il nome del file che contiene una bitmap o un altro tipo di immagine da visualizzare nel controllo. Il nome del file deve essere conforme all'attributo FileNaming del servizio ScriptForge.FileSystem. | 
| Required | No | Boolean | CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Un controllo è detto "richiesto" quando i dati sottostanti non devono contenere un valore null. | 
| Text | Sì | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Fornisce l'accesso al testo visualizzato dal controllo. | 
| TipText | No | String | Tutti (eccetto HiddenControl) | Specifica il testo visualizzato come suggerimento quando posizionate il puntatore del mouse sopra il controllo. | 
| TripleState | No | Boolean | CheckBox | Specifica se la Casella di controllo possa apparire disabilitata (in grigio). | 
| Value | No | Variant | Questa proprietà dipende dal tipo di controllo corrente. Per maggiori informazioni fate riferimento alla proprietà Value. | |
| Visible | No | Boolean | Tutti (eccetto HiddenControl) | Specifica se il controllo è nascosto o visibile. | 
| XControlModel | Sì | Oggetto della libreria UNO | Tutto | L'oggetto UNO che rappresenta il modello del controllo. Per maggiori informazioni fate riferimento a XControlModel e UnoControlModel nella documentazione delle API. | 
| XControlView | Sì | Oggetto della libreria UNO | Tutto | L'oggetto UNO che rappresenta la vista del controllo. Per maggiori informazioni fate riferimento a XControl e UnoControl nella documentazione delle API. | 
| Tipo del controllo | Tipo | Descrizione | 
|---|---|---|
| Button | Boolean | Applicabile solamente ai pulsanti Attiva/Disattiva. | 
| CheckBox | Booleano o intero | 0, False: non selezionato | 
| ComboBox | String | Il valore selezionato, in formato stringa. La proprietà ListIndex è un'opzione alternativa per accedere all'indice del valore selezionato. | 
| CurrencyField | Numerico | |
| DateField | Date | |
| FileControl | String | Un nome di file formattato in conformità con la proprietà FileNaming del servizio ScriptForge.FileSystem | 
| FormattedField | Stringa o numerico | |
| HiddenControl | String | |
| ListBox | Stringa o matrice di stringhe | La(le) riga(he) selezionate come stringa singola o matrice di stringhe. Può essere impostato solo un valore singolo. Se la casella è collegata a un database questa proprietà recupera o imposta i dati sottostanti. Altrimenti recupera o imposta i dati visualizzati. | 
| NumericField | Numerico | |
| PatternField | String | |
| RadioButton | Boolean | Ogni pulsante ha il proprio nome. I controlli di tipo Pulsante di scelta sono collegati tra loro se condividono lo stesso nome di gruppo. Se un Pulsante di scelta è impostato a True, gli altri pulsanti collegati sono automaticamente impostati a False | 
| ScrollBar | Numerico | Deve essere compreso entro i limiti prestabiliti | 
| SpinButton | Numerico | Deve essere compreso entro i limiti prestabiliti | 
| TextField | String | Il testo che appare nel campo | 
| TimeField | Date | 
Le seguenti proprietà restituiscono un insieme di stringhe in formato URI che indicano lo script attivato dall'evento.
| Nome | Sola lettura | La descrizione come etichettata nella IDE di Basic | 
|---|---|---|
| OnActionPerformed | No | Esegui azione | 
| OnAdjustmentValueChanged | No | Durante la regolazione | 
| OnApproveAction | No | Approva l'azione | 
| OnApproveReset | No | Prima di ripristinare | 
| OnApproveUpdate | No | Prima di aggiornare | 
| OnChanged | No | Modificato | 
| OnErrorOccurred | No | Si è verificato un errore | 
| OnFocusGained | No | Al ricevimento del fuoco | 
| OnFocusLost | No | Alla perdita del fuoco | 
| OnItemStateChanged | No | Lo stato dell'elemento è cambiato | 
| OnKeyPressed | No | Tasto premuto | 
| OnKeyReleased | No | Tasto rilasciato | 
| OnMouseDragged | No | Spostamento del mouse con tasto premuto | 
| OnMouseEntered | No | Mouse dentro | 
| OnMouseExited | No | Mouse fuori | 
| OnMouseMoved | No | Movimento del mouse | 
| OnMousePressed | No | Pulsante del mouse premuto | 
| OnMouseReleased | No | Pulsante del mouse rilasciato | 
| OnResetted | No | Dopo aver ripristinato | 
| OnTextChanged | No | Testo modificato | 
| OnUpdated | No | Dopo l'aggiornamento | 
Per saperne di più sulle stringhe in formato URI, fare riferimento alle Specifiche URI del framework di scripting.
| Elenco dei metodi del servizio FormControl | |
|---|---|
Questo metodo è applicabile solo ai controlli di tipo TableControl. Il valore restituito dipende dagli argomenti forniti.
Se l'argomento opzionale controlname è assente, viene restituita una matrice, con indice a partire da zero, contenente i nomi di tutti i controlli.
D'altro canto, se viene fornito un controlname, il metodo restituisce un'istanza della classe FormControl corrispondente allo specifico controllo.
svc.Controls(): str[0..*]
svc.Controls(controlname: str): svc
controlname: un nome di controllo valido, in formato stringa che distingue tra lettere minuscole e maiuscole. Se assente, viene restituito l'elenco dei nomi dei controlli in formato matrice, con indice a partire da zero.
      Dim myGrid As Object, myList As Variant, myControl As Object
      Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
      'Restituisce una matrice con i nomi di tutti i controlli di "myTableControl"
      myList = myGrid.Controls()
      ' Restituisce un'istanza della classe FormControl corrispondente a "myCheckBox"
      Set myControl = myGrid.Controls("myCheckBox")
   Usando Python:
      grid = form.Controls('myTableControl')  # SFDocuments.FormControl
      control_names = form.Controls()
      control = grid.Controls('myCheckBox')  # SFDocuments.FormControl
   Imposta il fuoco sul controllo. Restituisce True se la messa a fuoco ha avuto successo.
Questo metodo viene chiamato spesso da un evento di un formulario o di un controllo.
svc.SetFocus(): bool
      Dim oDoc As Object, oForm As Object, oControl As Object
      Set oDoc = CreateScriptService("SFDocuments.Document", ThisComponent)
      Set oForm = oDoc.Forms(0)
      Set oControl = oForm.Controls("thisControl") ' SFDocuments.FormControl
      oControl.SetFocus()
   
     bas = CreateScriptService('ScriptForge.Basic')
     doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)
     form = doc.Forms(0)
     control = form.Controls('thisControl')  # SFDocuments.FormControl
     control.SetFocus()
   Di seguito trovate due esempi che illustrano l'uso del servizio FormControl.
Il primo esempio legge il valore corrente in una Casella di riepilogo che contiene nomi di città e lo scrive in un controllo Casella di testo all'interno di un Formulario:
     Dim oDoc as Object, myForm as Object, myControl as Object
     Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
     myForm = oDoc.Forms("formDocumentName", "formName")
     Dim lbCity : lbCity = myForm.Controls("labelCity")
     Dim cbCity : cbCity = myForm.Controls("comboboxCity")
     lbCity.Caption = "Selected City: " & cbCity.Value
   
     bas = CreateScriptService('ScriptForge.Basic') # metodi in stile Basic
     doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     lbl_city = form.Controls('labelCity')
     combo_city = form.Controls('comboboxCity')
     lbl_city.Caption = "Città selezionata: " + combo_city.Value
   Il seguente frammento di codice può essere usato per elaborare controlli di tipo Pulsante di scelta che condividono lo stesso nome di gruppo. In questo esempio, supponete che ci siano tre pulsanti di scelta denominati optA, optB e optC e di voler visualizzare la didascalia del controllo selezionato.
     Dim oDoc as Object, myForm as Object
     Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
     myForm = oDoc.Forms("formDocumentName", "formName")
     Dim optNames As Object : optNames = Array("optA", "optB", "optC")
     Dim optControl as Object, opt as Variant
     For Each opt In optNames
         optControl = myForm.Controls(opt)
         If optControl.Value = True Then
             MsgBox "Opzione selezionata: " & optControl.Caption
             Exit For
         End If
     Next opt
   
     bas = CreateScriptService('ScriptForge.Basic') # metodi in stile Basic
     doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     radio_buttons = ['optA', 'optB', 'optC']
     for name in radio_buttons:
        control = form.controls(name)
        if control.Value == True:
           bas.MsgBox('Opzione selezionata: ' + control.Caption)
           break