Usługa SFDialogs.DialogControl

Usługa DialogControl zarządza formantami należącymi do okna dialogowego zdefiniowanego za pomocą edytora okien dialogowych Basic. Każde wystąpienie bieżącej usługi reprezentuje pojedynczy formant w oknie dialogowym.

Usługa koncentruje się na pobieraniu i ustawianiu wartości wyświetlanych w formantach okna. Elementy można formatować za pomocą właściwości XControlModel i XControlView.

Należy pamiętać, że zawartość unikalnej właściwości DialogControl.Value różni się w zależności od typu formantu.

Szczególną uwagę zwrócono na formantu kontroli drzewa typów. Łatwo jest obsadzić drzewo, albo gałąź po gałęzi, albo zestawem gałęzi na raz. Wypełnianie formantu drzewa może odbywać się statycznie lub dynamicznie.

Usługa SFDialogs.DialogControl jest ściśle powiązana z usługą SFDialogs.Dialog.

Wywoływanie usługi

Przed użyciem usługi DialogControl 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 DialogControl jest wywoływana z istniejącej instancji usługi Dialog poprzez jej metodę Controls(). Okno dialogowe musi zostać zainicjowane za pomocą usługi SFDialogs.Dialog.

      Dim myDialog As Object, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
      Set myControl = myDialog.Controls("myTextBox")
      myControl.Value = "Okno dialogowe uruchomiono " & Now()
      myDialog.Execute()
      ' ... przetwarzanie wartości formantów
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Okno dialogowe uruchomiono " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # ... przetwarzanie wartości formantów
     dlg.Terminate()
   

Pobieranie instancji DialogControl, która wyzwoliła zdarzenie formantu

