Usługa SFDialogs.Dialog

Usługa Dialog pomaga w zarządzaniu oknami dialogowymi utworzonymi za pomocą edytora okien dialogowych Basic. Każde wystąpienie bieżącej klasy reprezentuje pojedyncze okno dialogowe wyświetlane użytkownikowi.

tip

Okno dialogowe może być wyświetlane w trybie modalnym lub niemodalnym.


W trybie modalnym pole jest wyświetlane, a wykonywanie procesu makro jest zawieszane do czasu naciśnięcia jednego z przycisków OK lub Anuluj. W międzyczasie działania użytkownika wykonane na skrzynce mogą wywołać określone działania.

W trybie niemodalnym okno dialogowe „pływa” na pulpicie użytkownika, a wykonywanie procesu makro przebiega normalnie. Niemodalne okno dialogowe jest zamykane po zakończeniu metodą Terminate() lub po zakończeniu sesji LibreOffice. W niemodalnych oknach dialogowych przycisk zamykania okna jest nieaktywny.

Okno dialogowe znika z pamięci po jego jawnym zakończeniu.

tip

Usługa SFDialogs.Dialog jest ściśle powiązana z usługą SFDialogs.DialogControl.


Wywoływanie usług i korzystanie z nich

Przed użyciem usługi Dialog należy załadować lub zaimportować bibliotekę ScriptForge:

note

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService


Usługę Dialog wywołuje się za pomocą metody CreateScriptService. Aby określić okno dialogowe do aktywacji, wymagane są trzy argumenty pozycyjne:

Container: "GlobalScope" dla preinstalowanych bibliotek lub nazwa okna zdefiniowana przez usługę ScriptForge.UI. Wartość domyślna pustego ciągu "" oznacza bieżący dokument.

Library: nazwa biblioteki zawartej w kontenerze, w której uwzględniana jest wielkość liter. Wartość domyślna to „Standard”.

DialogName: ciąg znaków, w którym rozróżniana jest wielkość liter, określający okno dialogowe.

Poniższe przykłady w języku Basic i Python przedstawiają okno dialogowe dlgConsole należące do biblioteki współdzielonej 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")
      '... miejsce do inicjowania formantów...
      lButton = oDlg.Execute()
      ' Domyślnym trybem jest tryb modalny
      If lButton = oDlg.OKBUTTON Then
      '... Miejsce przetwarzania formantów i wykonywania niezbędnych działań
      End If
      oDlg.Terminate()
  

Lub używając Pythona:


    dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')
    # ... miejsce do inicjowania formantów...
    rc = dlg.Execute()
    # Trybem domyślnym jest modalny
    if rc == dlg.OKBUTTON:
        # ... Miejsce przetwarzania formantów i wykonywania niezbędnych działań
    dlg.Terminate()
  
note

Użyj ciągu „GlobalScope” jako argumentu container, gdy okno dialogowe jest przechowywane w Moje makra i okna dialogowe lub w Makra i okna dialogowe aplikacji.


Pobieranie instancji Dialog, która wyzwoliła zdarzenie dialogowe

Instancję usługi Dialog można pobrać poprzez usługę SFDialogs.DialogEvent, pod warunkiem, że okno dialogowe zostało zainicjowane za pomocą usługi Dialog. W poniższym przykładzie oDlg zawiera instancję Dialog, która wyzwoliła zdarzenie dialogowe.


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

Lub używając Pythona:


    def control_event_handler(event: uno):
        dlg = CreateScriptService("SFDialogs.DialogEvent", event)
        # ...
  

Należy pamiętać, że w poprzednich przykładach przedrostek "SFDialogs." można pominąć, jeśli uzna się to za stosowne.

Obsługa wyjątków w procedurach obsługi zdarzeń

