SFDialogs.Dialog service

Inhoud
Index 🔎︎

# SFDialogs.Dialog-service

De service Dialog draagt bij aan het beheer van dialoogvensters die zijn gemaakt met de Basic Dialog Editor. Elk exemplaar van de huidige klasse vertegenwoordigt een enkel dialoogvenster dat aan de gebruiker wordt weergegeven.

Een dialoogvenster kan worden weergegeven in modale of in niet-modale modi.

In de modale modus wordt het vak weergegeven en wordt de uitvoering van het macroproces opgeschort, totdat op een van de knoppen OK of Annuleren wordt gedrukt. In de tussentijd kunnen gebruikersacties die op de box worden uitgevoerd, specifieke acties activeren.

In niet-modale modus "zweeft" het dialoogvenster op het bureaublad van de gebruiker en de uitvoering van het macroproces gaat normaal door. Een niet-modaal dialoogvenster wordt gesloten wanneer het wordt beëindigd met de methode Terminate() of wanneer de LibreOffice-sessie eindigt. De knop voor het sluiten van het venster is inactief in niet-modale dialoogvensters.

Een dialoogvenster verdwijnt uit het geheugen nadat het expliciet is beëindigd.

De service SFDialogs.Dialog is nauw verwant aan de service SFDialogs.DialogControl.

## Service aanroep en gebruik

Voordat de service Dialog gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

De service Dialog wordt aangeroepen door de methode CreateScriptService. Er zijn drie positionele argumenten om het dialoogvenster aan te geven dat geactiveerd moet worden:

Container: "GlobalScope" voor voorgeïnstalleerde bibliotheken of een vensternaam zoals gedefinieerd met de service ScriptForge.UI. De standaardwaarde, een lege tekenreeks, staat voor het huidige document.

Library: De hoofdlettergevoelige naam van een bibliotheek in de container. Standaardwaarde is "Standard".

DialogName: Een hoofdlettergevoelige tekenreeks die de dialoog aangeeft.

De onderstaande voorbeelden in Basic en Python tonen het dialoogvenster dlgConsole dat behoort tot de gedeelde bibliotheek 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")
          '... hier staat wat initialisatie...
          lButton = oDlg.Execute()
          'Standaardmodus is Modal
          If lButton = oDlg.OKBUTTON Then
          '... Procescontrole
          End If
          oDlg.Terminate()

Of met Python:

        dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')
        #... hier staat wat initialisatie...
        rc = dlg.Execute()
        # Standaardmodus is Modal
        if rc == dlg.OKBUTTON:
            # ... Procescontrole
        dlg.Terminate()

Gebruik de tekenreeks "GlobalScope" als het argument container wanneer het dialoogvenster is opgeslagen in Mijn macro's en dialoogvensters of in Toepassingsmacro's en dialoogvensters.

## De Dialog-instantie ophalen die een dialooggebeurtenis heeft geactiveerd

Een exemplaar van de Dialog-service kan worden opgehaald via de SFDialogs.DialogEvent-service, op voorwaarde dat de dialoog is gestart met de Dialog-service. In het onderstaande voorbeeld bevat oDlg de instantie Dialog die de dialooggebeurtenis heeft geactiveerd.

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

Of Python gebruiken:

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

Merk op dat in de voorgaande voorbeelden het voorvoegsel "SFDialogs." kan worden weggelaten wanneer dit passend wordt geacht.

## Uitzonderingen in gebeurtenishandlers afhandelen

Bij het maken van een gebeurtenishandler voor dialooggebeurtenissen is het een goede gewoonte om fouten binnen de subroutine zelf af te handelen. Stel bijvoorbeeld dat onderstaande gebeurtenishandler wordt aangeroepen wanneer de muisknop wordt ingedrukt in het dialoogvenster.

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

SF_Exception.Clear aanroepen als u niet wilt dat de fout zich voortplant, nadat de uitvoering van het dialoogvenster is beëindigd.

Gebruik in Python native try/except-blokken voor het afhandelen van uitzonderingen, zoals hieronder getoond:

        def on_mouse_button_pressed(event=None):
            try:
                dlg = CreateScriptService("DialogEvent", event)
                # De gebeurtenis verwerken
            except Exception as e:
                # Het object "bas" is een instantie van de Basic-service
                bas.MsgBox(str(e))

## Eigenschappen

