Dienst SFDialogs.DialogControl

Der Dienst DialogControl verwaltet die Steuerelemente, die zu einem Dialog gehören, der mit dem einfachen Dialogeditor definiert wurde. Jede Instanz des aktuellen Dienstes stellt ein einzelnes Steuerelement innerhalb eines Dialogs dar.

Der Schwerpunkt liegt auf dem Abrufen und Festlegen der Werte, die von den Steuerelementen des Dialogs angezeigt werden. Auf die Formatierung kann über die Eigenschaften XControlModel und XControlView zugegriffen werden.

Beachten Sie, dass der Inhalt der eindeutigen Eigenschaft DialogControl.Value je nach Steuerelementtyp variiert.

Ein besonderes Augenmerk wird auf Steuerelemente vom Typ Baumansicht gelegt. Es ist einfach, einen Baum zu füllen, entweder Zweig für Zweig oder mit mehreren Zweigen parallel. Das Füllen eines Baumansicht-Steuerelements kann statisch oder dynamisch erfolgen.

Der Dienst SFDialogs.DialogControl ist eng verwandt mit dem Dienst SFDialogs.Dialog.

Dienstaufruf

Vor der Verwendung des Dienstes DialogControl muss die Bibliothek ScriptForge geladen oder importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

Der Dienst DialogControl wird von einer vorhandenen Dienstinstanz Dialog durch seine Methode Controls() aufgerufen. Der Dialog muss mit dem Dienst SFDialogs.Dialog initiiert werden.

      Dim myDialog As Object, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
      Set myControl = myDialog.Controls("myTextBox")
      myControl.Value = "Dialog startete um " & Now()
      myDialog.Execute()
      ' … die aktuellen Werte der Steuerung verarbeiten
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Dialog startete um " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # … die aktuellen Werte der Steuerung verarbeiten
     dlg.Terminate()
   

Abrufen der Instanz "DialogControl", die ein Steuerelementereignis ausgelöst hat

Eine Instanz des Dienstes DialogControl kann über den Dienst SFDialogs.DialogEvent abgerufen werden, sofern der Dialog mit dem Dienst Dialog initiiert wurde. Im Beispiel unten enthält oControl die Instanz DialogControl, die das Steuerungsereignis ausgelöst hat.

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

Oder mit Python:

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

Beachten Sie, dass in den vorherigen Beispielen das Präfix "SFDialogs." weggelassen werden kann, wenn es angebracht erscheint.

Behandlung von Ausnahmen in Ereignishandlern

Beim Erstellen einer Ereignisbehandlungsroutine für Steuerungsereignisse empfiehlt es sich, Fehler innerhalb der Subroutine selbst zu behandeln. Angenommen, der unten stehende Ereignishandler wird aufgerufen, wenn auf die Schaltfläche geklickt wird.

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

Rufen Sie SF_Exception.Clear auf, wenn Sie nicht möchten, dass der Fehler nach Beendigung der Dialogausführung weitergegeben wird.

Verwenden Sie in Python native Blöcke try/except für die Ausnahmebehandlung, wie unten gezeigt:

    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # Verarbeite das Ereignis
        except Exception as e:
            # Das Objekt "bas" unten ist eine Instanz des Dienstes Basic
            bas.MsgBox(str(e))
  

Steuerungstypen

Der Dienst DialogControl ist für diese Steuerelementtypen verfügbar:

Eigenschaften

Die Werteigenschaft

Es gibt keine Eigenschaft Value für die Dialogsteuerelemente "GroupBox", "Hyperlink", "ImageControl" und "TreeControl".

Ereigniseigenschaften

Das Zuweisen von Ereignissen über die Basic-IDE und das Zuweisen von Ereignissen über Makros schließen sich gegenseitig aus.

Methoden

AddSubNode

Erstellt einen neuen Knoten des Baumansicht-Steuerelements und gibt ihn als UNO-Objekt zurück, das einem übergeordneten Knoten untergeordnet ist. Siehe XMutableTreeNode in der Dokumentation der Programmierschnittstelle (API) für detaillierte Informationen.

Diese Methode kann aufgerufen werden, bevor der Dialog zum Erstellen des Anfangsbaums angezeigt wird. Es kann auch von einem Dialog- oder Steuerungsereignis aufgerufen werden – unter Verwendung des Ereignisses OnNodeExpanded – um den Baum dynamisch zu vervollständigen.

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

parentnode: Ein Knoten-UNO-Objekt vom Typ com.sun.star.awt.tree.XMutableTreeNode.

