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:

Per usare il servizio FormControl in un particolare formulario, formulario secondario o controllo tabella, tutti i controlli devono avere nomi univoci.

warning

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.

tip

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:

note

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

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.

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.


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

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

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

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

String

Tutto

Il nome del controllo.

Parent

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

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

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

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


tip

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
   
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 o negli script in Python.


Sostienici!