Nápověda LibreOfficeDev 7.6
Služba Dialog přispívá ke správě dialogových oken vytvořených v editoru dialogových oken Basicu. Každá instance třídy představuje jedno dialogové okno zobrazené uživateli.
Dialogové okno může být zobrazeno v modálním nebo nemodálním režimu.
V modálním režimu se po zobrazení okna pozastaví vykonávání makra, dokud není stisknuto tlačítko OK nebo Zrušit. Mezitím může uživatel spouštět v okně specifické akce.
V nemodálním režimu je okno na pracovní ploše uživatele „plovoucí“ a vykonávání makra normálně pokračuje. Nemodální okno se zavře, pokud je ukončeno metodou Terminate() nebo pokud skončí relace LibreOfficeDev. Tlačítko pro zavření okna je v těchto oknech neaktivní.
Při explicitním zavření je dialogové okno vymazáno z paměti.
Služba SFDialogs.Dialog úzce souvisí se službou SFDialogs.DialogControl.
Před používáním služby Dialog je nutné načíst či naimportovat knihovnu ScriptForge pomocí:
Služba Dialog je vytvořena metodou CreateScriptService. Ta vyžaduje tři argumenty určující, jaké dialogové okno se má aktivovat:
Container: "GlobalScope" pro předinstalované knihovny nebo název okna, jak byl definován službou ScriptForge.UI. Výchozí hodnotou je prázdný řetězec "", který znamená aktuální dokument.
Library: Název knihovny obsažené v kontejneru, záleží u něj na velikosti písmen. Výchozí hodnotou je "Standard".
DialogName: Řetězec označující dialogové okno, záleží u něj na velikosti písmen.
V následujících příkladech pro Basic a Python se zobrazí dialogové okno dlgConsole, které je součástí sdílené knihovny ScriptForge:
      Dim oDlg As Object, lButton As Long
      Dim Container As String, Library As String, DialogName As String
      Set oDlg = CreateScriptService("SFDialogs.Dialog", "GlobalScope", "ScriptForge", "dlgConsole")
      ' ... místo pro inicializaci ovládacích prvků...
      lButton = oDlg.Execute()
      ' Výchozí režim je modální
      If lButton = oDlg.OKBUTTON Then
      ' ... Místo pro zpracování ovládacích prvků a provedení potřebných akcí
      End If
      oDlg.Terminate()
  Nebo pomocí Pythonu:
    dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')
    # ... místo pro inicializaci ovládacích prvků...
    rc = dlg.Execute()
    # Výchozí režim je modální
    if rc == dlg.OKBUTTON:
        # ... Místo pro zpracování ovládacích prvků a provedení potřebných akcí
    dlg.Terminate()
  Řetězec "GlobalScope" použije jako argument container v případě, že je dialogové okno uloženo v části nebo .
Instanci služby Dialog 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 Dialog, která spustila událost dialogového okna, obsažena v proměnné oDlg.
    Sub aDialogEventHander(ByRef poEvent As Object)
        Dim oDlg As Object
        Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent)
        ' ...
    End Sub
  Nebo pomocí Pythonu:
    def control_event_handler(event: uno):
        dlg = CreateScriptService("SFDialogs.DialogEvent", event)
        # ...
  Ve výše uvedených příkladech je možné předponu "SFDialogs." vynechat.