displayvalue: Der Text, der im Baumansicht-Steuerelement erscheint.

datavalue: Jeder Wert, der dem neuen Knoten zugeordnet ist. datavalue kann eine Zeichenfolge, eine Zahl oder ein Datum sein. Lassen Sie das Argument weg, wenn es nicht zutrifft.

Collabora Office Basic- und Python-Beispiele übernehmen den Dialog myDialog des aktuellen Dokuments aus der Bibliothek 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

Gibt True zurück, wenn ein Teilbaum, der einem übergeordneten Knoten untergeordnet ist, erfolgreich in ein Baumansicht-Steuerelement eingefügt werden konnte. Wenn der übergeordnete Knoten vor dem Aufrufen dieser Methode bereits untergeordnete Knoten hatte, werden die untergeordneten Knoten gelöscht.

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

parentnode: Ein Knoten-UNO-Objekt vom Typ com.sun.star.awt.tree.XMutableTreeNode.

flattree: eine zweidimensionale Matrix, sortiert nach den Spalten, welche die Anzeigewerte enthalten. Eine solche Matrix kann von der Methode GetRows ausgegeben werden, die auf den Dienst SFDatabases.Database angewendet wird. Wenn ein Matrix-Element, das den anzuzeigenden Text enthält, Empty oder Null ist, wird kein neuer Unterknoten erstellt und der Rest der Zeile wird übersprungen.

      Flacher Baum >>>> Resultierender Teilbaum
      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: Wenn der Standardwert False verwendet wird, enthält jede Spalte von flattree den Text, der im Baumansicht-Steuerelement angezeigt werden soll. Bei True stehen die anzuzeigenden Texte (displayvalue) in den Spalten 0, 2, 4, … während die Datenwerte (datavalue) sich in den Spalten 1, 3, 5, … befinden.

      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

Gibt einen neuen Wurzelknoten des Baumansicht-Steuerelements als Knoten-UNO-Objekt des Typs com.sun.star.awt.tree.XMutableTreeNode zurück. Die neue Baumwurzel wird unterhalb bereits vorhandener Wurzelknoten eingefügt. Siehe XMutableTreeNode in der Dokumentation der Programmierschnittstelle (API) für detaillierte Informationen.

Diese Methode kann aufgerufen werden, bevor der Dialog zum Erstellen des Anfangsbaums angezeigt wird. Sie kann auch von einem Dialog oder einem Steuerereignis aufgerufen werden, um den Baum dynamisch zu vervollständigen.

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

displayvalue: Der Text, der im Baumansicht-Steuerelement erscheint.

      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

Durchläuft den Baum und findet rekursiv ausgehend von der Wurzel einen Knoten, der einige Kriterien erfüllt. Entweder – eine Übereinstimmung ist genug – der Anzeigewert muss dem Muster displayvalue entsprechen oder der Datenwert ist gleich datavalue. Bei den Vergleichen kann die Groß-/Kleinschreibung beachtet werden oder nicht. Das erste übereinstimmende Vorkommen wird als Knoten-UNO-Objekt des Typs com.sun.star.awt.tree.XMutableTreeNode zurückgegeben. Siehe XMutableTreeNode in der Dokumentation der Programmierschnittstelle (API) für detaillierte Informationen.

Wenn er nicht gefunden wird, gibt die Methode Nothing zurück, um es mit der eingebauten Funktion IsNull() zu testen.

Diese Methode kann aufgerufen werden, bevor der Dialog zum Erstellen des Anfangsbaums angezeigt wird. Es kann auch von einem Dialog oder einem Steuerereignis aufgerufen werden.

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

Ein Argument aus displayvalue oder datavalue muss angegeben werden. Wenn beide vorhanden sind, reicht eine Übereinstimmung aus, um den Knoten auszuwählen.

displayvalue: Das zu vergleichende Muster. Siehe die Methode SF_String.IsLike() für die Liste der möglichen Wildcards. Wenn sie gleich der Zeichenfolge der Länge Null ist (Standard), wird nach diesem Anzeigewert nicht gesucht.

casesensitive: Standardwert ist 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

Verschiebt die obere linke Ecke eines Dialogsteuerelements auf neue Koordinaten und/oder ändert seine Abmessungen. Gibt True zurück, wenn die Größenänderung erfolgreich war.

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

