Tjenesten SFDialogs.DialogControl

Tjenesten DialogControl håndterer de kontroller, der hører til en dialog, der er defineret med Basics Dialogredigering. Hver forekomst af den aktuelle tjeneste repræsenterer en enkelt kontrol indenfor et dialog felt.

Fokus sættes på at hente og sætte de værdier, der vises af dialogfeltets kontroller. Formatering er tilgængelig via egenskaberne XControlModel and XControlView.

Bemærk, at indholdet af den unikke egenskab DialogControl.Value (dialogkontrol.værdi) varierer efter kontroltypen.

Kontrolelementer ordnet i en træstruktur får særlig opmærksomhed. Det er let at fylde et træ med værdier, enten gren for gren eller med flere grene på én gang. Indsættelse af værdier i et "kontroltræ" kan gøres statisk eller dynamisk.

Tjenesten SFDialogs.DialogControl er tæt beslægtet med tjenesten SFDialogs.Dialog.

Kald af tjeneste

Før brug af tjenesten DialogControl skal biblioteket ScriptForge være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

Tjenesten DialogControl kaldes fra et eksisterende eksemplar af tjenesten Dialog gennem dens metode Controls(). Dialogen skal initieres med tjenesten 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 begyndt ved " & Now()
      myDialog.Execute()
      ' ... bearbejd kontrollens faktiske værdier
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Dialog begyndt ved " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # ... bearbejder kontrollens aktuelle værdier
     dlg.Terminate()
   

Retrieving the DialogControl instance that triggered a control event

An instance of the DialogControl service can be retrieved via the SFDialogs.DialogEvent service, provided that the dialog was initiated with the Dialog service. In the example below, oControl contains the DialogControl instance that triggered the control event.

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

Or using Python:

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

Note that in the previous examples, the prefix "SFDialogs." may be omitted when deemed appropriate.

Handling exceptions in event handlers

When creating an event handler for control events it is good practice to handle errors inside the subroutine itself. For instance, suppose the event handler below is called when button is clicked.

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

Call SF_Exception.Clear if you do not want the error to propagate after the dialog execution ended.

In Python use native try/except blocks for exception handling as shown below:

    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # Process the event
        except Exception as e:
            # The object "bas" below is an instance of the Basic service
            bas.MsgBox(str(e))
  

Kontroltyper

Tjenesten DialogControl er tilgængelig for disse kontroltyper:

Egenskaber

The Value property

There's no Value property for GroupBox, Hyperlink, ImageControl and TreeControl dialog controls.

Hændelsesegenskaber

Assigning events via the Basic IDE and assigning events via macros are mutually exclusive.

Metoder

AddSubNode

Opret og returner en ny forgrening på kontroltræet som et UNO-objekt, der er underordnet en ophavsforgrening. Se detaljeret information om XMutableTreeNode (Xforanderlig forgrening) i dokumentationen til Application Programming Interface (API).

Denne metode kan eventuelt kaldes, før visning af dialogfeltet til opbygning af begyndelses-træet. Den kan også kaldes fra en dialog- eller kontrol-hændelse - med hændelsen OnNodeExpanded (ved udvidet forgrening) - så træet kan udfyldes dynamisk.

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

overordnet_forgrening: Et UNO forgreningsobjekt, af typen com.sun.star.awt.tree.XMutableTreeNode.

visningsværdi: Teksten vises i træets kontrolfelt.

dataværdi: Enhver værdi, der er forbundet med den nye forgrening. datavalue (dataværdi) kan være en streng, et tal eller en dato. Udelad argumentet, når det ikke er anvendeligt.

LibreOffice Basic- og Python-eksempler opfanger det aktuelle dokuments dialog myDialog fra biblioteket 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

Returner True (sand), når det lykkedes at indsætte en forgrening underordnet en ophavsforgrening i et kontroltræ. Hvis ophavs-forgreningen allerede havde afkoms-forgreninger, før denne metode blev kaldt, slettes afkoms-forgreningerne.

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

overordnet_forgrening: Et UNO-forgreningsobjekt, af typen com.sun.star.awt.tree.XMutableTreeNode.

fladt_træ: en to-dimensionel matrix, sorteret efter kolonner, der indeholder visningsværdierne. En sådan matrix kan udsendes af metoden GetRows anvendt på tjenesten SFDatabases.Database. Når et matrixelement indeholder den tekst, der skal vises, er Empty (tom) eller Null (nul), oprettes der ingen ny underforgrening og resten af rækken udelades.

      Flat tree (fladt træ)    >>>>    Resulting subtree (resulterende deltræ)
      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
   

med_dataværdi: Når standardværdien False (falsk) anvendes, indeholder hver kolonne i fladt_træ den tekst, der skal vises i kontroltræet. Når True (sand), er teksterne, der skal vises (displayvalue (visningsværdi)), i kolonnerne 0, 2, 4, ... , mens dataværdierne (datavalue) er i kolonnerne 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

Returnerer en ny rodforgrening på kontroltræet som et UNO-forgreningsobjekt af typen com.sun.star.awt.tree.XMutableTreeNode (Xforanderlig forgrening). Den nye rodforgrening indsættes under allerede eksisterende rodforgreninger. Se detaljeret information om XMutableTreeNode (Xforanderlig forgrening) i dokumentationen til Application Programming Interface (API).