Při vytváření handleru události pro událost dialogového okna je vhodné zpracovávat chyby v samotném podprogramu. Například následující handler je volán tehdy, když je v dialogovém okně stisknuto tlačítko myši.
    Sub OnMouseButtonPressed(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oDialog As Object
        oDialog = 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_mouse_button_pressed(event=None):
        try:
            dlg = CreateScriptService("DialogEvent", event)
            # Zpracování události
        except Exception as e:
            # Objekt "bas" je instancí služby Basic
            bas.MsgBox(str(e))
  | Název | Pouze pro čtení | Typ | Popis | 
|---|---|---|---|
| OKBUTTON | ano | Integer | Hodnota = 1. Bylo stisknuto tlačítko OK. | 
| CANCELBUTTON | ano | Integer | Hodnota = 0. Bylo stisknuto tlačítko Zrušit. | 
| Caption | ne | String | Určuje popisek dialogového okna. | 
| Height | ne | Long | Určuje výšku dialogového okna. | 
| Modal | ano | Boolean | Určuje, zda je dialogové okno aktuálně v modálním režimu. | 
| Name | ano | String | Název dialogového okna. | 
| Page | ne | Integer | 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í. | 
| Visible | ne | Boolean | Určuje, zda je dialogové okno na pracovní ploše viditelné. Ve výchozím nastavení je viditelné až po spuštění metody Execute(). | 
| XDialogModel | ano | UNO | Objekt UNO představující model dialogového okna. Podrobné informace naleznete v dokumentaci API na stránkách XControlModel a UnoControlDialogModel. | 
| XDialogView | ano | UNO | Objekt UNO představující pohled (view) dialogového okna. Podrobné informace naleznete v dokumentaci API na stránkách XControl a UnoControlDialog. | 
| Width | ne | Long | Určuje šířku dialogového okna. | 
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 v IDE jazyka BASIC | 
|---|---|---|
| OnFocusGained | ano | Při zaměření | 
| OnFocusLost | ano | Při ztrátě zaměření | 
| 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 | 
| List of Methods in the Dialog Service | ||
|---|---|---|
Nastaví aktuální instanci služby Dialog zaměření. V případě úspěšného nastavení vrátí True.
Metoda je volána z události dialogového okna či ovládacího prvku, případně při zobrazení okna v nemodálním režimu.
svc.Activate(): bool
      Dim oDlg As Object
      Set oDlg = CreateScriptService(,, "myDialog")
      oDlg.Execute()
      ' ...
      oDlg.Activate()
   V příkladech v Pythonu i jazyce LibreOfficeDev Basic se předpokládá, že je okno uloženo v aktuálním dokumentu v knihovně Standard.
     dlg = CreateScriptService(,,'myDialog')
     dlg.Execute()
     # ...
     dlg.Activate()
   Zarovná aktuální instanci dialogového okna na střed rodičovského okna. Bez argumentů metoda dialogové okno zarovná na střed aktuálního okna.
V případě úspěšného zarovnání vrátí True.
svc.Center(opt Parent: obj): bool
Parent: Nepovinný objekt, kterým může být:
objekt dialogového okna knihovny ScriptForge
objekt dokumentu (Calc, Base, ...) knihovny ScriptForge
     Sub TriggerEvent(oEvent As Object)
         Dim oDialog1 As Object, oDialog2 As Object, lExec As Long
         Set oDialog1 = CreateScriptService("DialogEvent", oEvent) ' Dialogové okno, které způsobilo událost
         Set oDialog2 = CreateScriptService("Dialog", ...) ' Otevře druhé dialogové okno
         oDialog2.Center(oDialog1)
         lExec = oDialog2.Execute()
         Select Case lExec
             ...
     End Sub
  
     def triggerEvent(event: uno):
       dlg1 = CreateScriptService('DialogEvent.Dialog', event)  # Dialogové okno, které způsobilo událost
       dlg2 = CreateScriptService('Dialog', ...)  # Otevře druhé dialogové okno
       dlg2.Center(dlg1)
       rc = dlg2.Execute()
       if rc is False:
         # ...
   Vrátí:
seznam ovládacích prvků, které dialogové okno obsahuje
nebo instanci třídy DialogControl podle zadaného názvu
svc.Controls(): str[0..*]
svc.Controls(controlname: str): svc
ControlName : Platný název jako řetězec, u něhož záleží na velikost písmen. Není-li zadán, vrátí se seznam názvů ovládacích prvků jako pole začínající od 0.
      Dim myDialog As Object, myList As Variant, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", , "Standard", "Dialog1")
      myList = myDialog.Controls()
      Set myControl = myDialog.Controls("myTextBox")
   
     dlg = CreateScriptService('SFDialogs.Dialog','', 'Standard', 'Dialog1')
     ctrls = dlg.Controls()
     ctrl = dlg.Controls('myTextBox')
   Ukončí zobrazení modálního dialogového okna a předá zadaný argument do návratové hodnoty aktuálně spuštěné akce Excecute().
Metodu EndExecute() obvykle obsahuje zpracování makra spuštěného událostí dialogového okna či ovládacího prvku.
svc.EndExecute(returnvalue: int)
returnvalue: Hodnota předaná spuštěné metodě Execute().
Pomocí jazyka LibreOfficeDev Basic:
      Sub OnEvent(poEvent As com.sun.star.lang.EventObject)
          Dim oDlg As Object
          Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent)
          oDlg.EndExecute(ReturnValue := 25)
      End Sub
   Pomocí Pythonu:
     from com.sun.star.lang import EventObject
     def on_event(event: EventObject):
         dlg = CreateScriptService("SFDialogs.DialogEvent", event)
         dlg.EndExecute(25)
   Výše zmíněný zápis com.sun.star.lang.EventObject je nepovinný. Podobná označení napomáhají identifikovat rozhraní pro programování aplikací (API) pro LibreOfficeDev.
