Spis treści

# Usługa SFDocuments.FormControl

Usługa FormControl zapewnia dostęp do formantów należących do formularza, podformularza lub formantów tabeli FormDocument. Każda instancja usługi FormControl odnosi się do pojedynczego formantu w formularzu. Usługa ta umożliwia użytkownikom:

- Pobieranie i ustawianie właściwości formantu reprezentowanego przez instancję FormControl.

- Uzyskanie dostępu do bieżącej wartości wyświetlanej przez formant.

- Ustawienie fokusu na żądanym formancie.

Aby skorzystać z usługi FormControl w konkretnym formularzu, podformularzu lub formancie tabeli, wszystkie formanty muszą mieć unikalne nazwy.

Przyciski opcji o tej samej nazwie grupy muszą mieć także unikalne nazwy formantu.

Głównym celem usługi FormControl jest ustawianie i pobieranie właściwości i wartości wyświetlanych przez formantu w formularzu.

Wszystkie formanty mają właściwość Value. Jednakże jego zawartość będzie się różnić w zależności od rodzaju formantu. Aby uzyskać więcej informacji, przeczytaj poniżej Właściwość Value.

Możliwe jest także formatowanie formantu poprzez właściwości XControlModel i XControlView.

Usługa SFDocuments.FormControl jest ściśle powiązana z usługą SFDocuments.Form.

## Wywoływanie usługi

Przed użyciem usługi FormControl należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

Usługa FormControl jest wywoływana z istniejącej instancji usługi Form poprzez jej metodę 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()

##### W języku 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 = 'Bieżący czas = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())

Aby dowiedzieć się więcej o otwieraniu FormDocument i uzyskiwaniu dostępu do jego formularzy, zapoznaj się ze stroną pomocy usługi SFDocuments.Form.

Ewentualnie instancję FormControl można pobrać za pośrednictwem usługi SFDocuments.FormEvent, która zwraca instancję klasy SFDocuments.FormControl, która wyzwoliła zdarzenie.

          Sub OnEvent(ByRef poEvent As Object)
              Dim oControl As Object
              Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
              ' oControl reprezentuje teraz instancję klasy FormControl, która wyzwoliła bieżące zdarzenie
              ' ...
          End Sub

##### W języku Python

          def onEvent(event: uno):
              control = CreateScriptService('SfDocuments.FormEvent', event)

Należy pamiętać, że w poprzednich przykładach przedrostek "SFDocuments." mógł zostać pominięty.

Usługa FormEvent służy wyłącznie do tworzenia instancji usług SFDocuments.Form i SFDocuments.FormControl w przypadku wystąpienia formularza lub zdarzenia formantu.

## Typy formantów

Usługa FormControl jest dostępna dla następujących typów formantu:

Button CheckBox ComboBox CurrencyField DateField FileControl FixedText FormattedField | GroupBox HiddenControl ImageButton ImageControl ListBox NavigationBar NumericField | PatternField RadioButton ScrollBar SpinButton TableControl TextField TimeField

## Właściwości

Nazwa | Tylko do odczytu | Typ | Stosuje się do | Opis
--- | --- | --- | --- | ---
Action | Nie | String | Button | Określa akcję wyzwalaną po kliknięciu przycisku. Akceptowane wartości to: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord.
Caption | Nie | String | Button, CheckBox, FixedText, GroupBox, RadioButton | Określa tekst wyświetlany przez formant.
ControlSource | Tak | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Określa pole zestawu wierszy zamapowane na bieżący formant.
ControlType | Tak | String | Wszystkie | Jeden z typów formantu wymienionych powyżej.
Default | Nie | Boolean | Button | Określa, czy przycisk polecenia jest domyślnym przyciskiem OK.
DefaultValue | Nie | Variant | CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Określa wartość domyślną używaną do inicjowania formantu w nowym rekordzie.
Enabled | Nie | Boolean | Wszystkie (oprócz HiddenControl) | Określa, czy formant jest dostępny za pomocą kursora.

Format

Nie

String

DateField, TimeField, FormattedField (read-only)

Określa format używany do wyświetlania dat i godzin. Musi to być jeden z następujących ciągów:

W przypadku dat: "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".

W przypadku godzin: "24h short", "24h long", "12h short", "12h long".

