service SFDialogs.DialogControl

De service DialogControl beheert de bedieningselementen die horen bij een dialoogvenster dat is gedefinieerd met de Basic Dialog Editor. Elk exemplaar van de huidige service vertegenwoordigt een enkel besturingselement in een dialoogvenster.

De focus ligt op het verkrijgen en instellen van de waarden die worden weergegeven door de bedieningselementen van het dialoogvenster. Opmaak is toegankelijk via de eigenschappen XControlModel en XControlView.

Merk op dat de unieke inhoud van de eigenschap DialogControl.Value varieert afhankelijk van het type besturingselement.

Speciale aandacht wordt besteed aan besturingen van het type boombesturing. Het is gemakkelijk om een boom te bevolken, tak voor tak, of met een set takken tegelijk. Het vullen van een boombesturing kan statisch of dynamisch worden uitgevoerd.

De service SFDialogs.DialogControl is nauw verwant aan de SFDialogs.Dialog-service.

Service aanroep

Voordat de service DialogControl gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

De service DialogControl wordt aangeroepen vanuit een bestaande instantie van de service Dialog via de methode Controls(). Het dialoogvenster moet worden gestart met de service SFDialogs.Dialog.

      Dim myDialog As Object, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
      Set myControl = myDialog.Controls("myTextBox")
      myControl.Value = "Dialog started at " & Now()
      myDialog.Execute()
      ' ... de werkelijke waarden van de besturing verwerken
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Dialog started at " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # ... de werkelijke waarden van de besturing verwerken
     dlg.Terminate()
   

De DialogControl-instantie ophalen die een besturingsgebeurtenis heeft geactiveerd

Een instantie van de DialogControl-service kan worden opgehaald via de SFDialogs.DialogEvent-service, op voorwaarde dat de dialoog is gestart met de Dialog-service. In het onderstaande voorbeeld bevat oControl de instantie DialogControl die de control-gebeurtenis heeft geactiveerd.

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

Of Python gebruiken:

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

Merk op dat in de voorgaande voorbeelden het voorvoegsel "SFDialogs." kan worden weggelaten wanneer dit passend wordt geacht.

Uitzonderingen afhandelen in eventhandlers

Bij het maken van een gebeurtenishandler voor besturingsgebeurtenissen is het een goede gewoonte om fouten binnen de subroutine zelf af te handelen. Stel bijvoorbeeld dat de onderstaande gebeurtenishandler wordt aangeroepen wanneer op de knop wordt geklikt.

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

SF_Exception.Clear aanroepen als u niet wilt dat de fout zich voortplant, nadat de uitvoering van het dialoogvenster is beëindigd.

Gebruik in Python native try/except-blokken voor het afhandelen van uitzonderingen, zoals hieronder getoond:

    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # De gebeurtenis verwerken
        except Exception as e:
            # Het object "bas" hieronder is een instantie van de Basic-service
            bas.MsgBox(str(e))
  

Besturingstypen

De service DialogControl is beschikbaar voor deze besturingstypen:

Eigenschappen

De Waarde-eigenschappen

Er is geen eigenschap Value voor de dialoogvensterbesturingselementen GroupBox, Hyperlink, ImageControl en TreeControl.

Eigenschappen gebeurtenis

Het toewijzen van gebeurtenissen via de Basic IDE en het toewijzen van gebeurtenissen via macro's sluiten elkaar uit.

Methoden

AddSubNode

Maak en retourneer een nieuw knooppunt van de boomstructuur als een UNO-object dat ondergeschikt is aan een bovenliggend knooppunt. Raadpleeg XMutableTreeNode in de Application Programming Interface (API)-documentatie voor gedetailleerde informatie.

Deze methode kan worden aangeroepen voordat het dialoogvenster wordt weergegeven om de initiële boomstructuur te bouwen. Het kan ook worden aangeroepen vanuit een dialoog of controlegebeurtenis - met behulp van de gebeurtenis OnNodeExpanded - om de boom dynamisch te voltooien.

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

parentnode: Een knooppunt UNO-object, van het type com.sun.star.awt.tree.XMutableTreeNode.