Zobrazí dialogové okno, a pokud je okno modální, počká na jeho zavření uživatelem. Vrácená hodnota je:
0 : stisknuto tlačítko Zrušit
nebo 1 : stisknuto tlačítko OK
Okno je možné zastavit také příkazem EndExecute() spuštěným událostí dialogového okna či ovládacího prvku.
U nemodálních oken vrátí tato metoda vždy hodnotu 0 a bude pokračovat provádění makra.
svc.Execute(modal: bool = True): int
modal: False v případě nemodálního dialogového okna. Výchozí = True.
V tomto příkladu Basicu je okno myDialog uloženo v knihovně Standard v aktuálním dokumentu.
      Dim oDlg As Object, lReturn As Long
      Set oDlg = CreateScriptService("SFDialogs.Dialog", , , "myDialog")
      lReturn = oDlg.Execute(Modal := False)
      Select Case lReturn
          ' ...
      End Select
   Tento kód v Pythonu zobrazí modální dialogového okno DlgConvert se sdílené knihovny Basicu Euro.
     dlg = CreateScriptService("SFDialogs.Dialog", 'GlobalScope', 'Euro', "DlgConvert")
     rc = dlg.Execute()
     if rc == dlg.CANCELBUTTON:
         # ...
   Nahradí všechny textové řetězce dialogového okna jejich přeloženými verzemi z instance služby L10N. Metoda přeloží následující řetězce:
V případě úspěšného nahrazení vrátí metoda True.
Seznam řetězců okna určených k překladu vytvoříte metodou AddTextsFromDialog ze služby L10N.
svc.GetTextsFromL10N(l10n: svc): bool
l10n: Instance služby L10N, ze které se přeložené řetězce získají.
V následujícím příkladu se načtou přeložené řetězce a použijí se na dialogové okno "MyDialog".
     oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
     myPO = CreateScriptService("L10N", "/home/user/po_files/")
     oDlg.GetTextsFromL10N(myPO)
     oDlg.Execute()
   
     dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
     myPO = CreateScriptService("L10N", "/home/user/po_files/")
     dlg.GetTextsFromL10N(myPO)
     dlg.Execute()
   Další informace o nakládání se soubory PO a POT naleznete na stránce služby L10N.
Přesune levý horní roh dialogového okna na nové souřadnice a/nebo změní rozměry okna. Všechny vzdálenosti jsou udávány v setinách mm. Bez argumentů tato metoda nastaví výchozí rozměry. V případě úspěšné změny vrátí True.
svc.Resize(opt Left: num, opt Top: num, opt Width: num, opt Height: num): bool
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 dialogové okno
Height: výška obdélníku představujícího dialogové okno
Záporné nebo vynechané argumenty neprovedou žádnou změnu.
     oDialog.Resize(1000, 2000, Height := 6000) ' Šířka se nezmění
   Pomocí Pythonu:
     oDialog.Resize(1000, 2000, Height = 6000)  # Šířka se nezmění
   Určuje, které ovládací prvky dialogového okna slouží k přepínání stránek. Tím usnadní správu vlastnosti Page dialogového okna a souvisejících ovládacích prvků.