ListCount | Tak | Long | ComboBox, ListBox | Zwraca liczbę wierszy w ListBox lub ComboBox.
ListIndex | Nie | Long | ComboBox, ListBox | Określa, który element jest wybrany w ListBox lub ComboBox. W przypadku wielokrotnego wyboru zwracany jest indeks pierwszego elementu lub ustawiany jest tylko jeden element.
ListSource | Nie | Variant | ComboBox, ListBox | Określa dane zawarte w ComboBox lub ListBox jako tablicę wartości ciągów liczoną od zera. W połączeniu z ListSourceType może także zawierać nazwę tabeli, kwerendę lub pełną instrukcję SQL.
ListSourceType | Nie | Integer | ComboBox, ListBox | Określa typ danych zawartych w polu kombi lub polu listy. Musi to być jedna ze stałych com.sun.star.form.ListSourceType.*.
Locked | Nie | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Określa, czy formant jest tylko do odczytu.
MultiSelect | Nie | Boolean | ListBox | Określa, czy użytkownik może wybrać wiele elementów w polu listy.
Name | Tak | String | Wszystkie | Nazwa formantu.
Parent | Tak | Object | Wszystkie | W zależności od typu nadrzędnego, formularza, podformularza lub formantu tabeli, zwraca nadrzędny SFDocuments.Form lub SFDocuments.FormControl instancja obiektu klasy.
Picture | Nie | String | Button, ImageButton, ImageControl | Określa nazwę pliku zawierającego mapę bitową lub inny typ grafiki, która ma być wyświetlana w formancie. Nazwa pliku musi być zgodna z atrybutem FileNaming usługi ScriptForge.FileSystem.
Required | Nie | Boolean | CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Formant uznaje się za wymagany, gdy dane bazowe nie mogą zawierać wartości null.
Text | Tak | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Daje dostęp do tekstu wyświetlanego przez formant.
TipText | Nie | String | Wszystkie (oprócz HiddenControl) | Określa tekst wyświetlany jako podpowiedź po najechaniu wskaźnikiem myszy na formant.
TripleState | Nie | Boolean | CheckBox | Określa, czy formant pola wyboru może być przyciemniony (szary), czy nie.
Value | Nie | Variant |  | Ta właściwość zależy od typu formantu. Więcej informacji znajdziesz w artykule Właściwość Value.
Visible | Nie | Boolean | Wszystkie (oprócz HiddenControl) | Określa, czy formant jest ukryty czy widoczny.
XControlModel | Tak | Obiekt UNO | Wszystkie | Obiekt UNO reprezentujący model formantu. Zobacz XControlModel oraz UnoControlModel w dokumentacji API, aby uzyskać więcej informacji.
XControlView | Tak | Obiekt UNO | Wszystkie | Obiekt UNO reprezentujący widok formantu. Zobacz XControl i UnoControl w dokumentacji API, aby uzyskać więcej informacji.

## Właściwość Value

Typ formantu | Typ | Opis
--- | --- | ---
Button | Boolean | Dotyczy tylko przycisków przełączania.
CheckBox | Wartość logiczna lub liczba całkowita | 0, False: nie zaznaczono 1, True: zaznaczono 2: wyszarzone, nie wiem (dotyczy, jeśli TripleState ma wartość True)
ComboBox | String | Wybrana wartość jako ciąg. Właściwość ListIndex jest alternatywną opcją dostępu do indeksu wybranej wartości.
CurrencyField | Liczbowy |
DateField | Date |
FileControl | String | Nazwa pliku sformatowana zgodnie z właściwością FileNaming usługi ScriptForge.FileSystem
FormattedField | Ciąg lub liczba |
HiddenControl | String |
ListBox | Ciąg lub tablica ciągów | Zaznaczone wiersze jako pojedynczy ciąg lub tablica ciągów. Można ustawić tylko jedną wartość. Jeśli pole jest połączone z bazą danych, ta właściwość pobiera lub ustawia podstawowe dane. W przeciwnym razie pobiera lub ustawia wyświetlane dane.
NumericField | Liczbowy |
PatternField | String |
RadioButton | Boolean | Każdy przycisk ma swoją nazwę. Wiele formantów RadioButton jest ze sobą połączonych, jeśli mają tę samą nazwę grupy. Jeśli RadioButton jest ustawiony na True, inne powiązane przyciski są automatycznie ustawiane na False
ScrollBar | Liczbowy | Musi mieścić się w określonych granicach
SpinButton | Liczbowy | Musi mieścić się w określonych granicach
TextField | String | Tekst pojawiający się w polu
TimeField | Date |

