Služba SFDialogs.DialogControl

Služba DialogControl je určena pro správu ovládacích prvků náležejících k dialogovému oknu definovanému v editoru dialogových oken Basicu. Každá instance aktuální služby představuje jeden ovládací prvek v dialogovém okně.

Služba je zaměřena na získávání a nastavování hodnot zobrazených v ovládacích prvcích okna. Formátovat lze prvky prostřednictvím vlastností XControlModel a XControlView.

Obsah důležité vlastnosti DialogControl.Value závisí na druhu ovládacího prvku.

Důraz je kladen na ovládací prvky typu stromu. Lze je snadno plnit daty, buď větev po větvi, nebo najednou pro skupinu větví. Plnění může probíhat jak staticky, tak dynamicky.

Služba SFDialogs.DialogControl úzce souvisí se službou SFDialogs.Dialog.

Volání služby

Před používáním služby DialogControl je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

Instanci služby DialogControl lze vytvořit z existující instance služby Dialog pomocí její metody Controls(). Dialogové okno přitom musí být inicializováno službou SFDialogs.Dialog.

      Dim myDialog As Object, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
      Set myControl = myDialog.Controls("myTextBox")
      myControl.Value = "Dialogové okno spuštěno v čase " & Now()
      myDialog.Execute()
      ' ... zpracování hodnot z ovládacích prvků
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Dialogové okno spuštěno v čase " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # ... zpracování hodnot z ovládacích prvků
     dlg.Terminate()
   

Získání instance služby DialogControl, která spustila událost ovládacího prvku

Instanci služby DialogControl lze získat pomocí služby SFDialogs.DialogEvent, a to za předpokladu, že dialogové okno bylo službou Dialog vytvořeno. V následujícím příkladu je instanci služby DialogControl, která spustila událost dialogového okna, obsažena v proměnné oControl.

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

Nebo pomocí Pythonu:

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

Ve výše uvedených příkladech je možné předponu "SFDialogs." vynechat.

Zpracování výjimek v handlerech událostí