displayvalue: De tekst die in de boomstructuur verschijnt.

datavalue: Elke waarde die is gekoppeld aan het nieuwe knooppunt. datavalue kan een tekenreeks, een getal of een datum zijn. Laat het argument weg als het niet van toepassing is.

LibreOffice Basic- en Python-voorbeelden halen het dialoogvenster myDialog van het huidige document uit de bibliotheek 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

Retourneert True wanneer een subboom, ondergeschikt aan een bovenliggend knooppunt, met succes in een boomstructuur kon worden ingevoegd. Als het bovenliggende knooppunt al onderliggende knooppunten had voordat deze methode werd aangeroepen, worden de onderliggende knooppunten gewist.

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

parentnode: Een knooppunt UNO-object, van het type com.sun.star.awt.tree.XMutableTreeNode.

flattree: een tweedimensionale matrix gesorteerd op de kolommen die de weergegeven waarden bevatten. Een dergelijke matrix kan worden uitgegeven door de methode GetRows die wordt toegepast op de service SFDatabases.Database. Als een matrix-item dat de tekst bevat die moet worden weergegeven, Empty of Null is, wordt er geen nieuwe subnode gemaakt en wordt de rest van de rij overgeslagen.

      Flat tree    >>>>    Resulterende subboom
      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: Als de standaardwaarde False wordt gebruikt, bevat elke kolom van flattree de tekst die moet worden weergegeven in de boomstructuur. Wanneer True, staan de teksten die moeten worden weergegeven (displayvalue) in kolommen 0, 2, 4, ... terwijl de gegevenswaarden (datavalue) staan in kolommen 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

Retourneert een nieuw hoofdknooppunt van het boombesturingselement, als een knooppunt UNO-object van het type com.sun.star.awt.tree.XMutableTreeNode. De nieuwe boomwortel wordt ingevoegd onder reeds bestaande wortelknooppunten. Raadpleeg XMutableTreeNode in de Application Programming Interface (API)-documentatie voor gedetailleerde informatie.

Deze methode kan worden aangeroepen voordat het dialoogvenster wordt weergegeven om de initiële boomstructuur te bouwen. Het kan ook worden aangeroepen vanuit een dialoogvenser of besturingsgebeurtenis om de boom dynamisch te voltooien.

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

displayvalue: De tekst die in de boomstructuur verschijnt.

      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

Doorloopt de boom en vindt recursief, beginnend bij de wortel, een knoop die aan een aantal criteria voldoet. Ofwel - 1 overeenkomst is genoeg - waarbij de weergavewaarde overeenkomt met het patroon displayvalue of de gegevenswaarde gelijk is aan datavalue. De vergelijkingen kunnen al dan niet hoofdlettergevoelig zijn. Het eerste overeenkomende exemplaar wordt geretourneerd als een knooppunt UNO-object van het type com.sun.star.awt.tree.XMutableTreeNode. Raadpleeg XMutableTreeNode in de Application Programming Interface (API)-documentatie voor gedetailleerde informatie.

Indien niet gevonden, retourneert de methode Nothing, om te testen met de ingebouwde functie IsNull().

Deze methode kan worden aangeroepen voordat het dialoogvenster wordt weergegeven om de initiële boomstructuur te bouwen. Het kan ook worden aangeroepen vanuit een dialoog of besturingsgebeurtenis.

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

Eén argument uit displayvalue of datavalue moet worden opgegeven. Als beide aanwezig zijn, is één overeenkomst voldoende om het knooppunt te selecteren.

displayvalue: het patroon waaraan moet worden gekoppeld. Raadpleeg de SF_String.IsLike() methode voor de lijst met mogelijke jokertekens. Als deze gelijk is aan de tekenreeks met lengte nul (standaard), wordt er niet naar deze weergavewaarde gezocht.

Hoofdlettergevoelig : Standaardwaarde is 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

Verplaats de linkerbovenhoek van een dialoogvensterbesturingselement naar nieuwe coördinaten en/of wijzig de afmetingen ervan. Retourneert True als het wijzigen van de grootte is gelukt.

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