Naam | AlleenLezen | Type | Beschrijving
--- | --- | --- | ---
OKBUTTON | Ja | Integer | Value = 1. Er is op de knop OK gedrukt.
CANCELBUTTON | Ja | Integer | Value = 0. A Er is op de knop Annuleren gedrukt.
Caption | Nee | String | Geef de titel van het dialoogvenster op.
Height | Nee | Long | Geef de hoogte van het dialoogvenster op.
Modal | Ja | Boolean | Geeft aan of het dialoogvenster momenteel wordt uitgevoerd in de modale modus.
Name | Ja | String | De naam van het dialoogvenster
Page | Nee | Integer | Een dialoogvenster kan meerdere pagina's hebben die stap voor stap door de gebruiker kunnen worden doorlopen. De eigenschap Page van het Dialog-object definieert welke pagina van het dialoogvenster actief is.
Visible | Nee | Boolean | Geef op of het dialoogvenster zichtbaar is op het bureaublad. Standaard is het niet zichtbaar totdat de methode Execute() wordt uitgevoerd en daarna zichtbaar.
XDialogModel | Ja | UNO object | Het UNO-object dat het dialoogmodel vertegenwoordigt. Raadpleeg XControlModel en UnoControlDialogModel in de Application Programming Interface (API)-documentatie voor gedetailleerde informatie.
XDialogView | Ja | UNO object | Het UNO-object dat de dialoogweergave vertegenwoordigt. Raadpleeg XControl en UnoControlDialog in de Application Programming Interface (API)-documentatie voor gedetailleerde informatie.
Width | Nee | Long | Geef de breedte van het dialoogvenster op.

## Eigenschappen gebeurtenis

Retourneert een URI-tekenreeks met de verwijzing naar het script dat door de gebeurtenis is geactiveerd. Lees de specificatie ervan in de scripting framework URI-specificatie.

Naam | AlleenLezen | Basic IDE-beschrijving
--- | --- | ---
OnFocusGained | Ja | Bij het verkrijgen van focus
OnFocusLost | Ja | Bij verlies van focus
OnKeyPressed | Ja | Toets ingedrukt
OnKeyReleased | Ja | Toets losgelaten
OnMouseDragged | Ja | Muis bewoog tijdens toetsaanslagen
OnMouseEntered | Ja | Muis binnen
OnMouseExited | Ja | Muis buiten
OnMouseMoved | Ja | Muisbeweging
OnMousePressed | Ja | Muisknop ingedrukt
OnMouseReleased | Ja | Muisknop losgelaten

Lijst met methoden in de Dialog Service
Activate Center Controls | EndExecute Execute GetTextsFromL10N | Resize SetPageManager Terminate

## Activate

Stel de focus in op de huidige Dialog instantie. Retourneer True als het scherpstellen gelukt is.

Deze methode wordt aangeroepen vanuit een dialoog of besturingsgebeurtenis, of wanneer een dialoog wordt weergegeven in niet-modale modus.

### Syntaxis:

svc.Activate(): bool

### Voorbeeld:

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

Python en LibreOffice Basicvoorbeelden gaan er beide van uit dat het dialoogvenster is opgeslagen in de bibliotheek Standard van het huidige document.

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

## Center

Centreert de huidige dialooginstantie in het midden van een bovenliggend venster. Zonder argumenten centreert de methode het dialoogvenster in het midden van het huidige venster.

Retourneert True bij succes.

### Syntaxis:

svc.Center(opt Parent: obj): bool

### Parameters:

Parent: Een optioneel object …

- een ScriptForge-dialoogobject

- een document (Calc, Base, …) "ScriptForge"

### Voorbeeld:

##### In BASIC

         Sub TriggerEvent(oEvent As Object)
             Dim oDialog1 As Object, oDialog2 As Object, lExec As Long
             Set oDialog1 = CreateScriptService("DialogEvent", oEvent) ' Het dialoogvenster dat de gebeurtenis heeft veroorzaakt
             Set oDialog2 = CreateScriptService("Dialog", ...) ' Open een tweede dialoogvenster
             oDialog2.Center(oDialog1)
             lExec = oDialog2.Execute()
             Select Case lExec
                 ...
         End Sub

##### In Python

         def triggerEvent(event: uno):
           dlg1 = CreateScriptService('DialogEvent.Dialog', event) # Het dialoogvenster dat de gebeurtenis heeft veroorzaakt
           dlg2 = CreateScriptService('Dialog', ...)  # Een tweede dialoogvenster openen
           dlg2.Center(dlg1)
           rc = dlg2.Execute()
           if rc is False:
             # ...

