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.

tip

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í:

note

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

Instanci pro ovládací prvek lze také získat prostřednictvím služby SFDialogs.DialogEvent za předpokladu, že dialogové okno bylo službou Dialog inicializováno. DialogEvent totiž vrátí instanci třídy SFDialogs.DialogControl, která událost spustila.


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

     def some_event(event: uno):
         ctrl = CreateScriptService('SFDialogs.DialogEvent', event)
         # ...
   

V předchozích příkladech může být předpona "SFDialogs." vynechána.

Druhy ovládacích prvků

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

Vlastnosti

Název

Pouze pro čtení

Typ

Použitelné na

Popis

Cancel

ne

Boolean

Button

Určuje, zda se tlačítko s příkazem chová jako tlačítko Zrušit.

Caption

ne

String

Button, CheckBox, FixedLine, FixedText, GroupBox, RadioButton

Určuje text přiřazený k ovládacímu prvku.

ControlType

ano

String

všechny

Některý z výše uvedených druhů.

CurrentNode

ne

objekt
UNO

TreeControl

Aktuálně vybraný uzel stromu nacházející se nejvíce nahoře. Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací (API) na stránce XmutableTreeNode.

Default

ne

Boolean

Button

Určuje, zda je tlačítko s příkazem výchozím tlačítkem (OK).

Enabled

ne

Boolean

všechny

Určuje, zda je možné k ovládacímu prvku přistupovat pomocí kurzoru.

Format

ne

String

DateField, TimeField, FormattedField

(jen pro čtení)

Určuje formát použitý pro zobrazení data a času. Musí se jednat o některý z následujících řetězců:

Pro datum: "Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY" , "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD".

Pro čas: "24h short", "24h long", "12h short", "12h long".

ListCount

ano

Long

ComboBox, ListBox, TableControl

Určuje počet řádků v ovládacích prvcích ListBox, ComboBox nebo TableControl.

ListIndex

ne

Long

ComboBox, ListBox, TableControl

Určuje vybranou položku v ovládacích prvcích ListBox, ComboBox nebo TableControl.

Locked

ne

Boolean

ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, TextField, TimeField

Určuje, zda je ovládací prvek pouze pro čtení.

MultiSelect

ne

Boolean

ListBox

Určuje, zda může uživatel provést v seznamu vícenásobný výběr.

Name

ano

String

všechny

Název ovládacího prvku.

Page

ne

Integer

všechny

Dialogové okno může mít několik stránek, které uživatel krok za krokem prochází. Vlastnost Page objektu Dialog určuje, která stránka okna je aktivní.

Vlastnost Page ovládacího prvku určuje stránku okna, na které je ovládací prvek viditelný.

Parent

ano

služba
Dialog

všechny

Instance objektu rodičovské třídy SFDialogs.Dialog.

Picture

ne

String

Button, ImageControl

Určuje název souboru obsahujícího rastr nebo jiný typ grafiky, která se má na zadaném ovládacím prvku zobrazit. Název souboru musí odpovídat atributu FileNaming ze služby ScriptForge.FileSystem.

RootNode

ano

objekt
UNO

TreeControl

Objekt představující kořenový uzel nacházející se nejníže (obvykle existuje pouze jediný kořenový uzel). Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací (API) na stránce XmutableTreeNode.

RowSource

ne

Array of strings

ComboBox, ListBox

Určuje data obsažená v poli se seznamem nebo v seznamu.

Text

ano

String

ComboBox, FileControl, FormattedField, PatternField, TextField

Poskytuje přístup k textu zobrazenému ovládacím prvkem.

TipText

ne

String

všechny

Určuje text, který se zobrazí jako tip po najetí ukazatelem myši nad ovládací prvek.

TripleState

ne

Boolean

CheckBox

Určuje, zda může být zaškrtávací pole zobrazeno jako neaktivní (zašedlé).

Value

ne

Variant

Viz vlastnost Value

Visible

ne

Boolean

všechny

Určuje, zda ovládací prvek skrytý, nebo viditelný.

XControlModel

ano

objekt
UNO

všechny

Objekt UNO představující model ovládacího prvku. Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací (API) na stránkách XControlModel a UnoControlDialogModel.

XControlView

ano

