Servizio SFDialogs.Dialog

Il servizio Dialog contribuisce alla gestione delle finestre di dialogo create con l'Editor delle finestre di Basic. Ogni istanza della classe corrente rappresenta una singola finestra di dialogo visualizzata all'utente.

tip

Una finestra di dialogo può essere visualizzata in modalità modale o non modale.


In modalità modale, la finestra viene visualizzata e l'esecuzione del processo della macro è sospeso fino a che non viene premuto uno dei pulsanti OK o Annulla. Nel frattempo, le azioni eseguite dall'utente nella finestra possono richiamare specifiche azioni.

In modalità non modale, la finestra di dialogo è "mobile" sul desktop dell'utente e l'esecuzione del processo della macro continua normalmente. Una finestra non modale si chiude quanto viene terminata con il metodo Terminate() o con la conclusione della sessione di LibreOffice. Nelle finestre non modali, il pulsante di chiusura della finestra è inattivo.

Una finestra di dialogo scompare dalla memoria dopo la sua esplicita terminazione.

tip

Il servizio SFDialogs.Dialog è strettamente collegato al servizio SFDialogs.DialogControl.


Invocazione e utilizzo del servizio

Prima di usare il servizio Dialog è necessario caricare o importare le librerie ScriptForge:

note

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService


Il servizio Dialog è invocato tramite il metodo CreateScriptService. Richiede tre argomenti posizionali per specificare la finestra di dialogo da attivare:

Container: "GlobalScope" per le librerie preinstallare o un nome di finestra come definito dal servizio ScriptForge.UI. Una stringa vuota "", che è il valore predefinito, indica il documento corrente.

Library: Il nome, sensibile alla differenza tra maiuscole e minuscole, di una libreria contenuta nel container. Il valore predefinito è "Standard".

DialogName: Una stringa, sensibile alla differenza tra maiuscole e minuscole, che determina la finestra.

The examples below in Basic and Python display the dlgConsole dialog that belongs to the ScriptForge shared library:


      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")
      '... in questo punto va inserita l'inizializzazione dei controlli...
      lButton = oDlg.Execute()
      'Modalità predefinita = Modal
      If lButton = oDlg.OKBUTTON Then
      '...In questo punto vanno inserite l'elaborazione dei controlli e l'esecuzione di quanto necessario
      End If
      oDlg.Terminate()
  

O usando Python:


    dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')
    #... in questo punto va inserita l'inizializzazione dei controlli...
    rc = dlg.Execute()
    # La modalità predefinita è Modal
    if rc == dlg.OKBUTTON:
        # ...In questo punto vanno inserite l'elaborazione dei controlli e l'esecuzione di quanto necessario
    dlg.Terminate()
  
note

Use the string "GlobalScope" as the container argument when the dialog is stored either in My Macros & Dialogs or in Application Macros & Dialogs.


Retrieving the Dialog instance that triggered a dialog event

An instance of the Dialog service can be retrieved via the SFDialogs.DialogEvent service, provided that the dialog was initiated with the Dialog service. In the example below, oDlg contains the Dialog instance that triggered the dialog event.


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

Or using Python:


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

Note that in the previous examples, the prefix "SFDialogs." may be omitted when deemed appropriate.

Handling exceptions in event handlers

When creating an event handler for dialog events it is good practice to handle errors inside the subroutine itself. For instance, suppose the event handler below is called when the mouse button is pressed in the dialog window.


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

Call SF_Exception.Clear if you do not want the error to propagate after the dialog execution ended.


In Python use native try/except blocks for exception handling as shown below:


    def on_mouse_button_pressed(event=None):
        try:
            dlg = CreateScriptService("DialogEvent", event)
            # Process the event
        except Exception as e:
            # The object "bas" is an instance of the Basic service
            bas.MsgBox(str(e))
  

Proprietà

Nome

Sola lettura

Tipo

Descrizione

OKBUTTON

Integer

Value = 1. È stato premuto un pulsante OK.

CANCELBUTTON

Integer

Value = 0. È stato premuto un pulsante Annulla.

Caption

No

String

Specifica il titolo della finestra di dialogo.

Height

No

Long

Specifica l'altezza della finestra di dialogo.

Modal

Boolean

Specifica se la finestra di dialogo è attualmente in esecuzione in modalità modale.

Name

String

Il nome della finestra di dialogo

Page

No

Integer

Una finestra di dialogo può contenere diverse pagine che possono essere sfogliate dall'utente passo passo. La proprietà Page dell'oggetto Dialog definisce quale pagina dell'oggetto è attiva.

