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.

Servizio ScriptForge.Basic

Servizio SFDocuments.Form

Servizio SFDocuments.Document