## Właściwości zdarzenia

Poniższe właściwości zwracają lub ustawiają ciągi URI, które definiują skrypt wyzwalany przez zdarzenie.

Nazwa | Tylko do odczytu | Opis zgodny z etykietą w środowisku IDE Basic
--- | --- | ---
OnActionPerformed | Nie | Wykonaj działanie
OnAdjustmentValueChanged | Nie | W trakcie dopasowywania
OnApproveAction | Nie | Zatwierdź działanie
OnApproveReset | Nie | Przed zresetowaniem
OnApproveUpdate | Nie | Przed aktualizacją
OnChanged | Nie | Zmieniono
OnErrorOccurred | Nie | Wystąpił błąd
OnFocusGained | Nie | Przy uzyskaniu fokusu
OnFocusLost | Nie | Przy utracie fokusu
OnItemStateChanged | Nie | Zmieniony stan elementu
OnKeyPressed | Nie | Klawisz naciśnięty
OnKeyReleased | Nie | Klawisz zwolniony
OnMouseDragged | Nie | Przesunięcie myszy podczas wciśnięcia klawisza
OnMouseEntered | Nie | Mysz wewnątrz
OnMouseExited | Nie | Mysz na zewnątrz
OnMouseMoved | Nie | Przesunięcie myszy
OnMousePressed | Nie | Naciśnięto przycisk myszy
OnMouseReleased | Nie | Zwolniono przycisk myszy
OnResetted | Nie | Po resetowaniu
OnTextChanged | Nie | Tekst zmodyfikowano
OnUpdated | Nie | Po aktualizacji

Aby dowiedzieć się więcej o ciągach URI, zapoznaj się z Specyfikacją URI platformy skryptowej.

Lista metod w usłudze FormControl
Controls | SetFocus

## Controls

Ta metoda ma zastosowanie tylko do formantów typu TableControl. Zwracana wartość zależy od podanych argumentów.

Jeśli opcjonalny argument controlname jest nieobecny, zwracana jest tablica liczona od zera zawierająca nazwy wszystkich formantów.

Z drugiej strony, jeśli podano controlname, metoda zwraca instancję klasy FormControl odpowiadającą określonemu formantowi.

### Składnia:

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

svc.Controls(controlname: str): svc

### Parametry:

controlname: prawidłowa nazwa formantu jako ciąg znaków, w którym rozróżniana jest wielkość liter. W przypadku braku, lista nazw formantów jest zwracana jako tablica liczona od zera.

### Przykład:

          Dim myGrid As Object, myList As Variant, myControl As Object
          Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
          ' Zwraca tablicę z nazwami wszystkich formantów w "myTableControl"
          myList = myGrid.Controls()
          ' Zwraca instancję klasy FormControl odpowiadającą "myCheckBox"
          Set myControl = myGrid.Controls("myCheckBox")

Korzystanie z języka Python:

          grid = form.Controls('myTableControl')  # SFDocuments.FormControl
          control_names = form.Controls()
          control = grid.Controls('myCheckBox')  # SFDocuments.FormControl

## SetFocus

Ustawia fokus na formant. Zwróć True, jeśli ustawienie fokusu się powiodło.

Ta metoda jest często wywoływana z formularza lub zdarzenia formantu.

### Składnia:

svc.SetFocus(): bool

### Przykład:

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

##### W języku Python

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

## Dodatkowe przykłady

Poniżej dwa przykłady ilustrujące zastosowanie usługi FormControl.

Pierwszy przykład odczytuje bieżącą wartość w ComboBox zawierającym nazwy miast i zapisuje ją do formantu FixTest w formularzu:

         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

##### W języku Python

         bas = CreateScriptService('ScriptForge.Basic')  # metody jak w 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 = "Wybrane miasto: " + combo_city.Value

Poniższego fragmentu kodu można użyć do przetwarzania formantów RadioButton, które mają tę samą nazwę grupy. W tym przykładzie załóżmy, że istnieją trzy przyciski opcji o nazwach optA, optB i optC i chcemy wyświetlić podpis wybranego formantu.

         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 "Wybrana opcja: " & optControl.Caption
                 Exit For
             End If
         Next opt

##### W języku Python

         bas = CreateScriptService('ScriptForge.Basic')  # metody jak w 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('Wybrana opcja: ' + control.Caption)
               break

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Usługa ScriptForge.Basic

Usługa SFDocuments.Form

Usługa SFDocuments.Document