Visible

No

Boolean

Specifica se la finestra di dialogo è visibile sul desktop. Per impostazione predefinita non è visibile fino a quando non è eseguito il metodo Execute(), da quel momento in poi diventa visibile.

XDialogModel

UNO
object

L'oggetto UNO che rappresenta il modello di finestra di dialog. Per informazioni dettagliate, fate riferimento a XControlModel e UnoControlDialogModel nella documentazione delle Application Programming Interface (API).

XDialogView

UNO
object

L'oggetto UNO che rappresenta la vista della finestra di dialogo. Per informazioni più dettagliate fate riferimento a XControl e UnoControlDialog nella documentazione delle Application Programming Interface (API).

Width

No

Long

Specifica la larghezza della finestra di dialogo.


Proprietà dell'evento

Restituisce una stringa URI con il riferimento allo script attivato dall'evento. Leggete la relativa specifica nella specifica URI del framework di scripting (in inglese).

Nome

Sola lettura

Descrizione della IDE di Basic

OnFocusGained

Al ricevimento del fuoco

OnFocusLost

Alla perdita del fuoco

OnKeyPressed

Tasto premuto

OnKeyReleased

Tasto rilasciato

OnMouseDragged

Spostamento del mouse con pulsante premuto

OnMouseEntered

Mouse dentro

OnMouseExited

Mouse fuori

OnMouseMoved

Movimento del mouse

OnMousePressed

Pulsante del mouse premuto

OnMouseReleased

Pulsante del mouse rilasciato


Metodi

Activate
Center
Controls

EndExecute
Execute
GetTextsFromL10N

Resize
SetPageManager
Terminate


Activate

Imposta il fuoco sull'istanza corrente di Dialog. Restituisce True se la messa a fuoco è riuscita.

Questo metodo è chiamato da un evento di una finestra o di un controllo, o quando una finestra di dialogo è visualizzata in modalità non modale.

Sintassi:

svc.Activate(): bool

Esempio:


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

Gli esempi in Python e LibreOffice Basic presumono che la finestra di dialogo sia memorizzata nella libreria Standard del documento corrente.


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

Center

Centra l'istanza corrente della finestra di dialogo nel mezzo di una finestra genitore. Senza argomenti, il metodo centra la finestra di dialogo nel mezzo della finestra corrente.

Il metodo restituisce True se eseguito correttamente.

Sintassi:

svc.Center(opt Parent: obj): bool

Parametri:

Parent: un oggetto opzionale che può essere uno tra:

Esempio:

In Basic

     Sub TriggerEvent(oEvent As Object)
         Dim oDialog1 As Object, oDialog2 As Object, lExec As Long
         Set oDialog1 = CreateScriptService("DialogEvent", oEvent) ' la finestra di dialogo che ha attivato l'evento
         Set oDialog2 = CreateScriptService("Dialog", ...) ' Apre una seconda finestra di dialogo
         oDialog2.Center(oDialog1)
         lExec = oDialog2.Execute()
         Select Case lExec
             ...
     End Sub
  
In Python

     def triggerEvent(event: uno):
       dlg1 = CreateScriptService('DialogEvent.Dialog', event) # La finestra di dialogo che ha attivato l'evento
       dlg2 = CreateScriptService('Dialog', ...) # Apre una seconda finestra di dialogo
       dlg2.Center(dlg1)
       rc = dlg2.Execute()
       if rc is False:
         # ...
   

Controls

Eseguite uno tra:

Sintassi:

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

svc.Controls(controlname: str): svc

Parametri:

ControlName : Un nome valido di un controllo, in formato stringa sensibile alla differenza tra maiuscole e minuscole. Se assente, viene restituito l'elenco dei nomi dei controlli in formato di matrice con indice a partire da zero.

Esempio:


      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

Termina la visualizzazione di una finestra modale e fornisce l'argomento come valore di ritorno per l'azione Execute() in esecuzione in quel momento.

EndExecute() di solito è contenuto nel processo di una macro attivata da un evento di una finestra di dialogo o di un controllo.

Sintassi:

svc.EndExecute(returnvalue: int)

Parametri:

returnvalue: Il valore passato al metodo Execute() in esecuzione.

Esempio:

Usando 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
   

Usando Python:


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

Le menzioni a com.sun.star.lang.EventObject riportate sopra sono opzionali. Tali annotazioni consentono di identificare le Application Programming Interface (API) di LibreOffice.


Execute

