Contenuto
Indice 🔎︎

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

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.

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

## Invocazione e utilizzo del servizio

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.

I seguenti esempi in Basic e Python in LibreOffice visualizzano la finestra dlgConsole che appartiene alla libreria condivisa 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")
          '... 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()

In alternativa un'istanza di Dialog può essere richiamata tramite il servizio SFDialogs.DialogEvent, purchè la finestra di dialogo sia inizializzata con il servizio Dialog. DialogEvent restituisce l'istanza al servizio SFDialogs.Dialog che attiva l'evento.

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

con Python:

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

Tenete presente che negli esempi precedenti il prefisso "SFDialogs." può essere omesso se ritenuto appropriato.

## Proprietà

Nome | Sola lettura | Tipo | Descrizione
OKBUTTON | Sì | Integer | Value = 1. È stato premuto un pulsante OK.
CANCELBUTTON | Sì | 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 | Sì | Boolean | Specifica se la finestra di dialogo è attualmente in esecuzione in modalità modale.
Name | Sì | 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 | Sì | 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 | Sì | 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

Queste proprietà degli eventi sono disponibili in LibreOffice dalla versione 7.2 in poi.

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

Nome | Sola lettura | Descrizione della IDE di Basic
OnFocusGained | Sì | Al ricevimento del fuoco
OnFocusLost | Sì | Alla perdita del fuoco
OnKeyPressed | Sì | Tasto premuto
OnKeyReleased | Sì | Tasto rilasciato
OnMouseDragged | Sì | Spostamento del mouse con pulsante premuto
OnMouseEntered | Sì | Mouse dentro
OnMouseExited | Sì | Mouse fuori
OnMouseMoved | Sì | Movimento del mouse
OnMousePressed | Sì | Pulsante del mouse premuto
OnMouseReleased | Sì | Pulsante del mouse rilasciato

| Metodi |
Activate Controls | EndExecute Execute | 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()

## Controls

Eseguite uno tra:

- l'elenco dei controlli contenuto nella finestra di dialogo

- un'istanza della classe DialogControl in base al suo nome

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

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:

- 0 : è stato premuto il pulsante Annulla

- 1: è stato premuto il pulsante OK

- Altrimenti la finestra è stata chiusa da un'istruzione EndExecute() attivata da un evento di una finestra o di un controllo

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

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

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

Con Python:

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

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.

Argomenti correlati

Servizio SFDialogs.DialogControl

Servizio ScriptForge.UI