Obsah
Rejstřík 🔎︎

# Služba SFDialogs.Dialog

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

## Volání a použití služby

Před používáním služby Dialog 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

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 Moje makra a dialogová okna nebo Makra a dialogová okna aplikace.

## Získání instance služby Dialog, která spustila událost dialogového okna

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.

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

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

## Vlastnosti

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

## 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 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

| Metody |
--- | --- | ---
Activate Center Controls | EndExecute Execute GetTextsFromL10N | Resize SetPageManager Terminate

## Activate

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.

### Syntaxe:

svc.Activate(): bool

### Příklad:

          Dim oDlg As Object
          Set oDlg = CreateScriptService(,, "myDialog")
          oDlg.Execute()
          ' ...
          oDlg.Activate()

V příkladech v Pythonu i jazyce LibreOffice 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()

## Center

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.

### Syntaxe:

svc.Center(opt Parent: obj): bool

### Parametry:

Parent: Nepovinný objekt, kterým může být:

- objekt dialogového okna knihovny ScriptForge

- objekt dokumentu (Calc, Base, ...) knihovny ScriptForge

### Příklad:

##### V Basicu

         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

##### V Pythonu

         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:
             # ...

## Controls

Vrátí:

- seznam ovládacích prvků, které dialogové okno obsahuje

- nebo instanci třídy DialogControl podle zadaného názvu

### Syntaxe:

svc.Controls(): str[0..*]

svc.Controls(controlname: str): svc

### Parametry:

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.

### Příklad:

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

## EndExecute

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.

### Syntaxe:

svc.EndExecute(returnvalue: int)

### Parametry:

returnvalue: Hodnota předaná spuštěné metodě Execute().

### Příklad:

Pomocí jazyka LibreOffice 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 LibreOffice.

## Execute

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.

### Syntaxe:

svc.Execute(modal: bool = True): int

### Parametry:

modal: False v případě nemodálního dialogového okna. Výchozí = True.

### Příklad:

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:
             # ...

## GetTextsFromL10N

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:

- Nadpis dialogového okna.

- Popisky následujících druhů ovládacích prvků: Button, CheckBox, FixedLine, FixedText, GroupBox a RadioButton.

- Statické řetězce v prvcích ListBox a ComboBox.

- Tip nebo text nápovědy zobrazený při najetí myší nad ovládací prvek.

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.

### Syntaxe:

svc.GetTextsFromL10N(l10n: svc): bool

### Parametry:

l10n: Instance služby L10N, ze které se přeložené řetězce získají.

### Příklad:

V následujícím příkladu se načtou přeložené řetězce a použijí se na dialogové okno "MyDialog".

##### V Basicu

         oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
         myPO = CreateScriptService("L10N", "/home/user/po_files/")
         oDlg.GetTextsFromL10N(myPO)
         oDlg.Execute()

##### V Pythonu

         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.

## Resize

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.

### Syntaxe:

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

### Parametry:

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.

### Příklad:

##### V Basicu

         oDialog.Resize(1000, 2000, Height := 6000) ' Šířka se nezmění

##### V Pythonu

Pomocí Pythonu:

         oDialog.Resize(1000, 2000, Height = 6000)  # Šířka se nezmění

## SetPageManager

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čů.

- Posloupnost tlačítek: určuje sadu tlačítek, z nichž každé odpovídá stránce dialogového okna. Umístíte-li tlačítka v okně vedle sebe, můžete tím napodobit rozhraní s kartami.

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

### Syntaxe:

svc.SetPageManager(pilotcontrols: str = "", tabcontrols: str = "", wizardcontrols: str = "", opt lastpage: int): bool

### Parametry:

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

### Příklad:

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

##### V Basicu

        oDialog.SetPageManager(PilotControls := "aPageList", _
                               WizardControls := "btnPrevious,btnNext", _
                               LastPage := 3)
        oDialog.Execute()

##### V Pythonu

        dlg.SetPageManager(pilotcontrols="aPageList",
                           wizardcontrols="btnPrevious,btnNext",
                           lastpage=3)
        dlg.Execute()

## Terminate

Ukončí službu Dialog pro aktuální instanci. V případě úspěšného ukončení vrátí True.

### Syntaxe:

svc.Terminate(): bool

### Příklad:

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:

##### V Basicu

         oDlg = CreateScriptService("SFDialogs.Dialog","GlobalScope","ScriptForge","DlgConsole")
         oDlg.Execute(modal:=False)
         Wait 5000
         oDlg.Terminate()

Pomocí Pythonu:

##### V Pythonu

         from time import sleep
         dlg = CreateScriptService('SFDialogs.Dialog',"GlobalScope",'Access2Base',"dlgTrace")
         dlg.Execute(modal=False)
         sleep 5
         dlg.Terminate()

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.

Související témata

Služba SFDialogs.DialogControl

Služba ScriptForge.UI