Visualizza la finestra di dialogo e, se modale, attende la sua chiusura da parte dell'utente. Il valore restituito è uno tra:

Per le finestre di dialogo non modali il metodo restituisce sempre 0 e l'esecuzione della macro continua.

Sintassi:

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

Parametri:

modal: False se la finestra di dialogo non è modale. Predefinito = True.

Esempio:

In questo esempio in Basic la finestra di dialogo myDialog è memorizzata nella libreria Standard del documento corrente.


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

Questo codice in Python visualizza la finestra di dialogo modale DlgConvert della libreria Euro condivisa con Basic.


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

GetTextsFromL10N

Sostituisce tutti i testi fissi di una finestra di dialogo con la loro versione tradotta basata sull'istanza del servizio L10N. Questo metodo traduce le seguenti stringhe:

Il metodo restituisce True, se eseguito correttamente.

Per creare un elenco delle stringhe traducibili della finestra di dialogo usate il metodo AddTextsFromDialog del servizio L10N.

Sintassi:

svc.GetTextsFromL10N(l10n: svc): bool

Parametri:

l10n: un'istanza del servizio L10N dalla quale saranno recuperate le stringhe tradotte.

Esempio:

L'esempio seguente carica le stringhe tradotte e le applica alla finestra di dialogo "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()
   
tip

Per approfondire l'argomento sulla gestione dei file PO e POT, consultare la pagina servizio L10N della guida.


Resize

Sposta l'angolo superiore sinistro della finestra di dialogo alle nuove coordinate e/o modifica le sue dimensioni. Tutte le distanze sono espresse in 1/100 di mm. Senza argomenti il metodo reimposta le dimensioni iniziali. Restituisce True se il ridimensionamento è stato eseguito correttamente.

Sintassi:

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

Parametri:

Left: la distanza orizzontale dall'angolo superiore sinistro

Top: la distanza verticale dall'angolo superiore sinistro

Width: la larghezza del rettangolo che contiene la finestra di dialogo

Height: l'altezza del rettangolo che contiene la finestra di dialogo

Gli argomenti con valori negativi od omessi sono lasciati immutati

Esempio:

In Basic

     oDialog.Resize(1000, 2000, Height := 6000) ' La larghezza non viene modificata
   
In Python

Con Python:


     oDialog.Resize(1000, 2000, Height = 6000) # La larghezza non viene modificata
   

SetPageManager

Defines which controls in a dialog are responsible for switching pages, making it easier to manage the Page property of a dialog and its controls.

Dialogs may have multiple pages and the currently visible page is defined by the Page dialog property. If the Page property is left unchanged, the default visible page is equal to 0 (zero), meaning that no particular page is defined and all visible controls are displayed regardless of the value set in their own Page property.

When the Page property of a dialog is changed to some other value such as 1, 2, 3 and so forth, then only the controls whose Page property match the current dialog page will be displayed.

By using the SetPageManager method it is possible to define four types of page managers:

tip

It is possible to use more than one page management mechanism at the same time.


This method is supposed to be called just once before calling the Execute method. Subsequent calls are ignored.

If successful this method returns True.

Sintassi:

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

Parametri:

pilotcontrols: a comma-separated list of ListBox, ComboBox or RadioButton control names used as page managers. For RadioButton controls, specify the name of the first control in the group to be used.

tabcontrols: a comma-separated list of button names that will be used as page managers. The order in which they are specified in this argument corresponds to the page number they are associated with.

wizardcontrols: a comma-separated list with the names of two buttons that will be used as the Previous/Next buttons.

lastpage: the number of the last available page. It is recommended to specify this value when using the Previous/Next page manager.

Esempio:

Consider a dialog with three pages. The dialog has a ListBox control named "aPageList" that will be used to control the visible page. Additionally, there are two buttons named "btnPrevious" and "btnNext" that will be used as the Previous/Next buttons in the dialog.

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

Termina il servizio Dialog per l'istanza corrente. Restituisce True se la terminazione è riuscita.

Sintassi:

svc.Terminate(): bool

Esempio:

I seguenti esempi in Basic e Python aprono le finestre di dialogo non modali DlgConsole e dlgTrace. Queste sono memorizzate rispettivamente nelle librerie condivise ScriptForge e Access2Base. I pulsanti di chiusura delle finestre sono disabilitati e viene eseguita una terminazione esplicita alla fine di un processo in esecuzione.

In questo esempio un pulsante in DlgConsole sostituisce la chiusura della finestra che è inibita:

In Basic

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

Con Python:

In Python

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

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.