Alle afstanden worden uitgedrukt in Map AppFont unit en worden gemeten vanaf de linkerbovenhoek van het bovenliggende dialoogvenster. Zonder argumenten past de methode het besturingselement aan naar de "voorkeursgrootte", een grootte die wordt aangepast afhankelijk van de feitelijke inhoud ervan. Ontbrekende argumenten blijven ongewijzigd.

Left: De horizontale afstand vanaf de linkerbovenhoek

Top: De verticale afstand vanaf de linkerbovenhoek

Width: de horizontale breedte van de rechthoek met het besturingselement

Height: de verticale hoogte van de rechthoek met het besturingselement

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.Resize(100, 200, Height:=6000) ' Breedte is ongewijzigd
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.Resize(300, 200, 1500)  # Hoogte is ongewijzigd
    

SetFocus

Stel de focus op de besturing. Retourneer True als het scherpstellen gelukt is.

Deze methode wordt vaak aangeroepen vanuit een dialoog of controlegebeurtenis.

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

Vult een TableControl met de gegeven gegevens. Alle reeds bestaande gegevens worden gewist voordat de nieuwe gegevens worden ingevoerd die als argument zijn doorgegeven.

Wanneer de TableControl aan het dialoogvenster is toegevoegd, is het mogelijk om de Basic IDE te gebruiken om te definiëren of kolom- en rijkoppen in de tabel worden weergegeven. Als de TableControl kolom- en/of rijkoppen heeft, worden de eerste kolom en/of rij in de verstrekte gegevensmatrix gebruikt als labels voor de tabelkoppen.

Deze methode retourneert True wanneer succesvol.

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

dataarray: Gegevens die in de tabel moeten worden ingevoerd, worden weergegeven als een matrix van marixen in Basic of een tupel van tupels in Python. De gegevens moeten kolom- en rijkoppen bevatten als ze moeten worden weergegeven door de TableControl.

widths: Matrix met de relatieve breedte van elke kolom. Met andere woorden: widths = (1, 2) betekent dat de tweede kolom twee keer zo breed is als de eerste. Als het aantal waarden in de matrix kleiner is dan het aantal kolommen in de tabel, wordt de laatste waarde in de matrix gebruikt om de breedte van de overige kolommen te definiëren.

alignments: Definieert de uitlijning in elke kolom als een tekenreeks waarin elk teken "L" (Links), "C" (Midden), "R" (Rechts) of " " kan zijn (witruimte, standaard, wat betekent dat links voor tekenreeksen en rechts voor numerieke waarden). Als de lengte van de tekenreeks korter is dan het aantal kolommen in de tabel, wordt het laatste teken in de tekenreeks gebruikt om de uitlijning van de resterende kolommen te definiëren.

RowHeaderWidth: breedte van de rijkopkolom, uitgedrukt in Map AppFont units. Standaard = 10. Het argument wordt genegeerd als TableControl geen rijkop heeft.

In het volgende voorbeeld wordt ervan uitgegaan dat het dialoogvenster myDialog een TableControl heeft met de naam Grid1 met de eigenschappen "Rijkop weergeven" en "Kolomkop weergeven" ingesteld op "Ja".

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

De eigenschap Value retourneert de geselecteerde rij in de tabel. Als er geen rij is geselecteerd, wordt een leeg Matrix-object geretourneerd. Het volgende codefragment laat zien hoe u kunt testen of een rij in de tabel is geselecteerd.

     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "Geen rij geselecteerd."
     Else
         MsgBox "Rij " & oTable.ListIndex & " is geselecteerd."
     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

Voeg een nieuwe regel toe aan het einde van een tekstveld met meerdere regels. Waar nodig wordt een teken voor een nieuwe regel ingevoegd. De methode retourneert True wanneer succesvol.

Er treedt een fout op als het feitelijke besturingselement niet van het type TextField is of niet uit meerdere regels bestaat.

svc.WriteLine(opt line: str): bool

Line: De tekenreeks die moet worden ingevoegd. Standaard is een lege regel.

      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-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.