Dialogová okna mohou mít více stránek. Aktuálně zobrazenou stránku určuje vlastnost Page dialogového okna. Pokud tato vlastnost není změněna, výchozí zobrazená stránka bude rovna 0 (nule), což znamená, že nebude stránka nebude určena a zobrazí se všechny viditelné ovládací prvky bez ohledu na to, jako hodnotu mají nastavenu ve svých vlastnostech Page.
Změní-li se vlastnost Page dialogového okna, například na hodnotu 1, 2, 3 atd., zobrazí se pouze ty ovládací prvky, jejichž vlastnost Page aktuální stránce dialogového okna odpovídá.
Metodou SetPageManager je možné určit čtyři typu prvků spravujících stránky:
Seznam nebo pole se seznamem: v tomto případě odpovídá stránce každá položka seznamu či pole se seznamu. První položka odkazuje na stránku 1, druhá na stránku 2 atd.
Skupina přepínačů: to, která stránka je zobrazena, bude určovat skupina přepínačů.
Sequence of buttons: defines a set of buttons, each of which corresponding to a dialog page. This can be used to emulate a tabbed interface by placing buttons side by side in the dialog.
Tlačítka Předchozí/Další: určuje, která tlačítka dialogového okna budou použita pro přechod na předchozí/další stránku.
Je možné použít více způsobů správy stránek zároveň.
Předpokládá se, že se tato metoda bude volat pouze jednou, před voláním metody Execute. Následující volání jsou ignorována.
V případě úspěšného provedení vrátí metoda True.
svc.SetPageManager(pilotcontrols: str = "", tabcontrols: str = "", wizardcontrols: str = "", opt lastpage: int): bool
pilotcontrols: čárkami oddělený seznam názvů ovládacích prvků typu ListBox, ComboBox nebo RadioButton, které se použijí pro správu stránek. U ovládacích prvků typu RadioButton zadejte název prvního prvku skupiny, která se má použít.
tabcontrols: čárkami oddělený seznam názvů tlačítek, která se použijí pro správu stránky. Pořadí, v jakém jsou zadány, odpovídá číslům stránek, ke kterým jsou přiřazeny.
wizardcontrols: čárkou oddělený seznam názvů dvou tlačítek, které se použijí jako tlačítka Předchozí/Další.
lastpage: číslo poslední dostupné stránky. Tuto hodnotu je vhodné zadat při použití správy stránek s tlačítky Předchozí/Další.
Dialogové okno obsahuje tři stránky a ovládací prvek typu ListBox pojmenovaný "aPageList", který se použije k nastavení zobrazené stránky. Kromě toho má dvě tlačítka pojmenovaná "btnPrevious" a "btnNext", která se použijí jako tlačítka Předchozí/Další.
    oDialog.SetPageManager(PilotControls := "aPageList", _
                           WizardControls := "btnPrevious,btnNext", _
                           LastPage := 3)
    oDialog.Execute()
  
    dlg.SetPageManager(pilotcontrols="aPageList",
                       wizardcontrols="btnPrevious,btnNext",
                       lastpage=3)
    dlg.Execute()
  Ukončí službu Dialog pro aktuální instanci. V případě úspěšného ukončení vrátí True.
svc.Terminate(): bool
V níže uvedených příkladech v Basicu a v Pythonu je otevřena dialogová okna DlgConsole a dlgTrace, která jsou uložena ve sdílených knihovnách ScriptForge a Access2Base. Tlačítka pro zavření okna jsou zakázána, a na konci spuštěného procesu je proto okno ukončeno explicitně.
V tomto příkladu je potlačené zavírání okna nahrazeno tlačítkem v DlgConsole:
     oDlg = CreateScriptService("SFDialogs.Dialog","GlobalScope","ScriptForge","DlgConsole")
     oDlg.Execute(modal:=False)
     Wait 5000
     oDlg.Terminate()
   Pomocí Pythonu:
     from time import sleep
     dlg = CreateScriptService('SFDialogs.Dialog',"GlobalScope",'Access2Base',"dlgTrace")
     dlg.Execute(modal=False)
     sleep 5
     dlg.Terminate()