Instancję usługi DialogControl można pobrać poprzez usługę SFDialogs.DialogEvent, pod warunkiem, że okno dialogowe zostało zainicjowane za pomocą usługi Dialog. W poniższym przykładzie oControl zawiera instancję DialogControl, która wyzwoliła zdarzenie formantu.

      Sub aControlEventHandler(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDialogs.DialogEvent", poEvent)
          ' ...
      End Sub
  

Lub używając Pythona:

     def control_event_handler(event: uno):
         oControl = CreateScriptService('SFDialogs.DialogEvent', event)
         # ...
  

Należy pamiętać, że w poprzednich przykładach przedrostek "SFDialogs." można pominąć, jeśli uzna się to za stosowne.

Obsługa wyjątków w procedurach obsługi zdarzeń

Podczas tworzenia procedury obsługi zdarzeń formantów dobrą praktyką jest obsługa błędów wewnątrz samego podprogramu. Załóżmy na przykład, że po kliknięciu przycisku wywoływana jest procedura obsługi zdarzeń poniżej.

    Sub OnButtonClicked(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oControl As Object
        oControl = CreateScriptService("DialogEvent", oEvent)
        ' Przetwarzanie zdarzeń
        Exit Sub
    Catch:
        MsgBox SF_Exception.Description
        SF_Exception.Clear
    End Sub
  

Wywołaj SF_Exception.Clear, jeśli nie chcesz, aby błąd rozprzestrzeniał się po zakończeniu wykonywania okna dialogowego.

W Pythonie użyj natywnych bloków try/except do obsługi wyjątków, jak pokazano poniżej:

    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # Przetwórz zdarzenie
        except Exception as e:
            # Obiekt "bas" poniżej jest instancją usługi Basic
            bas.MsgBox(str(e))
  

Typy formantów

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

Właściwości

Właściwość wartości

Nie ma właściwości Value dla formantów dialogowych GroupBox, Hyperlink, ImageControl i TreeControl.

Właściwości zdarzenia

Przypisywanie zdarzeń poprzez IDE Basic i przypisywanie zdarzeń poprzez makra wzajemnie się wykluczają.

Metody

AddSubNode

Utwórz i zwróć nowy węzeł formantu drzewa jako obiekt UNO podrzędny węźle nadrzędnemu. Zapoznaj się z XMutableTreeNode w dokumentacji interfejsu programowania aplikacji (API), aby uzyskać szczegółowe informacje.

Metodę tę można wywołać przed wyświetleniem okna dialogowego w celu zbudowania drzewa początkowego. Można go także wywołać z poziomu okna dialogowego lub zdarzenia formantu – przy użyciu zdarzenia OnNodeExpanded – w celu dynamicznego uzupełnienia drzewa.

svc.AddSubNode(parentnode: uno, displayvalue: str, opt datavalue: any): uno

parentnode: obiekt UNO węzła typu com.sun.star.awt.tree.XMutableTreeNode.

displayvalue: tekst pojawiający się w polu formantu drzewa.

datavalue: dowolna wartość skojarzona z nowym węzłem. datavalue może być ciągiem znaków, liczbą lub datą. Pomiń argument, jeśli nie ma zastosowania.

Przykłady LibreOffice Basic i Python wykorzystują okno dialogowe myDialog bieżącego dokumentu z biblioteki Standard.

      Dim oDlg As Object, myTree As Object, myNode As Object, theRoot As Object
      Set oDlg = CreateScriptService("Dialog",,, "myDialog")
      Set myTree = oDlg.Controls("myTreeControl")
      Set theRoot = myTree.CreateRoot("Tree top")
      Set myNode = myTree.AddSubNode(theRoot, "A branch ...")
   

     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     tree = dlg.Controls('myTreeControl')
     root = tree.CreateRoot('Tree top')
     node = tree.AddSubNode(root, 'A branch ...')
   

AddSubTree

Zwraca wartość True, gdy poddrzewo podporządkowane węzłowi nadrzędnemu można pomyślnie wstawić do formantu drzewa. Jeśli węzeł nadrzędny miał już węzły podrzędne przed wywołaniem tej metody, węzły podrzędne zostaną usunięte.

svc.AddSubTree(parentnode: uno, flattree: any, opt withdatavalue: bool): bool

parentnode: obiekt UNO węzła typu com.sun.star.awt.tree.XMutableTreeNode.

flattree: dwuwymiarowa tablica posortowana według kolumn zawierających wyświetlane wartości. Taka tablica może zostać wystawiona metodą GetRows zastosowaną w usłudze SFDatabases.Database. Gdy element tablicy zawierający tekst do wyświetlenia jest Empty lub Null, nie jest tworzony żaden nowy podwęzeł, a pozostała część wiersza jest pomijana.

      Płaskie drzewo    >>>>     Wynikowe poddrzewo
      A1	B1	C1             |__   A1	
      A1	B1	C2                   |__   B1
      A1	B2	C3                         |__  C1
      A2	B3	C4                         |__  C2
      A2	B3	C5                   |__   B2
      A3	B4	C6                         |__  C3
                             |__   A2
                                   |__   B3
                                         |__  C4
                                         |__  C5
                             |__   A3
                                   |__   B4
                                         |__  C6
   

withdatavalue: gdy używana jest domyślna wartość False, każda kolumna flattree zawiera tekst, który ma być wyświetlany w formancie drzewa. Gdy True, teksty do wyświetlenia (displayvalue) znajdują się w kolumnach 0, 2, 4, ... natomiast wartości danych (datavalue) ) znajdują się w kolumnach 1, 3, 5, ...

      Dim myTree As Object, theRoot As Object, oDb As Object, vData As Variant
      Set myTree = myDialog.Controls("myTreeControl")
      Set theRoot = myTree.CreateRoot("By product category")
      Set oDb = CreateScriptService("SFDatabases.Database", "/home/.../mydatabase.odb")
      vData = oDb.GetRows("SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] " _
          & "FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] " _
          & "ORDER BY [Category].[Name], [Product].[Name]")
      myTree.AddSubTree(theRoot, vData, WithDataValue := True)
   

     SQL_STMT = "SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] \
         FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] \
         ORDER BY [Category].[Name], [Product].[Name]"
     tree = dlg.Controls('myTreeControl')
     root = tree.CreateRoot('By Product category')
     db = CreateScriptService('SFDatabases.Database', '/home/.../mydatabase.odb')
     sub_tree = db.GetRows(SQL_STMT)
     tree.AddSubTree(root, sub_tree, withdatavalue=True)
   

CreateRoot

Zwraca nowy węzeł główny formantu drzewa jako obiekt UNO węzła typu com.sun.star.awt.tree.XMutableTreeNode. Nowy węzeł główny drzewa jest wstawiany poniżej istniejących wcześniej węzłów głównych. Zapoznaj się z XMutableTreeNode w dokumentacji interfejsu programowania aplikacji (API), aby uzyskać szczegółowe informacje.

Metodę tę można wywołać przed wyświetleniem okna dialogowego w celu zbudowania drzewa początkowego. Można go również wywołać z okna dialogowego lub zdarzenia formantu w celu dynamicznego uzupełnienia drzewa.

svc.CreateRoot(displayvalue: str, opt datavalue: any): uno

displayvalue: tekst pojawiający się w polu formantu drzewa.

      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.CreateRoot("Tree starts here ...")
   

     tree = dlg.Controls('myTreeControl')
     node = tree.CreateRoot('Tree starts here ...')
   

FindNode

Przechodzi przez drzewo i znajduje rekurencyjnie, zaczynając od korzenia, węzeł spełniający określone kryteria. Albo – wystarczy 1 dopasowanie – wartość wyświetlana jest zgodna ze wzorcem displayvalue lub wartość danych jest równa datavalue. W porównaniach może być rozróżniana wielkość liter lub nie. Pierwsze pasujące wystąpienie jest zwracane jako obiekt UNO węzła typu com.sun.star.awt.tree.XMutableTreeNode. Zapoznaj się z XMutableTreeNode w dokumentacji interfejsu programowania aplikacji (API), aby uzyskać szczegółowe informacje.

Jeśli nie zostanie znaleziona, metoda zwraca Nothing, który należy przetestować za pomocą wbudowanej funkcji IsNull().

Metodę tę można wywołać przed wyświetleniem okna dialogowego w celu zbudowania drzewa początkowego. Można go również wywołać z okna dialogowego lub zdarzenia formantu.

svc.FindNode(displayvalue: str = '', opt datavalue: any, casesensitive = False): uno

Należy określić jeden argument spośród displayvalue lub datavalue. Jeśli oba są obecne, wystarczy jedno dopasowanie, aby wybrać węzeł.

displayvalue: wzór do uzgodnienia. Listę możliwych symboli wieloznacznych znajdziesz w metodzie SF_String.IsLike(). Jeśli jest równa łańcuchowi o zerowej długości (domyślnie), ta wartość wyświetlana nie jest wyszukiwana.

casesensitive: wartość domyślna to False

      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.FindNode("*Sophie*", CaseSensitive := True)
   

     tree = dlg.Controls('myTreeControl')
     node = FindNode('*Sophie*', casesensitive=True)
     if node is None:
         # ...
   

Resize

Przesuń lewy górny róg okna dialogowego do nowych współrzędnych i/lub zmodyfikuj jego wymiary. Zwróć wartość True, jeśli zmiana rozmiaru zakończyła się pomyślnie.

svc.Resize(opt Left: int, opt Top: int, opt Width: int, opt Height: int): bool

Wszystkie odległości są wyrażone w jednostkach Map AppFont i są mierzone od lewego górnego rogu nadrzędnego okna dialogowego. Bez argumentów metoda zmienia rozmiar formantu do „preferowanego rozmiaru”, czyli rozmiaru dostosowanego w zależności od jej rzeczywistej zawartości. Brakujące argumenty pozostają niezmienione.

Left: odległość w poziomie od lewego górnego rogu

Top: odległość w pionie od lewego górnego rogu

Width: szerokość w poziomie prostokąta zawierającego formant

Height: wysokość w pionie prostokąta zawierającego formant

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.Resize(100, 200, Height:=6000) ' Szerokość pozostaje niezmieniona
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.Resize(300, 200, 1500)  # Wysokość pozostaje niezmieniona
    

SetFocus

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

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

svc.SetFocus(): bool

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.SetFocus()
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.SetFocus()
    

SetTableData

Wypełnia TableControl podanymi danymi. Wszystkie istniejące dane są usuwane przed wstawieniem nowych danych przekazanych jako argument.

Po dodaniu elementu TableControl do okna dialogowego możliwe jest użycie podstawowego środowiska IDE do określenia, czy główki kolumn i wierszy będą wyświetlane w tabeli. Jeśli TableControl ma główki kolumn i/lub wierszy, pierwsza kolumna i/lub wiersz w podanej tablicy danych są używane jako etykiety główek tabeli.

Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

svc.SetTableData(dataarray: any[0..*, 0..*], widths: int[0..*], alignments: str, RowHeaderWidth = 10): bool

dataarray: dane do wprowadzenia do tabeli reprezentowane jako tablica tablic w języku Basic lub krotka krotek w Pythonie. Dane muszą zawierać główki kolumn i wierszy, jeśli mają być wyświetlane przez TableControl.

widths: tablica zawierająca względne szerokości każdej kolumny. Innymi słowy, widths = (1, 2) oznacza, że druga kolumna jest dwa razy szersza od pierwszej. Jeżeli liczba wartości w tablicy jest mniejsza niż liczba kolumn w tabeli, to ostatnia wartość w tablicy służy do określenia szerokości pozostałych kolumn.

alignments: definiuje wyrównanie w każdej kolumnie jako ciąg znaków, w którym każdy znak może mieć postać „L” (do lewej), „C” (do środka), „R” (do prawej) lub „” (białe znaki, domyślnie, co oznacza lewy dla ciągów i prawy dla wartości liczbowe). Jeżeli długość ciągu jest krótsza niż liczba kolumn w tabeli, ostatni znak ciągu służy do określenia wyrównania pozostałych kolumn.

RowHeaderWidth: szerokość kolumny główki wiersza wyrażona w jednostkach Map AppFont. Wartość domyślna = 10. Argument jest ignorowany, jeśli TableControl nie ma główki wiersza.

W poniższym przykładzie założono, że okno dialogowe myDialog ma element TableControl o nazwie Grid1 z właściwościami „Pokaż główkę wiersza” i „Pokaż główkę kolumny” ustawionymi na „Tak".

     Dim myDialog As Object, oTable As Object, tableData As Variant
     myDialog = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")
     oTable = myDialog.Controls("Grid1")
     tableData = Array("Column A", "Column B", "Column C")
     tableData = SF_Array.AppendRow(tableData, Array("Row 1", 1, 2))
     tableData = SF_Array.AppendRow(tableData, Array("Row 2", 3, 4))
     tableData = SF_Array.AppendRow(tableData, Array("Row 3", 5, 6))
     vAlignments = "LCC"
     vWidths = Array(2, 1, 1)
     oTable.SetTableData(tableData, vWidths, vAlignments)
     myDialog.Execute()
   

Właściwość Value zwraca wybrany wiersz w tabeli. Jeśli nie zostanie wybrany żaden wiersz, zwracany jest pusty obiekt Array. Poniższy fragment kodu pokazuje, jak sprawdzić, czy w tabeli wybrano dowolny wiersz.

     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "Nie wybrano wiersza."
     Else
         MsgBox "Wiersz " & oTable.ListIndex & " jest wybrany."
     End If
   

     dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")
     table_control = dlg.Controls("Grid1")
     table_data = (("Column A", "Column B", "Column C"),
                   ("Row 1", 1, 2),
                   ("Row 2", 3, 4),
                   ("Row 3", 5, 6))
     alignments = "LCC"
     widths = (100, 50, 50)
     table_control.SetTableData(table_data, widths, alignments)
     dlg.Execute()
   

     bas = CreateScriptService("Basic")
     row_values = table_control.Value
     if len(row_values) == 0:
         bas.MsgBox("No row selected.")
     else:
         bas.MsgBox(f"Row {table_control.ListIndex} is selected.")
   

WriteLine

Dodaj nowy wiersz na końcu wielowierszowego pola tekstowego. W stosownych przypadkach zostanie wstawiony znak nowego wiersza. Metoda zwraca wartość True, jeśli operacja się powiedzie.

Jeśli formant nie jest typu TextField lub nie jest wielowierszowy, zgłaszany jest błąd.

svc.WriteLine(opt line: str): bool

Line: ciąg do wstawienia. Domyślnie jest to pusty wiersz.

      Dim oDlg As Object, oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.WriteLine("a new line")
   

     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     ctrl = dlg.Controls('thisControl')
     ctr.WriteLine("a new line")
   

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.