Denne metode kan eventuelt kaldes før visning af dialogfeltet, hvor begyndelses-træet bygges. Den kunne også kaldes fra en dialog- eller kontrol-hændelse for at udfylde træet dynamisk.

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

visningsværdi: Teksten, der vises i træets kontrolfelt.

      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

Gennemgår træet rekursivt, startende fra roden, og finder en forgrending, der opfylder nogle kriterier. Ethvert - 1-match er nok - når det har en visningsværdi, der matcher mønstret visningsværdi eller har en dataværdi, der er lig med dataværdi. Sammenlignerne have eller ikke have Stort-og-småt. Den første matchende forekomst returneres som et forgrenings-UNO-objekt af typen com.sun.star.awt.tree.XMutableTreeNode. Se detaljeret information om XMutableTreeNode (Xforanderlig forgrening) i dokumentationen til Application Programming Interface (API).

Hvis den ikke findes, returnerer metoden Nothing (ingenting), som skal testes med den indbyggede funktion IsNull() (er nul()).

Den metode kan eventuelt kaldes før visning af dialogfeltet til bygning af begyndelsestræet. Den kan også kaldes fra en dialog- eller kontrol-hændelse.

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

Et af argumenterne visningsværdi eller dataværdi skal angives. Hvis begge er tilstede, er et match tilstrækkeligt til at vælge en forgrening.

visningsværdi: Det mønster, der skal matches. Se en liste over mulige jokere i metoden SF_String.IsLike() Når den er lig med en nul-længde streng (standard), søges der ikke efter denne visningsværdi.

Stort-og-småt: Standardværdien er False (falsk)

      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

Move the top-left corner of a dialog control to new coordinates and/or modify its dimensions. Return True if resizing was successful.

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

All distances are expressed in Map AppFont units and are measured from the top-left corner of the parent dialog. Without arguments the method resizes the control to its "preferred size", a size adjusted depending on its actual content. Missing arguments are left unchanged.

Left: The horizontal distance from the top-left corner

Top: The vertical distance from the top-left corner

Width: the horizontal width of the rectangle containing the control

Height: the vertical height of the rectangle containing the control

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

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

SetFocus

Sæt fokus på kontrollen. Returner True , hvis fokuseringen lykkedes.

Denne metode kaldes ofte fra en dialog eller en kontrolhændelse

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

Fylder en TableControl (tabelkontrol) med de givne data. Alle forudeksisterende data ryddes, før de nye data videregives som argument.

Når TableControl (tabelkontrollen) tilføjes til dialogen, er det muligt at Basic IDE til at definere, om kolonne- og rækkeoverskrifter skal vises i tabellen. Hvis TableControl (tabelkontrollen) har kolonne- og rækkeoverskrifter, bruges den første kolonne og/eller række i det leverede datamatrix som etiketter til tabeloverskrifterne.

Denne metode returnerer True (sand), når den lykkes.

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

datamatrix: Data, der skal indtastes i tabellen, repræsenteret som en matrix af matrixer i Basic eller en tuple af tupler i Python. Data skal indeholde kolonne- og rækkeoverskrifter, hvis de skal vises af TableControl (tabelkontrollen).

widths: Array containing the relative widths of each column. In other words, widths = (1, 2) means that the second column is twice as wide as the first one. If the number of values in the array is smaller than the number of columns in the table, then the last value in the array is used to define the width of the remaining columns.

justeringer: Definerer justeringerne i hver kolonne som en streng, hvor hvert tegn kan være "L" (Left - venstre), "C" (Center - centreret), "R" (Right - højre) eller " " (blanktegn, standard, dett vil side venstre for strenge og højre for numeriske værdier). Hvis strengens længde er kortere end antallet af kolonner i tabellen, bliver det sidste tegn i strengen brugt til at definere justeringen i de resterende kolonner.

RowHeaderWidth: width of the row header column expressed in Map AppFont units. Default = 10. The argument is ignored when the TableControl has no row header.

Det følgende eksempel antager, at dialogen myDialog har en TableControl (Tabelkontrol) kaldet Grid1 med egenskaberne "Vis rækkeoverskrift" og "Vis kolonneoverskrifter" sat til "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()
   

Egenskaben Value (værdi) returnerer den valgte række i tabellen. Hvis der ikke er valgt nogen række, returneres en tom række i tabellen. Den følgende kodestump viser, hvordan der testes, hvis der ikke er valgt nogen række i tabellen.

     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "Ingen række valgt."
     Else
         MsgBox "Række" & oTable.ListIndex & " er valgt."
     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

Tilføj en ny linje i slutningen af et tekstfelt med flere linjer. Der indsætte et linjeskift-tegn, når det er passende. Metoden returnerer True, når det er lykkedes den.

Der sættes et fejlflag, hvis den faktiske kontrol ikke er af typen TextField eller ikke har flere linjer.

svc.WriteLine(opt line: str): bool

Line (linje): Strengen, der skal indsættes. Standard er en tom linje.

      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-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.