Při vytváření handleru události pro událost ovládacího prvku je vhodné zpracovávat chyby v samotném podprogramu. Například následující handler je volán tehdy, když je stisknuto tlačítko.

    Sub OnButtonClicked(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oControl As Object
        oControl = CreateScriptService("DialogEvent", oEvent)
        ' Zpracování události
        Exit Sub
    Catch:
        MsgBox SF_Exception.Description
        SF_Exception.Clear
    End Sub
  

Volání SF_Exception.Clear použijte, pokud si nepřejete, aby se chyba propagovala.

V Pythonu použijte pro zpracování výjimek nativní bloky try/except, jak ukazuje následující příklad:

    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # Zpracování události
        except Exception as e:
            # Objekt "bas" je instancí služby Basic
            bas.MsgBox(str(e))
  

Druhy ovládacích prvků

Služba DialogControl je k dispozici pro tyto druhy ovládacích prvků:

Vlastnosti

Vlastnost Value

Vlastnost Value neexistuje pro ovládací prvky GroupBox, Hyperlink, ImageControl a TreeControl.

Vlastnosti události

Přiřazování událostí pomocí IDE Basicu a pomocí maker se vzájemně vylučuje.

Metody

AddSubNode

Vytvoří a vrátí nový uzel ovládacího prvku strom jako objekt UNO vnořený do rodičovského uzlu. Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací (API) na stránce XMutableTreeNode.

Metodu lze zavolat před zobrazením dialogového okna a vytvořit tak počáteční strom. Je možné ji také zavolat z události okna nebo ovládacího prvku - s využitím události OnNodeExpanded - a dokončit tak vytváření stromu dynamicky.

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

parentnode: Objekt UNO s uzlem typu com.sun.star.awt.tree.XMutableTreeNode.

displayvalue: Text zobrazený v poli ovládacího prvku strom.

datavalue: Hodnota přiřazená k novému uzlu. datavalue může být řetězec, číslo nebo datum. Argument lze vynechat, pokud není relevantní.

V příkladech pro LibreOffice Basic a Python se používá z aktuálního dokumentu dialogové okno myDialog z knihovny 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

Vrátí True, pokud je možné do ovládacího prvku strom vložit podstrom vnořený do rodičovského uzlu. Uzly, které rodičovský uzel obsahoval před voláním této metody, jsou vymazány.

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

parentnode: Objekt UNO s uzlem typu com.sun.star.awt.tree.XMutableTreeNode.

flattree: dvourozměrné pole seřazené podle sloupců a obsahující hodnoty, které se mají zobrazit. Takové pole je možné získat pomocí metody GetRows použité na službu SFDatabases.Database. Jestliže položka pole obsahující text je Empty nebo Null, nový poduzel se nevytvoří a zbytek řádku se přeskočí.

      Plochý strom    >>>>    Výsledný podstrom
      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: Je-li použita výchozí hodnota False, každý sloupec argumentu flattree obsahuje text, který se má ve stromu zobrazit. Je-li hodnota True, zobrazené texty (displayvalue) jsou ve sloupcích 0, 2, 4, ..., zatímco ve sloupcích 1, 3, 5, ... jsou uloženy hodnoty dat (datavalue).

      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

Vrátí nový kořenový uzel jako objekt UNO s uzlem typu com.sun.star.awt.tree.XMutableTreeNode. Nový kořenový uzel se vloží pod dříve existující kořenové uzly. Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací (API) na stránce XMutableTreeNode.

Metodu lze zavolat před zobrazením dialogového okna a vytvořit tak počáteční strom. Je možné ji také zavolat z události okna nebo ovládacího prvku a dokončit tak vytváření stromu dynamicky.

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

displayvalue: Text zobrazený v poli ovládacího prvku strom.

      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

Projde strom a rekurzivně, počínaje kořenem, vyhledá uzel splňující určitá kritéria: jeho zobrazená hodnota odpovídá vzorku displayvalue nebo je hodnota jeho dat rovna argumentu datavalue (postačí jedno splněné kritérium). Při porovnávání se může rozlišovat velikost písmen. První výskyt splňující podmínky se vrátí jako objekt UNO s uzlem typu com.sun.star.awt.tree.XMutableTreeNode. Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací (API) na stránce XMutableTreeNode.

Není-li nic nalezeno, metoda vrátí hodnotu Nothing, kterou lze otestovat vestavěnou funkcí IsNull().

Metodu lze zavolat před zobrazením dialogového okna a vytvořit tak počáteční strom. Je možné ji také zavolat z události okna nebo ovládacího prvku.

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

Je nutné, aby byl zadán jeden z argumentů displayvalue a datavalue. Jsou-li zadány oba, pro výběr uzlu postačí splnění jedné podmínky.

displayvalue: Vzorek, jemuž odpovídající uzel se má vyhledat. Seznam povolených zástupných znaků naleznete v popisu metody SF_String.IsLike(). Pokud je roven řetězci s nulovou délkou (výchozí), zobrazená hodnota se nebude při vyhledávání používat.

casesensitive: Výchozí hodnotou je 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

Přesune levý horní roh dialogového okna na nové souřadnice a/nebo změní rozměry okna. V případě úspěšné změny vrátí True.

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

Všechny vzdálenosti jsou udávány v jednotkách AppFont a měří se od levého horního rohu rodičovského dialogového okna. Bez argumentů tato metoda nastaví prvek na „upřednostňovanou velikost“, která závisí na jeho obsahu. Vynechané argumenty zůstanou nezměněny.

Left: vodorovná vzdálenost od levého horního rohu

Top: svislá vzdálenost od levého horního rohu

Width: šířka obdélníku představujícího ovládací prvek

Height: výška obdélníku představujícího ovládací prvek

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.Resize(100, 200, Height:=6000) ' Šířka se nezmění
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.Resize(300, 200, 1500)  # Výška se nezmění
    

SetFocus

Nastaví ovládacímu prvku zaměření. V případě úspěšného nastavení vrátí True.

Metoda je často volána z událostí dialogového okna nebo ovládacího prvku.

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

Vyplní ovládací prvek TableControl daty předanými jako argument. Všechna předem existující data jsou před vložením nových vymazána.

Při přidávání prvku TableControl je možné v IDE Basicu určit, zda budou v tabulce zobrazena záhlaví sloupců a řádků. Pokud TableControl záhlaví sloupců nebo řádků má, první sloupec či řádek v zadaném poli dat bude považován za popisky v záhlaví tabulky.

V případě úspěšného nastavení vrátí metoda True.

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

dataarray: Data, která se mají do tabulky zadat, jako pole polí v Basicu nebo n-tice n-tic v Pythonu. Pokud se mají v prvku TableControl zobrazit záhlaví sloupců a řádků, musí je tabulka také obsahovat.

widths: Pole obsahující relativní šířky všech sloupců. Například widths = (1, 2) znamená, že druhý sloupec bude dvakrát širší než první. Pokud je počet hodnot v poli menší než počet sloupců tabulky, pro určení šířky zbývajících sloupců se použije poslední hodnota pole.

alignments: Určuje zarovnání všech sloupců jako řetězec, jehož znaky mohou být "L" (left, vlevo), "C" (center, na střed), "R" (right, vpravo) nebo " " (prázdný znak, výchozí, znamená zarovnání vlevo pro řetězce a vpravo pro číselné hodnoty). Pokud je délka řetězce menší než počet sloupců tabulky, pro určení zarovnání zbývajících sloupců se použije poslední znak řetězce.

RowHeaderWidth: šířka řádku se záhlavím sloupců vyjádřená v jednotkách Map AppFont. Výchozí = 10. V případě, že prvek TableControl záhlaví nemá, se tento argument ignoruje.

V následujícím příkladu se předpokládá, že dialogové okno myDialog obsahuje prvek TableControl pojmenovaný Grid1, pro nějž jsou vlastnosti „Zobrazit záhlaví řádků“ a „Zobrazit záhlaví sloupců“ nastaveny na „ano“.

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

Vlastnost Value vrátí vybraný řádek tabulky. Pokud není vybrán žádný řádek, vrátí se prázdný objekt Array. Následující část kódu ukazuje, jak ověřit, zda je v tabulce řádek vybrán.

     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "Není vybrán žádný řádek."
     Else
         MsgBox "Je vybrán řádek " & oTable.ListIndex & "."
     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

Přidá nový řádek na konec víceřádkového textového pole. Je-li to vhodné, vloží se znak nového řádku. V případě úspěšného přidání vrátí metoda True.

Pokud není druh ovládacího prvku TextField nebo není-li víceřádkový, nastane chyba.

svc.WriteLine(opt line: str): bool

Line: Řetězec, který se má vložit. Výchozí je prázdný řádek.

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

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.