Alle Abstände werden in Einheiten Map AppFont ausgedrückt und von der oberen linken Ecke des übergeordneten Dialogs aus gemessen. Ohne Argumente ändert die Methode die Größe des Steuerelements auf seine „bevorzugte Größe“, eine Größe, die abhängig von seinem tatsächlichen Inhalt angepasst wird. Fehlende Argumente bleiben unverändert.

Left: Der horizontale Abstand von der oberen linken Ecke

Top: Der vertikale Abstand von der oberen linken Ecke

Width: die horizontale Breite des Rechtecks, welches das Steuerelement enthält

Width: die vertikale Höhe des Rechtecks, welches das Steuerelement enthält

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.Resize(100, 200, Height:=6000) ' Die Breite bleibt unverändert
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.Resize(300, 200, 1500)  # Die Breite bleibt unverändert
    

SetFocus

Setzt den Fokus auf das Steuerelement. Gibt True zurück, wenn die Fokussierung erfolgreich war.

Diese Methode wird häufig von einem Dialog- oder Steuerelement-Ereignis aufgerufen.

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

Füllt ein Tablen-Steuerelement mit den angegebenen Daten. Alle bereits vorhandenen Daten werden gelöscht, bevor die neuen als Argument übergebenen Daten eingefügt werden.

Wenn das Tabellen-Steuerelement zum Dialog hinzugefügt wird, ist es möglich, die Basic IDE zu verwenden, um festzulegen, ob Spalten- und Zeilenüberschriften in der Tabelle angezeigt werden. Wenn das Tabellen-Steuerelement Spalten- und/oder Zeilenüberschriften hat, wird die erste Spalte und/oder Zeile in der bereitgestellten Datenmatrix als Beschriftung für die Tabellenüberschriften verwendet.

Diese Methode gibt True zurück, wenn sie erfolgreich war.

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

dataarray: Daten, welche in die Tabelle eingegeben werden sollen, dargestellt als eine Matrix von Matrizen in Basic oder ein Tupel von Tupeln in Python. Die Daten müssen Spalten- und Zeilenüberschriften enthalten, wenn sie vom Tabellen-Steuerelement angezeigt werden sollen.

widths: Matrix, welche die relativen Breiten jeder Spalte enthält. Mit anderen Worten: widths = (1, 2) bedeutet, dass die zweite Spalte doppelt so breit ist wie die erste. Wenn die Anzahl der Werte in der Matrix kleiner als die Anzahl der Spalten in der Tabelle ist, wird der letzte Wert in der Matrix verwendet, um die Breite der verbleibenden Spalten zu definieren.

alignments: Definiert die Ausrichtung in jeder Spalte als Zeichenfolge, in der jedes Zeichen "L" (links), "C" (Mitte), "R" (rechts) oder " " (Leerzeichen, Standard, also links für Zeichenfolgen und rechts für numerische Werte). Wenn die Länge der Zeichenfolge kürzer ist als die Anzahl der Spalten in der Tabelle, wird das letzte Zeichen der Zeichenfolge verwendet, um die Ausrichtung der verbleibenden Spalten zu definieren.

RowHeaderWidth: Breite der Zeilenkopfspalte, ausgedrückt in Einheiten Map AppFont. Standard = 10. Das Argument wird ignoriert, wenn das TableControl keinen Zeilenkopf hat.

Das folgende Beispiel geht davon aus, dass der Dialog myDialog ein Tabellen-Steuerelement namens Grid1 hat, dessen Eigenschaften "Zeilenkopf anzeigen" und "Spaltenkopf anzeigen" auf " Ja" gesetzt sind.

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

Die Eigenschaft Value gibt die ausgewählte Zeile in der Tabelle zurück. Wenn keine Zeile ausgewählt ist, wird ein leeres Matrixobjekt zurückgegeben. Der folgende Codeschnipsel zeigt, wie getestet wird, ob eine Zeile in der Tabelle ausgewählt ist.

     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "Keine Zeile ausgewählt."
     Else
         MsgBox "Zeile " & oTable.ListIndex & " ist ausgewählt."
     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

Fügt am Ende eines mehrzeiligen Textfelds eine neue Zeile hinzu. Gegebenenfalls wird ein Zeilenumbruch eingefügt. Die Methode gibt bei Erfolg True zurück.

Ein Fehler wird ausgelöst, wenn das eigentliche Steuerelement nicht vom Typ TextField oder nicht mehrzeilig ist.

svc.WriteLine(opt line: str): bool

Zeile: Die einzufügende Zeichenfolge. Standard ist eine leere Zeile.

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

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.