## Controls

Teruggave:

- de lijst met bedieningselementen in het dialoogvenster

- a DialogControl klasse-instantie op basis van zijn naam

### Syntaxis:

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

svc.Controls(controlname: str): svc

### Parameters:

ControlName : Een geldige besturingselementnaam als hoofdlettergevoelige tekenreeks. Indien afwezig, wordt de lijst met besturingselementnamen geretourneerd als een op nul gebaseerde matrix.

### Voorbeeld:

          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

Beëindigt de weergave van een modaal dialoogvenster en geeft het argument terug als retourwaarde voor de huidige Execute() actieve actie.

EndExecute() is meestal vervat in de verwerking van een macro die wordt geactiveerd door een dialoogvenster of besturingsgebeurtenis.

### Syntaxis:

svc.EndExecute(returnvalue: int)

### Parameters:

returnvalue: De waarde die is doorgegeven aan de actieve methode Execute().

### Voorbeeld:

LibreOffice Basic gebruiken:

          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

Python gebruiken:

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

Bovenstaande com.sun.star.lang.EventObject-vermeldingen zijn optioneel. Dergelijke annotaties helpen bij het identificeren van LibreOffice Application Programming Interface (API).

## Execute

Geef het dialoogvenster weer en wacht, indien modaal, op beëindiging door de gebruiker. De geretourneerde waarde is ofwel:

- 0 : Cancel knop ingedrukt

- 1 : OK knop ingedrukt

- Anders stopte het dialoogvenster met een EndExecute()-instructie uitgegeven door een dialoogvenster of controlegebeurtenis

Voor niet-modale dialoogvensters retourneert de methode altijd 0 en gaat de uitvoering van de macro door.

### Syntaxis:

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

### Parameters:

modal: False bij niet-modale dialoogvenster. Standaard = True.

### Voorbeeld:

In dit basisvoorbeeld wordt het dialoogvenster myDialog opgeslagen in de bibliotheek Standard van het huidige document.

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

Deze Python-code geeft het modale dialoogvenster DlgConvert weer uit de gedeelde Basic bibliotheek Euro.

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

## GetTextsFromL10N

Vervangt alle vaste tekstreeksen in een dialoogvenster door hun vertaalde versies op basis van een service-instantie L10N. Deze methode vertaalt de volgende strings:

- De naam van de dialoog.

- De 'caption' van de gebruikte elementen: Button, CheckBox, FixedLine, FixedText, GroupBox en RadioButton.

- Statische teksten in ListBoxes en ComboBoxes.

- Helpteksten en teksten die gebruikt worden als de gebruiker met de muis over een veld heengaat.

De methode retourneert True indien succesvol.

Gebruik de AddTextsFromDialog methode van de service L10N om een lijst met vertaalbare tekenreeksen in een dialoogvenster te maken.

### Syntaxis:

svc.GetTextsFromL10N(l10n: svc): bool

### Parameters:

l10n: Een service-instantie L10N waaruit vertaalde tekenreeksen worden opgehaald.

### Voorbeeld:

Het volgende voorbeeld laadt vertaalde tekenreeksen en past ze toe op het dialoogvenster "MyDialog".

##### In BASIC

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

##### In Python

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

Lees de L10N-service-helppagina voor meer informatie over hoe PO- en POT-bestanden worden verwerkt.

## Resize

Verplaatst de linkerbovenhoek van een dialoogvenster naar nieuwe coördinaten en/of wijzigt de afmetingen ervan. Alle afstanden zijn uitgedrukt in 1/100 mm. Zonder argumenten stelt de methode de initiële dimensies opnieuw in. Retourneert True als het wijzigen van de grootte is gelukt.

### Syntaxis:

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

### Parameters:

Left: de horizontale afstand vanaf de linkerbovenhoek

Top: de verticale afstand vanaf de linkerbovenhoek

Width: de breedte van de rechthoek die het dialoogvenster bevat

Height: de hoogte van de rechthoek die het dialoogvenster bevat

Negatieve of ontbrekende argumenten blijven ongewijzigd

### Voorbeeld:

##### In BASIC

         oDialog.Resize(1000, 2000, Height := 6000) ' Breedte is niet gewijzigd

##### In Python

Met Python:

         oDialog.Resize(1000, 2000, Height = 6000)  # Breedte is niet gewijzigd

