Contenuto

# Servizio SFDocuments.FormControl

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.

## Invocazione del servizio

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

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

##### In Python

          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

##### In Python

          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.

## Tipi di controllo

Il servizio FormControl è disponibile per i seguenti tipi di controllo:

- Button

- CheckBox

- ComboBox

- CurrencyField

- DateField

- FileControl

- FixedText

- FormattedField

- GroupBox

- HiddenControl

- ImageButton

- ImageControl

- ListBox

- NavigationBar

- NumericField

- PatternField

- RadioButton

- ScrollBar

- SpinButton

- TableControl

- TextField

- TimeField

## Proprietà

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, 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.

## La proprietà Value

Tipo del controllo | Tipo | Descrizione
--- | --- | ---
Button | Boolean | Applicabile solamente ai pulsanti Attiva/Disattiva.
CheckBox | Booleano o intero | 0, False: non selezionato 1, True: selezionato 2: disabilitato, "Non so" (applicabile se TripleState è True)
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 |

## Proprietà dell'evento

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
Controls | SetFocus

## Controls

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.

### Sintassi:

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

svc.Controls(controlname: str): svc

### Parametri:

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.

### Esempio:

          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

## SetFocus

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.

### Sintassi:

svc.SetFocus(): bool

### Esempio:

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

##### In Python

         bas = CreateScriptService('ScriptForge.Basic')
         doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)
         form = doc.Forms(0)
         control = form.Controls('thisControl')  # SFDocuments.FormControl
         control.SetFocus()

## Esempi aggiuntivi

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

##### In Python

         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

##### In Python

         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

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 ScriptForge.Basic

Servizio SFDocuments.Form

Servizio SFDocuments.Document