Contenuto

# Servizio SFDialogs.Dialog

Il servizio Dialog contribuisce alla gestione delle finestre di dialogo create con l'Editor delle finestre di Basic o di quelle create al volo. 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

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

• 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 supplementari 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 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()

Usare la stringa "GlobalScope" come argomento container se la finestra di dialogo è memorizzata in Macro e finestre di dialogo personali o in Macro e finestre di dialogo dell'applicazione.

Il servizio per le finestre di dialogo offre metodi per creare dinamicamente nuovi controlli in una finestra di dialogo preimpostata con l'Editor delle finestre di dialogo. Una finestra di dialogo viene inizializzata con i controlli all'interno dell'Editor delle finestre di dialogo ed è possibile aggiungere nuovi controlli in fase di esecuzione, prima o dopo dell'istruzione Execute() della finestra di dialogo.

Il servizio Dialog può essere invocato, tramite il metodo CreateScriptService, anche quando si creano delle finestre al volo. In questo caso richiede due argomenti posizionali supplementari dopo il nome del servizio ad-hoc "NuovaFinestra":

DialogName: una stringa, che distingue tra maiuscole e minuscole, che determina la finestra.

Place: la posizione della finestra di dialogo che può essere:

- una matrice di Basic o una tupla di Python con 4 elementi: (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

        Sub newDialog()
            Dim oDlg As Object
           oDlg = CreateScriptService("NewDialog", "myDialog1", Array(100,200, 40, 110))
           ' ...
        End Sub

O usando Python:

        def newDialog():
           dlg = CreateScriptService('NuovaFinestra', 'miaFinestra1', (100,200, 40, 110))
           # ... Controlli del processo ed esecuzione di quanto necessario

Tutte le proprietà e i metodi applicabili alle finestre di dialogo predefinite sono disponibili per queste nuove finestre. In particolare la serie di metodi CreateXXX() per l'aggiunta di nuovi controlli alla finestra di dialogo.

## Ricerca dell'istanza di Dialog che ha attivato un evento relativo alla finestra di dialogo

Un'istanza del servizio Dialog può essere trovata attraverso il servizio SFDialogs.DialogEvent, purché la finestra di dialogo sia stata inizializzata con il servizio Dialog. Nell'esempio seguente, oDlg contiene l'istanza di Dialog che ha attivato l'evento nella finestra di dialogo.

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

O usando Python:

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

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

### Gestione delle eccezioni con i gestori degli eventi

Quando si crea un gestore degli eventi per la finestra di dialogo è buona pratica gestire gli errori all'interno della subroutine stessa. Per esempio, si ipotizzi che il seguente gestore degli eventi sia chiamato quando viene premuto il pulsante del mouse in una finestra di dialogo.

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

Chiamare SF_Exception.Clear se non si desidera che l'errore si propaghi dopo che l'esecuzione della finestra di dialogo è terminata.

In Python usare i blocchi nativi try/except per gestire le eccezioni, come mostrato qui di seguito:

        def on_mouse_button_pressed(event=None):
            try:
                dlg = CreateScriptService("DialogEvent", event)
                # Elabora l'evento
            except Exception as e:
                # L'oggetto "bas" è un'istanza del servizio Basic
                bas.MsgBox(str(e))

## 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ì | Oggetto UNO | 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ì | Oggetto UNO | 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

Le proprietà On… degli eventi sono delle stringhe URI che fanno riferimento allo script attivato da un evento. Leggere le sue specifiche nelle specifiche URI per il framework del linguaggio di scripting.

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

Suggerimento: tutte le proprietà On… possono essere impostate tramite programmazione.
Un esempio dimostrativo si trova in Come mostrare i dati in un controllo ad albero sul Wiki di LibreOffice.

L'assegnazione degli eventi per mezzo dell'IDE di Basic o la loro assegnazione tramite macro si escludono vicendevolmente.

Elenco dei metodi del servizio Dialog

Activate
Center
Controls
CloneControl
CreateButton
CreateCheckBox
CreateComboBox
CreateCurrencyField
CreateDateField
CreateFileControl
CreateFixedLine
CreateFixedText

CreateFormattedField
CreateGroupBox
CreateHyperlink
CreateImageControl
CreateListBox
CreateNumericField
CreatePatternField
CreateProgressBar
CreateRadioButton
CreateScrollBar
CreateTableControl
CreateTabPageContainer

CreateTextField
CreateTimeField
CreateTreeControl
EndExecute
Execute
GetTextsFromL10N
ImportControl
OrderTabs
Resize
SetPageManager
Terminate

I controlli TabPageContainer non sono disponibili nell'editor delle finestre di dialogo.

Il dimensionamento di una finestra di dialogo viene fatto usando le unità Map AppFont. Anche le finestre di messaggio o i modelli di controllo usano le unità AppFont. Mentre le loro visualizzazioni usano i pixel.

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

- un oggetto dialog di ScriptForge

- un oggetto document di ScriptForge (Calc, Base, ...)

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

## CloneControl

Duplica un controllo esistente di qualsiasi tipo nella finestra di dialogo corrente. Il controllo duplicato rimane immutato e può essere riposizionato.

### Sintassi:

svc.CloneControl(SourceName: str, ControlName: str, Left: num, Top: num): svc

### Parametri:

SourceName: il nome del controllo da duplicare.

ControlName: un nome valido per il controllo in formato stringa con distinzione tra lettere minuscole e maiuscole. Non deve esistere ancora.

Left, Top: le coordinate per il nuovo controllo espresse in unità Map AppFont.

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

          Set myButton2 = oDlg.CloneControl("Button1", "Button2", 30, 30)

##### In Python

         dlg = dlg.CloneControl('Button1', 'Button2', 30, 30)

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

## CreateButton

Crea un nuovo controllo di tipo pulsante (Button) nella finestra di dialogo corrente.

### Sintassi:

svc.CreateButton(ControlName: str, Place: any, Toggle: bool = False, Push: str = ""): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Toggle: se impostato su True viene creato un pulsante di tipo Attiva/Disattiva. Predefinito = False

Push: "OK", "ANNULLA" o "" (predefinito)

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myButton = oDlg.CreateButton("Button1", Array(20, 20, 60, 15))

##### In Python

         myButton = dlg.CreateButton('Button1', (20, 20, 60, 15))

## CreateCheckBox

Crea un nuovo controllo di tipo casella di controllo (CheckBox) nella finestra di dialogo corrente.

### Sintassi:

svc.CreateCheckBox(ControlName: str, Place: any, Multiline: bool = False): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

MultiLine: se impostato su True (predefinito = False), la descrizione può essere visualizzata su più di una riga.

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myCheckBox = oDlg.CreateCheckBox("CheckBox1", Array(20, 20, 60, 15), MultiLine := True)

##### In Python

         myCheckBox = dlg.CreateCheckBox('CheckBox1', (20, 20, 60, 15), MultiLine = True)

## CreateComboBox

Crea un nuovo controllo di tipo casella combinata (ComboBox) nella finestra di dialogo corrente.

### Sintassi:

svc.CreateComboBox(ControlName: str, Place: any, Border: str = "3D", DropDown: bool = True, LineCount: num = 5): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

DropDown: se impostato su True (predefinito), viene visualizzato un pulsante per l'elenco a tendina

LineCount: specifica il numero massimo di righe visualizzate nel menu a tendina (predefinito = 5)

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myComboBox = oDlg.CreateComboBox("ComboBox1", Array(20, 20, 60, 15), Dropdown := True)

##### In Python

         myComboBox = dlg.CreateComboBox('ComboBox1', (20, 20, 60, 15), Dropdown = True)

## CreateCurrencyField

Crea un nuovo controllo di tipo campo valuta (CurrencyField) nella finestra di dialogo corrente.

### Sintassi:

svc.CreateCurrencyField(ControlName: str, Place: any, Border ="3D", SpinButton: bool = False, MinValue: num = -1000000, MaxValue: num = +1000000, Increment: num = 1, Accuracy: num = 2): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

SpinButton: se impostato su True (predefinito = False), è presente un pulsante di selezione

MinValue: il valore minimo che può essere inserito nel controllo. Predefinito = -1000000

MaxValue: il valore massimo che può essere inserito nel controllo. Predefinito = +1000000

Increment: il valore del passo quando il pulsante di selezione viene premuto. Predefinito = 1

Accuracy: specifica la precisione decimale. Predefinito = 2 cifre decimali

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myCurrencyField = oDlg.CreateCurrencyField("CurrencyField1", Array(20, 20, 60, 15), SpinButton := True)

##### In Python

         myCurrencyField = dlg.CreateCurrencyField('CurrencyField1', (20, 20, 60, 15), SpinButton = True)

## CreateDateField

Crea un nuovo controllo di tipo campo data (DateField) nella finestra di dialogo corrente.

### Sintassi:

svc.CreateDateField(ControlName: str, Place: any, Border: str = "3D", DropDown: bool = False, opt MinDate: datetime, opt MaxDate: datetime): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

DropDown: se impostato su True (predefinito = False), viene visualizzato un pulsante per l'elenco a tendina

MinDate: la data più piccola che può essere inserita nel controllo. Predefinita = 1900-01-01

MaxDate: la data più grande che può essere inserita nel controllo. Predefinita = 2200-12-31

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myDateField = oDlg.CreateDateField("DateField1", Array(20, 20, 60, 15), Dropdown := True)

##### In Python

         myDateField = dlg.CreateDateField('DateField1', (20, 20, 60, 15), Dropdown = True)

## CreateFileControl

Crea un nuovo controllo di tipo FileControl nella finestra di dialogo corrente.

### Sintassi:

svc.CreateFileControl(ControlName: str, Place: any, Border: str = "3D"): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myFileControl = oDlg.CreateFileControl("FileControl1", Array(20, 20, 60, 15))

##### In Python

         myFileControl = dlg.CreateFileControl('FileControl1', (20, 20, 60, 15))

## CreateFixedLine

Crea un nuovo controllo di tipo FixedLine nella finestra di dialogo corrente.

### Sintassi:

svc.CreateFixedLine(ControlName: str, Place: any, Orientation: str): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Orientation: per l'orientamento orizzontale usare "H" o "Horizontal"; per quello verticale usare "V" o "Vertical".

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myFixedLine = oDlg.CreateFixedLine("FixedLine1", Array(20, 20, 60, 15), Orientation := "vertical")

##### In Python

         myFixedLine = dlg.CreateFixedLine('FixedLine1', (20, 20, 60, 15), Orientation = 'vertical')

## CreateFixedText

Crea un nuovo controllo di tipo FixedText nella finestra di dialogo corrente.

### Sintassi:

svc.CreateFixedText(ControlName: str, Place: any, Border: str = "3D", MultiLine: bool = False, Align: str = "LEFT", VerticalAlign: str = "TOP"): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "NONE" (nessuno, predefinito), "FLAT" (piatto) o "3D"

Multiline: se impostato su True (predefinito = False), la didascalia può essere visualizzata su una o più righe

Align: allineamento orizzontale, "LEFT" (a sinistra, predefinito), "CENTER" (al centro) o "RIGHT" (a destra)

VerticalAlign: allineamento verticale, "TOP" (in cima, predefinito), "MIDDLE" (al centro) o "BOTTOM" (in basso)

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myFixedText = oDlg.CreateFixedText("FixedText1", Array(20, 20, 60, 15), MultiLine := True)

##### In Python

         myFixedText = dlg.CreateFixedText('FixedText1', (20, 20, 60, 15), MultiLine = True)

## CreateFormattedField

Crea un nuovo controllo di tipo FormattedField nella finestra di dialogo corrente.

### Sintassi:

svc.CreateFormattedField(ControlName: str, Place: any, Border: str = "3D", SpinButton: bool = False, MinValue: num = -1000000, MaxValue: num = +1000000): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

SpinButton: se impostato su True (predefinito = False), è presente un pulsante di selezione

MinValue: il valore minimo che può essere inserito nel controllo. Predefinito = -1000000

MaxValue: il valore massimo che può essere inserito nel controllo. Predefinito = +1000000

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myFormattedField = oDlg.CreateFormattedField("FormattedField1", Array(20, 20, 60, 15), SpinButton := True)

##### In Python

         myFormattedField = dlg.CreateFormattedField('FormattedField1', (20, 20, 60, 15), SpinButton = True)

## CreateGroupBox

Crea un nuovo controllo di tipo GroupBox nella finestra di dialogo corrente.

### Sintassi:

svc.CreateGroupBox(ControlName: str, Place: any): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myGroupBox = oDlg.CreateGroupBox("GroupBox1", Array(20, 20, 60, 15))

##### In Python

         myGroupBox = dlg.CreateGroupBox('GroupBox1', (20, 20, 60, 15))

## CreateHyperlink

Crea un nuovo controllo di tipo Hyperlink nella finestra di dialogo corrente.

### Sintassi:

svc.CreateHyperlink(ControlName: str, Place: any, Border: str = "NONE", MultiLine: bool = False, Align: str = "LEFT", VerticalAlign: str = "TOP"): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "NONE" (nessuno, predefinito), "FLAT" (piatto) o "3D"

Multiline: se impostato su True (predefinito = False), la didascalia può essere visualizzata su una o più righe

Align: allineamento orizzontale, "LEFT" (a sinistra, predefinito), "CENTER" (al centro) o "RIGHT" (a destra)

VerticalAlign: allineamento verticale, "TOP" (in cima, predefinito), "MIDDLE" (al centro) o "BOTTOM" (in basso)

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myHyperlink = oDlg.CreateHyperlink("Hyperlink1", Array(20, 20, 60, 15), MultiLine := True)

##### In Python

         myHyperlink = dlg.CreateHyperlink('Hyperlink1', (20, 20, 60, 15), MultiLine = True)

## CreateImageControl

Crea un nuovo controllo di tipo ImageControl nella finestra di dialogo corrente.

### Sintassi:

svc.CreateImageControl(ControlName: str, Place: any, Border: str = "3D", Scale: str = "FITTOSIZE"): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

Scale - uno dei seguenti valori: "FITTOSIZE" (adatta alle dimensioni, predefinito), "KEEPRATIO" (mantieni proporzioni) o "NO"

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myImageControl = oDlg.CreateImageControl("ImageControl1", Array(20, 20, 60, 15))

##### In Python

           myImageControl = dlg.CreateImageControl('ImageControl1", (20, 20, 60, 15))

## CreateListBox

Crea un nuovo controllo di tipo ListBox nella finestra di dialogo corrente.

### Sintassi:

svc.CreateListBox(ControlName: str, Place: any, Border: str = "3D", DropDown: bool = True, LineCount: num = 5, MultiSelect: bool = False): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

DropDown: se impostato su True (predefinito), viene visualizzato un pulsante per l'elenco a tendina

LineCount: specifica il numero massimo di righe visualizzate nel menu a tendina (predefinito = 5)

MultiSelect: se impostato su True, è possibile selezionare più di una voce. Predefinito = False

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myListBox = oDlg.CreateListBox("ListBox1", Array(20, 20, 60, 15), Dropdown := True, MultiSelect := True)

##### In Python

         myListBox = dlg.CreateListBox('ListBox1', (20, 20, 60, 15), Dropdown = True, MultiSelect = True)

## CreateNumericField

Crea un nuovo controllo di tipo NumericField nella finestra di dialogo corrente.

### Sintassi:

svc.CreateNumericField(ControlName: str, Place: any, Border: str = "3D", SpinButton: bool = False, MinValue: num = -1000000, MaxValue: num = 1000000, Increment: num = 1, Accuracy: num = 2): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

SpinButton: se impostato su True (predefinito = False), è presente un pulsante di selezione

MinValue: il valore minimo che può essere inserito nel controllo. Predefinito = -1000000

MaxValue: il valore massimo che può essere inserito nel controllo. Predefinito = +1000000

Increment: il valore del passo quando il pulsante di selezione viene premuto. Predefinito = 1

Accuracy: specifica la precisione decimale. Predefinito = 2 cifre decimali

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myNumericField = oDlg.CreateNumericField("NumericField1", Array(20, 20, 60, 15), SpinButton := True)

##### In Python

         myNumericField = dlg.CreateNumericField('NumericField1', (20, 20, 60, 15), SpinButton = True)

## CreatePatternField

Crea un nuovo controllo di tipo PatternField nella finestra di dialogo corrente.

### Sintassi:

svc.CreatePatternField(ControlName: str, Place: any, Border: str = "3D", EditMask: str, opt LiteralMax: str): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

EditMask: un carattere usato come codice che determina che cosa l'utente può inserire
Per maggiori informazioni fare riferimento alla pagina wiki Pattern_Field.

LiteralMask: contiene i valori iniziali visualizzati nel campo a maschera

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myPatternField = oDlg.CreatePatternField("PatternField1", Array(20, 20, 60, 15), EditMask := "NNLNNLLLLL", LiteralMask := "__.__.2002")

##### In Python

         myPatternField = dlg.CreatePatternField('PatternField1', (20, 20, 60, 15), EditMask = 'NNLNNLLLLL', LiteralMask = '__.__.2002')

## CreateProgressBar

Crea un nuovo controllo di tipo ProgressBar nella finestra di dialogo corrente.

### Sintassi:

svc.CreateProgressBar(ControlName: str, opt Place: any, Border: str = "3D", MinValue: num = 0, MaxValue: num = 100): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

MinValue: il valore più piccolo che può essere inserito nel campo di controllo. Predefinito = 0

MaxValue: il valore più grande che può essere inserito nel campo di controllo. Predefinito = 100

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myProgressBar = oDlg.CreateProgressBar("ProgressBar1", Array(20, 20, 60, 15), MaxValue := 1000)

##### In Python

         myProgressBar = dlg.CreateProgressBar('ProgressBar1', (20, 20, 60, 15), MaxValue = 1000)

## CreateRadioButton

Crea un nuovo controllo di tipo RadioButton nella finestra di dialogo corrente.

### Sintassi:

svc.CreateRadioButton(ControlName: str, Place: any, MultiLine: bool = False): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Multiline: se impostato su True (predefinito = False), la didascalia può essere visualizzata su una o più righe

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myRadioButton = oDlg.CreateRadioButton("RadioButton1", Array(20, 20, 60, 15), MultiLine := True)

##### In Python

         myRadioButton = dlg.CreateRadioButton('RadioButton1', (20, 20, 60, 15), MultiLine = True)

## CreateScrollBar

Crea un nuovo controllo di tipo ScrollBar nella finestra di dialogo corrente.

### Sintassi:

svc.CreateScrollBar(ControlName: str, Place, Orientation: str, Border: str = "3D", MinValue: num = 0, MaxValue: num = 100): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Orientation: per l'orientazione orizzontale usare "H" o "Horizontal"; per quella verticale usare "V" o "Vertical".

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

MinValue: il valore più piccolo che può essere inserito nel campo di controllo. Predefinito = 0

MaxValue: il valore più grande che può essere inserito nel campo di controllo. Predefinito = 100

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myScrollBar = oDlg.CreateScrollBar("ScrollBar1", Array(20, 20, 60, 15), MaxValue := 1000)

##### In Python

         myScrollBar = dialog.CreateScrollBar('ScrollBar1', (20, 20, 60, 15), MaxValue = 1000)

## CreateTableControl

Crea un nuovo controllo di tipo TableControl nella finestra di dialogo corrente.

### Sintassi:

svc.CreateTableControl(ControlName: str, Place: any, Border: str = "3D", RowHeaders: bool = True, ColumnHeaders: bool = True, ScrollBars: str = "N", GridLines: bool = False): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

RowHeaders: se impostato su True (predefinito), vengono mostrate le intestazioni di riga

ColumnHeaders: se impostato su True (predefinito), vengono mostrate le intestazioni di colonna

ScrollBars: i valori possibili sono "H" o "Horizontal" (barre di scorrimento orizzontali), "V" o "Vertical" (barre di scorrimento verticali); "B" o "Both" (entrambe le barre di scorrimento); "N" o "None" (predefinito) per nessuna barra di scorrimento. Le barre di scorrimento appaiono dinamicamente, quando necessarie.

GridLines: se impostato su True (predefinito = False) vengono disegnate delle linee orizzontali e verticali tra le celle della griglia

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myTableControl = oDlg.CreateTableControl("TableControl1", Array(20, 20, 60, 15), ScrollBars := "B")

##### In Python

         myTableControl = dlg.CreateTableControl('TableControl1', (20, 20, 60, 15), ScrollBars = 'B')

## CreateTabPageContainer

Crea un nuovo controllo del tipo TabPageContainer nella finestra di dialogo corrente. Le schede vengono disposte su righe separate all'interno della finestra di dialogo, se necessario. TabPageContainer multipli non sono supportati.

La creazione del controllo TabPageContainer avviene sempre per ultima durante la creazione della finestra di dialogo.

### Sintassi:

svc.CreateTabPageContainer(ControlName: str, Place: any, TabHeaders: str[1..*], Border: str = "3D"): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

TabHeaders: una matrice di stringhe in cui ognuna definisce le etichette delle singole schede

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myTabPageContainer = oDlg.CreateTabPageContainer("someContainer", Array(20, 20, 60, 15), TabHeaders := Array("Modules", "Dialogs", "Libraries"))

##### In Python

         myTabPageContainer = dlg.CreateTabPageContainer('theTabs', TabHeaders=('Modules', 'Dialogs', 'Libraries'), place=(20, 20, 60, 15))

## CreateTextField

Crea un nuovo controllo di tipo TextField nella finestra di dialogo corrente.

### Sintassi:

svc.CreateTextField(ControlName: str, Place: any, Border: str = "3D", MultiLine: bool = False, MaximumLength: num = 0, PasswordCharacter: str = ""): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

Multiline: se impostato su True (predefinito = False), la didascalia può essere visualizzata su una o più righe

MaximumLength: il numero massimo di caratteri (predefinito = 0, che significa illimitato)

PasswordCharacter: un singolo carattere che specifica cosa visualizzare nel campo di testo per una password (predefinito = "")

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

    Set myTextField = oDlg.CreateTextField("TextField1", Array(20, 20, 120, 50), MultiLine := True)

##### In Python

         myTextField = dlg.CreateTextField('TextField1', (20, 20, 120, 50), MultiLine = True)

## CreateTimeField

Crea un nuovo controllo di tipo TimeField nella finestra di dialogo corrente.

### Sintassi:

svc.CreateTimeField(ControlName: str, Place: any, Border: str = "3D", MinTime: num = 0, MaxTime: num = 24): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

MinTime: l'orario più piccolo che può essere inserito nel campo di controllo. Predefinito = 0

MaxTime: l'orario più grande che può essere inserito nel campo di controllo. Predefinito = 24h

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myTimeField = oDlg.CreateTimeField("TimeField1", Array(20, 20, 60, 15))

##### In Python

         myTimeField = dlog.CreateTimeField('TimeField1', (20, 20, 60, 15))

## CreateTreeControl

Crea un nuovo controllo di tipo TreeControl nella finestra di dialogo corrente.

### Sintassi:

svc.CreateTreeControl(ControlName: str, Place: any, Border = "3D"): svc

### Parametri:

ControlName: il nome del nuovo controllo. Non deve esistere ancora.

Place: uno tra …

- una matrice Array di Basic o una tupla di Python con 4 elementi (X, Y, larghezza, altezza)

- un oggetto com.sun.star.awt.Rectangle [X, Y, Larghezza, Altezza]

Tutti gli elementi sono espressi usando le unità Map AppFont.

Border: "3D" (predefinito), "FLAT" (piatto) o "NONE" (nessuno)

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set myTreeControl = oDlg.CreateTreeControl("TreeControl1", Array(20, 20, 60, 15))

##### In Python

         myTreeControl = dlg.CreateTreeControl('TreeControl1', (20, 20, 60, 15))

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

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

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

## 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 titolo della finestra di dialogo.

- Le etichette dei seguenti tipi di campo di controllo: Pulsanti, Caselle di controllo, Linee fisse, Testi fissi, Caselle di riepilogo e Pulsanti di scelta.

- Stringhe statiche delle Caselle di riepilogo e delle Caselle combinate.

- I suggerimenti e gli aiuti testuali visualizzati quando il puntatore del mouse si sofferma sul controllo.

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

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

## ImportControl

Importa e duplica un controllo esistente di qualsiasi tipo da una finestra di dialogo a quella corrente. Il controllo duplicato non viene modificato. Il nuovo controllo può essere rinominato e riposizionato. Possono essere importati anche i gestori degli eventi, se presenti.

### Sintassi:

svc.ImportControl(SourceDialog: svc, SourceName: str, opt ControlName: str, Page: num = 0, OffsetX: num = 0, OffsetY:num = 0, IncludeOnProperties: bool = False): svc

### Parametri:

SourceDialog: un'istanza della classe SFDialogs.Dialog.

SourceName: il nome del controllo da importare.

ControlName: il nome del nuovo controllo. Non deve già esistere. Il nome predefinito è SourceName.

Page: il numero della pagina del nuovo controllo. Valore predefinito = 0

OffsetX, OffsetY: il numero di pixel da aggiungere alle coordinate del controllo sorgente nell'unità di misura "Map AppFont". Valore predefinito = 0, possono essere negativi.

IncludeOnProperties: comprende le proprietà degli eventi On.... Valore predefinito = False.

### Tipo di ritorno:

Un'istanza del servizio SFDialogs.DialogControl o Nothing.

### Esempio:

##### In Basic

         Set mCtrl = oDlg.ImportControl(srceDlg, "someCtrlName")

##### In Python

         dlg.ImportControl(srceDlg, 'aCtrlName', includeOnProperties=true)

## OrderTabs

Imposta l'ordine di tabulazione di una serie di campi di controllo. La sequenza dei campi di controllo è fornita come matrice contenente i loro nomi dal primo all'ultimo.

I campi di controllo con un indice >= 1 non sono accessibili con il tasto TAB se:
- sono stati omessi dalla lista passata
- il loro tipo è FixedLine, GroupBox o ProgressBar
- sono disabilitati

### Sintassi:

svc.TabsList(TabsList: num, Start: num = 1, Increment: num = 1): bool

### Parametri:

TabsList: una matrice di nomi di campi di controllo validi, in ordine di tabulazione

Start: l'indice di tabulazione da assegnare al primo campo di controllo dell'elenco. Predefinito = 1

Increment: la differenza tra due indici di tabulazione consecutivi. Predefinito = 1

### Tipo di ritorno:

Il metodo restituisce True se eseguito correttamente.

### Esempio:

##### In Basic

         oDlg.OrderTabs(Array("myListBox", "myTextField", "myNumericField"), Start := 10)

##### In Python

         dlg.OrderTabs(('myListBox', 'myTextField', 'myNumericField'), Start = 10)

## 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 unità AppFont. 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 mancanti non vengono modificati

### Esempio:

##### In Basic

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

##### In Python

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

## SetPageManager

Definisce quali controlli in una finestra di dialogo sono responsabili per lo sfogliare le pagine, rendendo più semplice gestire la proprietà Page di una finestra di dialogo e dei suoi controlli.

Le finestre di dialogo possono avere più pagine e la pagina correntemente visualizzata è definita dalla proprietà Page della finestra di dialogo. Se la proprietà Page non viene modificata, la pagina visibile predefinita è uguale a 0 (zero), il che significa che non è definita un pagina particolare e tutti i controlli visibili sono visualizzati indipendentemente dal valore impostato nella loro proprietà Page.

Se la proprietà Page di una finestra di dialogo viene modificata in qualche altro valore tipo 1, 2, 3 e via discorrendo, saranno visualizzati solo i controlli la cui proprietà Page corrisponde all'attuale pagina della finestra di dialogo.

Usando il metodo SetPageManager è possibile definire quattro tipi di gestori per le pagine:

- Casella di riepilogo o casella combinata: in questo caso, ogni voce dell'elenco nella casella di riepilogo o nella casella combinata corrisponde a una pagina. Il primo elemento si riferisce alla pagina 1, il secondo elemento alla pagina 2 e così avanti.

- Gruppo di pulsanti di scelta: definisce un gruppo di pulsanti di scelta che controllano quale pagina è visibile.

- Sequenza di pulsanti: definisce un insieme di pulsanti, ognuno dei quali corrisponde a una pagina della finestra di dialogo. Questa soluzione può essere usata per emulare un'interfaccia a schede posizionando i pulsanti uno a fianco all'altro nella finestra di dialogo.

- Pulsanti Precedente/Successiva: definisce quali pulsanti nella finestra di dialogo saranno usati per spostarsi alla pagina precedente/successiva della finestra di dialogo.

È possibile usare contemporaneamente più di un meccanismo di gestione delle pagine.

Si presume che questo metodo sia chiamato solamente una volta prima di chiamare il metodo Execute. Le chiamate successive saranno ignorate.

Se l'esecuzione va a buon fine questo metodo restituisce True.

### Sintassi:

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

### Parametri:

pilotcontrols: un elenco separato da virgole con i nomi dei controlli ListBox, ComboBox o RadioButton da usare come gestori delle pagine. Per i controlli RadioButton, specificare il nome del primo controllo nel gruppo da usare.

tabcontrols: un elenco separato da virgole con i nomi dei pulsanti da usare come gestori delle pagine. L'ordine nel quale sono indicati in questo argomento corrisponde al numero della pagina alla quale sono associati.

wizardcontrols: un elenco separato da virgole con i nomi dei due pulsanti da usare come pulsanti Precedente/Successiva.

lastpage: il numero dell'ultima pagina disponibile. Si raccomanda di specificare questo valore quando si usano i pulsanti Precedente/Successiva come gestore delle pagine.

### Esempio:

Si consideri una finestra di dialogo con tre pagine. La finestra di dialogo contiene un controllo ListBox denominato "aPageList" che sarà usato per controllare le pagine visibili. Inoltre, sono presenti due pulsanti denominati "btnPrevious" e "btnNext" che saranno usati come pulsanti Precedente/Successiva all'interno della finestra di dialogo.

##### In Basic

        oDlg.SetPageManager(PilotControls := "aPageList", _
                               WizardControls := "btnPrevious,btnNext", _
                               LastPage := 3)
        oDlg.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()

##### In 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 o negli script in Python.

Argomenti correlati

Servizio SFDialogs.DialogControl

Servizio ScriptForge.UI