objekt
UNO

všechny

Objekt UNO představující pohled (view) ovládacího prvku. Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací (API) na stránkách XControl a UnoControlDialog.

XTreeDataModel

ano

objekt
UNO

TreeControl

Objekt UNO představující datový model ovládacího prvku strom. Podrobné informace naleznete v dokumentaci rozhraní pro programování aplikací na stránce XMutableTreeDataModel.


The vlastnost Value

Druh ovládacího prvku

Typ

Popis

Button

Boolean

Pouze pro přepínací tlačítka.

CheckBox

Boolean nebo Integer

0, False: nezaškrtnuto
1, True: zaškrtnuto
2: zašedlé, neznámo

ComboBox

String

Vybraná hodnota. Jinou možností je vlastnost ListIndex.

CurrencyField

číselný

DateField

Date

FileControl

String

Název souboru formátovaný v souladu s vlastností FileNaming ze služby SF_FileSystem.

FormattedField

String nebo číselný

ListBox

String nebo pole řetězců

Vybraný řádek (či řádky) jako skalár nebo jako pole, v závislosti na atributu MultiSelect.

NumericField

číselný

PatternField

String

ProgressBar

číselný

Musí se nacházet v předem definovaných mezích.

RadioButton

Boolean

Každé tlačítko přepínače má vlastní název. Jsou spolu propojena v případě, že po sobě následují hodnoty jejich pozic při výběru tabulátorem. Je-li tlačítko přepínač nastaveno na True, ostatní související tlačítka se automaticky nastaví na False.

ScrollBar

číselný

Musí se nacházet v předem definovaných mezích.

TableControl

Array

Jednorozměrné pole s daty na aktuálně vybraném řádku.

TextField

String

Text zobrazený v poli.

TimeField

Date


Vlastnosti události

Vrátí řetězec URI s odkazem na skript spuštěný událostí. Specifikaci tohoto řetězce naleznete na wiki stránce Scripting framework URI specification.

Název

Pouze pro čtení

Popis zobrazený v IDE jazyka Basic

OnActionPerformed

ano

Provést akci

OnAdjustmentValueChanged

ano

Při úpravě

OnFocusGained

ano

Při zaměření

OnFocusLost

ano

Při ztrátě zaměření

OnItemStateChanged

ano

Změna stavu položky

OnKeyPressed

ano

Klávesa stisknuta

OnKeyReleased

ano

Klávesa uvolněna

OnMouseDragged

ano

Myš se pohnula spolu se stisknutou klávesou

OnMouseEntered

ano

Myš uvnitř

OnMouseExited

ano

Myš vně

OnMouseMoved

ano

Posuv myši

OnMousePressed

ano

Stisknuto tlačítko myši

OnMouseReleased

ano

Uvolněno tlačítko myši

OnNodeExpanded

ne

(není v IDE Basicu) pro uzel stromu stisknuto tlačítko rozbalení

OnNodeSelected

ne

(není v IDE Basicu) vybrán uzel stromu

OnTextChanged

ano

Text změněn


Metody

Seznam metod služby DialogControl

AddSubNode
AddSubTree
CreateRoot

FindNode
SetFocus

SetTableData
WriteLine


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.

Syntaxe:

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

Parametry:

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í.

Příklad:

V příkladech pro LibreOffice Basic a Python se používá z aktuálního dokumentu dialogové okno myDialog z knihovny Standard.

V Basicu

      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 ...")
   
V Pythonu

     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.

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.

Syntaxe:

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

Parametry:

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

Příklad:

V Basicu

      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)
   
V Pythonu

     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.

Syntaxe:

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

Parametry:

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í.

Příklad:

V Basicu

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

     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.

Syntaxe:

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

Parametry:

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.

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í.

casesensitive: Výchozí hodnotou je False.

Příklad:

V Basicu

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

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

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.

Syntaxe:

svc.SetFocus(): bool

Příklad:

V Basicu

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

      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.

Syntaxe:

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

Parametry:

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 = Array(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.

Příklad:

V Basicu

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
   
V Pythonu

     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.

Syntaxe:

svc.WriteLine(opt line: str): bool

Parametry:

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

Příklad:

V Basicu

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

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

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.


Podpořte nás!