## SetPageManager

Definieert welke besturingselementen in een dialoogvenster verantwoordelijk zijn voor het schakelen tussen pagina's, waardoor het eenvoudiger wordt om de eigenschap Pagina van een dialoogvenster en de bijbehorende besturingselementen te beheren.

Dialoogvensters kunnen meerdere tabbladen hebben en het momenteel zichtbare tabblad wordt gedefinieerd door de Pagina dialoogeigenschap. Als de eigenschap Page ongewijzigd blijft, is het standaard zichtbare tabblad gelijk aan 0 (nul), wat betekent dat er geen specifiek tabblad is gedefinieerd en dat alle zichtbare bedieningselementen worden weergegeven, ongeacht de waarde die is ingesteld in hun eigen eigenschap Page.

Wanneer de eigenschap Page van een dialoogvenster wordt gewijzigd in een andere waarde, zoals 1, 2, 3 enzovoort, dan worden alleen de besturingselementen weergegeven waarvan de eigenschap Page overeenkomt met de huidige dialoogvensterpagina zullen worden tentoongesteld.

Door gebruik te maken van de methode SetPageManager is het mogelijk om vier typen paginabeheerders te definiëren:

- List box or combo box:in dit geval komt elk item in de keuzelijst of keuzelijst met invoervak overeen met een tabblad. Het eerste item verwijst naar tabblad 1, het tweede item verwijst naar tabblad 2 enzovoort.

- Group of radio buttons: definieert een groep keuzerondjes die bepalen welk tabblad zichtbaar is.

- Volgorde van knoppen: definieert een set knoppen, die elk overeenkomen met een dialoogpagina. Dit kan worden gebruikt om een interface met tabbladen te emuleren door knoppen naast elkaar in het dialoogvenster te plaatsen.

- Previous/Next buttons: definieert welke knoppen in het dialoogvenster worden gebruikt om naar het vorige/volgende tabblad in het dialoogvenster te navigeren.

Het is mogelijk om meer dan één tabbladbeheermechanisme tegelijkertijd te gebruiken.

Het is de bedoeling dat deze methode slechts één keer wordt aangeroepen voordat de methode Execute wordt aangeroepen. Latere oproepen worden genegeerd.

Indien succesvol retourneert deze methode True.

### Syntaxis:

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

### Parameters:

pilotcontrols: een door komma's gescheiden lijst van ListBox-, ComboBox- of RadioButton-besturingselementen die worden gebruikt als tabbladbeheerders. Geef voor RadioButton-besturingselementen de naam op van het eerste besturingselement in de te gebruiken groep.

tabcontrols: een door komma's gescheiden lijst met knopnamen die zullen worden gebruikt als tabbladbeheerders. De volgorde waarin ze in dit argument worden opgegeven, komt overeen met het bladnummer waaraan ze zijn gekoppeld.

wizardcontrols: een door komma's gescheiden lijst met de namen van twee knoppen die zullen worden gebruikt als de knoppen Vorige/Volgende.

lastpage: het nummer van het laatst beschikbare tabblad. Het wordt aanbevolen om deze waarde op te geven bij gebruik van Vorige/Volgende tabbladbeheer.

### Voorbeeld:

Neem een dialoog met drie tabbladen. Het dialoogvenster heeft een ListBox-besturingselement met de naam "aPageList" dat zal worden gebruikt om het zichtbare tabblad te beheren. Daarnaast zijn er twee knoppen genaamd "btnPrevious" en "btnNext" die zullen worden gebruikt als de Vorige/Volgende knoppen in het dialoogvenster.

##### In BASIC

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

##### In Python

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

## Terminate

Beëindig de service Dialog voor de huidige instantie. Retourneert True als de beëindiging is gelukt.

### Syntaxis:

svc.Terminate(): bool

### Voorbeeld:

Onderstaande basis- en Python-voorbeelden openen de niet-modale dialoogvensters DlgConsole en dlgTrace. Ze worden respectievelijk opgeslagen in ScriptForge en Access2Base gedeelde bibliotheken. Dialoogvenster sluitknoppen zijn uitgeschakeld en expliciete beëindiging wordt uitgevoerd aan het einde van een lopend proces.

In dit voorbeeld vervangt een knop in DlgConsole de geblokkeerde venstersluiting:

##### In BASIC

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

Met Python:

##### In Python

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

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Verwante onderwerpen

service SFDialogs.DialogControl

Service ScriptForge.UI