Podczas tworzenia procedury obsługi zdarzeń dla zdarzeń dialogowych dobrą praktyką jest obsługa błędów wewnątrz samego podprogramu. Załóżmy na przykład, że poniższa procedura obsługi zdarzeń jest wywoływana po naciśnięciu przycisku myszy w oknie dialogowym.


    Sub OnMouseButtonPressed(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oDialog As Object
        oDialog = CreateScriptService("DialogEvent", oEvent)
        ' Przetwarzanie zdarzeń
        Exit Sub
    Catch:
        MsgBox SF_Exception.Description
        SF_Exception.Clear
    End Sub
  
tip

Wywołaj SF_Exception.Clear, jeśli nie chcesz, aby błąd rozprzestrzeniał się po zakończeniu wykonywania okna dialogowego.


W Pythonie użyj natywnych bloków try/except do obsługi wyjątków, jak pokazano poniżej:


    def on_mouse_button_pressed(event=None):
        try:
            dlg = CreateScriptService("DialogEvent", event)
            # Przetwórz zdarzenie
        except Exception as e:
            # Obiekt „bas” jest instancją usługi Basic
            bas.MsgBox(str(e))
  

Właściwości

Nazwa

Tylko do odczytu

Typ

Opis

OKBUTTON

Tak

Integer

Wartość = 1. Naciśnięto przycisk OK.

CANCELBUTTON

Tak

Integer

Wartość = 0. Naciśnięto przycisk Anuluj.

Caption

Nie

String

Określ tytuł okna dialogowego.

Height

Nie

Long

Określ wysokość okna dialogowego.

Modal

Tak

Boolean

Określa, czy okno dialogowe jest aktualnie wykonywane w trybie modalnym.

Name

Tak

String

Nazwa okna dialogowego

Page

Nie

Integer

Okno dialogowe może składać się z kilku stron, po których użytkownik może przechodzić krok po kroku. Właściwość Page obiektu Dialog określa, która strona okna dialogowego jest aktywna.

Visible

Nie

Boolean

Określa, czy okno dialogowe jest widoczne na pulpicie. Domyślnie jest ono widoczne dopiero po wywołaniu metody Execute().

XDialogModel

Tak

UNO
object

Obiekt UNO reprezentujący model okna dialogowego. Zobacz XControlModel i UnoControlDialogModel w dokumentacji interfejsu programowania aplikacji (API), aby uzyskać szczegółowe informacje.

XDialogView

Tak

UNO
object

Obiekt UNO reprezentujący widok okna dialogowego. Zobacz XControl i UnoControlDialog w dokumentacji interfejsu programowania aplikacji (API), aby uzyskać szczegółowe informacje.

Width

Nie

Long

Określ szerokość okna dialogowego.


Właściwości zdarzenia

Zwraca ciąg URI z odwołaniem do skryptu wywołanego zdarzeniem. Przeczytaj jego specyfikację w specyfikacji URI struktury skryptowej.

Nazwa

Tylko do odczytu

Opis IDE Basic

OnFocusGained

Tak

Przy uzyskaniu fokusu

OnFocusLost

Tak

Przy utracie fokusu

OnKeyPressed

Tak

Klawisz naciśnięty

OnKeyReleased

Tak

Klawisz zwolniony

OnMouseDragged

Tak

Przesunięcie myszy podczas wciśnięcia klawisza

OnMouseEntered

Tak

Mysz wewnątrz

OnMouseExited

Tak

Mysz na zewnątrz

OnMouseMoved

Tak

Przesunięcie myszy

OnMousePressed

Tak

Naciśnięto przycisk myszy

OnMouseReleased

Tak

Zwolniono przycisk myszy


Lista metod w usłudze Dialog

Activate
Center
Controls

EndExecute
Execute
GetTextsFromL10N

Resize
SetPageManager
Terminate


Activate

Ustaw fokus na bieżącą instancję Dialog. Zwróć True, jeśli ustawienie fokusu się powiodło.

Ta metoda jest wywoływana z okna dialogowego lub zdarzenia formantu lub gdy okno dialogowe jest wyświetlane w trybie niemodalnym.

Składnia:

svc.Activate(): bool

Przykład:


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

W przykładach Pythona i LibreOffice Basic założono, że okno dialogowe jest przechowywane w bibliotece Standard bieżącego dokumentu.


     dlg = CreateScriptService(,,'myDialog')
     dlg.Execute()
     # ...
     dlg.Activate()
   

Center

Wyśrodkowuje bieżącą instancję okna dialogowego na środku okna nadrzędnego. Bez argumentów metoda centruje okno dialogowe na środku bieżącego okna.

Zwraca True, gdy się powiedzie.

Składnia:

svc.Center(opt Parent: obj): bool

Parametry:

Parent: opcjonalny obiekt, który może być:

Przykład:

W języku Basic

     Sub TriggerEvent(oEvent As Object)
         Dim oDialog1 As Object, oDialog2 As Object, lExec As Long
         Set oDialog1 = CreateScriptService("DialogEvent", oEvent) ' Okno dialogowe, które spowodowało zdarzenie
         Set oDialog2 = CreateScriptService("Dialog", ...) ' Otwórz drugie okno dialogowe
         oDialog2.Center(oDialog1)
         lExec = oDialog2.Execute()
         Select Case lExec
             ...
     End Sub
  
W języku Python

     def triggerEvent(event: uno):
       dlg1 = CreateScriptService('DialogEvent.Dialog', event)  # Okno dialogowe, które spowodowało zdarzenie
       dlg2 = CreateScriptService('Dialog', ...)  # Otwórz drugie okno dialogowe
       dlg2.Center(dlg1)
       rc = dlg2.Execute()
       if rc is False:
         # ...
   

Controls

Zwróć:

Składnia:

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

svc.Controls(controlname: str): svc

Parametry:

ControlName: prawidłowa nazwa formantu jako ciąg uwzględniający wielkość liter. W przypadku braku lista nazw formantów jest zwracana jako tablica liczona od zera.

Przykład:


      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

Kończy wyświetlanie modalnego okna dialogowego i zwraca argument jako wartość zwracaną dla bieżącej uruchomionej akcji Execute().

EndExecute() jest zwykle zawarta w przetwarzaniu makra wyzwalanego przez okno dialogowe lub zdarzenie formantu.

Składnia:

svc.EndExecute(returnvalue: int)

Parametry:

returnvalue: wartość przekazana do działającej metody Execute().

Przykład:

Korzystanie z 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
   

Korzystanie z języka Python:


     from com.sun.star.lang import EventObject
     def on_event(event: EventObject):
         dlg = CreateScriptService("SFDialogs.DialogEvent", event)
         dlg.EndExecute(25)
   
tip

Powyższe wzmianki com.sun.star.lang.EventObject są opcjonalne. Takie adnotacje pomagają zidentyfikować interfejs programowania aplikacji (API) LibreOffice.


Execute

Wyświetl okno dialogowe i, jeśli jest modalne, poczekaj na jego zamknięcie przez użytkownika. Zwracana wartość to:

Dla niemodalnych okien dialogowych metoda zawsze zwraca 0, a wykonywanie makra jest kontynuowane.

Składnia:

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

Parametry:

modal: False w przypadku okna dialogowego niemodalnego. Wartość domyślna = True.

Przykład:

W tym przykładzie Basic okno dialogowe myDialog jest przechowywane w bibliotece Standard bieżącego dokumentu.


      Dim oDlg As Object, lReturn As Long
      Set oDlg = CreateScriptService("SFDialogs.Dialog", , , "myDialog")
      lReturn = oDlg.Execute(Modal := False)
      Select Case lReturn
          ' ...
      End Select
   

Ten kod Pythona wyświetla modalne okno dialogowe DlgConvert ze współdzielonej biblioteki Basic Euro.


     dlg = CreateScriptService("SFDialogs.Dialog", 'GlobalScope', 'Euro', "DlgConvert")
     rc = dlg.Execute()
     if rc == dlg.CANCELBUTTON:
         # ...
   

GetTextsFromL10N

Zastępuje wszystkie stałe ciągi tekstowe w oknie dialogowym ich przetłumaczonymi wersjami opartymi na instancji usługi L10N. Ta metoda tłumaczy następujące ciągi:

Metoda zwraca wartość True, jeśli operacja się powiedzie.

Aby utworzyć listę tłumaczonych ciągów znaków w oknie dialogowym, użyj metody AddTextsFromDialog z usługi L10N.

Składnia:

svc.GetTextsFromL10N(l10n: svc): bool

Parametry:

l10n: instancja usługi L10N, z której zostaną pobrane przetłumaczone ciągi znaków.

Przykład:

Poniższy przykład ładuje przetłumaczone ciągi i stosuje je do okna dialogowego „MyDialog”.

W języku Basic

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

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

Przeczytaj stronę pomocy usługi L10N, aby dowiedzieć się więcej o obsłudze plików PO i POT.


Resize

Przesuwa lewy górny róg okna dialogowego do nowych współrzędnych i/lub modyfikuje jego wymiary. Wszystkie odległości wyrażone są w 1/100 mm. Bez argumentów metoda resetuje wymiary początkowe. Zwraca True, jeśli zmiana rozmiaru się powiodła.

Składnia:

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

Parametry:

Left: pozioma odległość od lewego górnego rogu

Top: odległość w pionie od lewego górnego rogu

Width: szerokość prostokąta zawierającego okno dialogowe

Height: wysokość prostokąta zawierającego okno dialogowe

Argumenty negatywne lub brakujące pozostają niezmienione

Przykład:

W języku Basic

     oDialog.Resize(1000, 2000, Height := 6000) ' Szerokość nie ulega zmianie
   
W języku Python

Za pomocą języka Python:


     oDialog.Resize(1000, 2000, Height = 6000)  # Szerokość nie ulega zmianie
   

SetPageManager

Określa, które formanty okna dialogowego są używane do przełączania stron. Ułatwia to zarządzanie właściwością Page okna dialogowego i powiązanymi formantami.

Okna dialogowe mogą mieć wiele stron, a aktualnie widoczna strona jest definiowana przez właściwość okna dialogowego Page. Jeśli właściwość Page pozostanie niezmieniona, domyślna widoczna strona będzie równa 0 (zero), co oznacza, że nie jest zdefiniowana żadna konkretna strona i wyświetlane są wszystkie widoczne formanty niezależnie od wartości ustawionej w ich własnej właściwości Page.

Jeśli właściwość Page okna dialogowego zostanie zmieniona, na przykład na 1, 2, 3 itd., wyświetlane będą tylko te formanty, których właściwość Page odpowiada bieżącej stronie okna dialogowego.

Za pomocą metody SetPageManager można określić cztery typy elementów zarządzania stroną:

tip

Możliwe jest wykorzystanie więcej niż jednego mechanizmu zarządzania stroną jednocześnie.


Metodę tę należy wywołać tylko raz przed wywołaniem metody Execute. Kolejne wywołania są ignorowane.

Jeśli się powiedzie, ta metoda zwraca wartość True.

Składnia:

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

Parametry:

pilotcontrols: rozdzielona przecinkami lista nazw formantów ListBox, ComboBox lub RadioButton używanych jako menedżery stron. W przypadku formantów RadioButton określ nazwę pierwszego formantu w grupie, która ma zostać użyta.

tabcontrols: rozdzielona przecinkami lista nazw przycisków, które będą używane jako menedżery stron. Kolejność, w jakiej są one określone w tym argumencie, odpowiada numerowi strony, z którą są powiązane.

wizardcontrols: lista oddzielona przecinkami zawierająca nazwy dwóch przycisków, które będą używane jako przyciski Poprzednia/Następna.

lastpage: numer ostatniej dostępnej strony. Zaleca się określenie tej wartości w przypadku korzystania z menedżera stron Poprzednia/Następna.

Przykład:

Rozważmy okno dialogowe składające się z trzech stron. Okno dialogowe zawiera formant ListBox o nazwie „aPageList”, który będzie używany do kontrolowania widocznej strony. Dodatkowo istnieją dwa przyciski o nazwach „btnPrevious” i „btnNext”, które będą używane jako przyciski Poprzednia/Następna w oknie dialogowym.

W języku Basic

    oDialog.SetPageManager(PilotControls := "aPageList", _
                           WizardControls := "btnPrevious,btnNext", _
                           LastPage := 3)
    oDialog.Execute()
  
W języku Python

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

Terminate

Zakończ usługę Dialog dla bieżącej instancji. Zwróć True, jeśli zakończenie się powiodło.

Składnia:

svc.Terminate(): bool

Przykład:

Poniżej przykładów języków Basic i Python otwierają się niemodalne okna dialogowe DlgConsole i dlgTrace. Są one odpowiednio przechowywane w bibliotekach współdzielonych ScriptForge i Access2Base. Przyciski zamykania okna dialogowego są wyłączone, a na końcu uruchomionego procesu wykonywane jest jawne zakończenie.

W tym przykładzie przycisk w DlgConsole zastępuje wstrzymane zamykanie okna:

W języku Basic

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

Za pomocą języka Python:

W języku Python

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

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.


Prosimy o wsparcie!