Servizio SFDialogs.Dialog

The Dialog service contributes to the management of dialogs created with the Basic Dialog Editor or dialogs created on-the-fly. Each instance of the current class represents a single dialog box displayed to the user.

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


The Dialog service is invoked through the CreateScriptService method. It requires three supplemental positional arguments to specify the dialog box to activate:

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

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.


tip

The dialog service offers methods that create new controls dynamically in an existing dialog predefined with the Dialog Editor. A dialog is initialized with controls in the Dialog Editor and new controls can be added at run-time before or after the dialog Execute() statement.


The Dialog service can equally be invoked - through the CreateScriptService method - when creating dialogs on-the-fly. It requires two supplemental positional arguments after the name of the ad-hoc service "NewDialog":

DialogName: A case-sensitive string designating the dialog.

Place: Window location of the dialog being either :

All elements are expressed in Map AppFont units.


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

Or using Python:


    def newDialog():
       dlg = CreateScriptService('NewDialog', 'myDialog1', (100,200, 40, 110))
       # ... Process controls and do what is needed
  

All properties and methods applicable to predefined dialogs are available for such new dialogs. In particular the series of CreateXXX() methods for the addition of new dialog controls.

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
  
tip

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

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

On… properties return a URI string with the reference to the script triggered by the event. On… properties can be set programmatically.
Read its specification in the scripting framework URI specification.

Nome

Read/Write

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


warning

Assigning events via the Basic IDE and assigning events via macros are mutually exclusive.


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
CreateTextField
CreateTimeField
CreateTreeControl
EndExecute
Execute
GetTextsFromL10N
Resize
OrderTabs
SetPageManager
Terminate


note

Dimensioning a dialog is done by using Map AppFont units. A dialog or control model also uses AppFont units. While their views use pixels.


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

CloneControl

Duplicate an existing control of any type in the actual dialog. The duplicated control is left unchanged and can be relocated.

Sintassi:

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

Parametri:

SourceName: The name of the control to duplicate.

ControlName: A valid control name as a case-sensitive string. It must not exist yet.

Left, Top: The coordinates of the new control expressed in Map AppFont units.

Valore restituito:

An instance of SFDialogs.DialogControl service or 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:

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

Create a new control of type Button in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Toggle: when True a Toggle button is created. Default = False

Push: "OK", "CANCEL" or "" (default)

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type CheckBox in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

MultiLine: When True (default = False), the caption may be displayed on more than one line.

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type ComboBox in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

DropDown: When True (default), a drop down button is displayed

LineCount: Specifies the maximum line count displayed in the drop down (default = 5)

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type CurrencyField in the current dialog.

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: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

SpinButton: when True (default = False), a spin button is present

MinValue: the smallest value that can be entered in the control. Default = -1000000

MaxValue: the largest value that can be entered in the control. Default = +1000000

Increment: the step when the spin button is pressed. Default = 1

Accuracy: specifies the decimal accuracy. Default = 2 decimal digits

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type DateField in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

DropDown: when True (default = False), a dropdown button is shown

MinDate: the smallest date that can be entered in the control. Default = 1900-01-01

MaxDate: the largest date that can be entered in the control. Default = 2200-12-31

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type FileControl in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type FixedLine in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Orientation: "H[orizontal]" or "V[ertical]".

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type FixedText in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "NONE" (default) or "FLAT" or "3D"

Multiline: When True (default = False), the caption may be displayed on more than one line

Align: horizontal alignment, "LEFT" (default) or "CENTER" or "RIGHT"

VerticalAlign: vertical alignment, "TOP" (default) or "MIDDLE" or "BOTTOM"

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type FormattedField in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

SpinButton: when True (default = False), a spin button is present

MinValue: the smallest value that can be entered in the control. Default = -1000000

MaxValue: the largest value that can be entered in the control. Default = +1000000

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type GroupBox in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type Hyperlink in the current dialog.

Sintassi:

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "NONE" (default) or "FLAT" or "3D"

MultiLine: When True (default = False), the caption may be displayed on more than one line

Align: horizontal alignment, "LEFT" (default) or "CENTER" or "RIGHT"

VerticalAlign: vertical alignment, "TOP" (default) or "MIDDLE" or "BOTTOM"

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type ImageControl in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

Scale: One of next values: "FITTOSIZE" (default), "KEEPRATIO" or "NO"

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type ListBox in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

DropDown: When True (default), a drop down button is displayed

LineCount: Specifies the maximum line count displayed in the drop down (default = 5)

MultiSelect: When True, more than 1 entry may be selected. Default = False

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type NumericField in the current dialog.

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: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

SpinButton: when True (default = False), a spin button is present

MinValue: the smallest value that can be entered in the control. Default = -1000000

MaxValue: the largest value that can be entered in the control. Default = +1000000

Increment: the step when the spin button is pressed. Default = 1

Accuracy: specifies the decimal accuracy. Default = 2 decimal digits

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type PatternField in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

EditMask: a character code that determines what the user may enter
Refer to Pattern_Field in the wiki for more information.

LiteralMask: contains the initial values that are displayed in the pattern field

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type ProgressBar in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

MinValue: the smallest value that can be entered in the control. Default = 0

MaxValue: the largest value that can be entered in the control. Default = 100

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type RadioButton in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

MultiLine: When True (default = False), the caption may be displayed on more than one line

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type ScrollBar in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Orientation: H[orizontal] or V[ertical]

Border: "3D" (default) or "FLAT" or "NONE"

MinValue: the smallest value that can be entered in the control. Default = 0

MaxValue: the largest value that can be entered in the control. Default = 100

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type TableControl in the current dialog.

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: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

RowHeaders: when True (default), the row Headers are shown

ColumnHeaders: when True (default), the column Headers are shown

ScrollBars: H[orizontal] or V[ertical] or B[oth] or N[one] (default). Scrollbars appear dynamically when they are needed.

GridLines: when True (default = False) horizontal and vertical lines are painted between the grid cells

Valore restituito:

An instance of SFDialogs.DialogControl service or 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')
   

CreateTextField

Create a new control of type TextField in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

MultiLine: When True (default = False), the caption may be displayed on more than one line

MaximumLength: the maximum character count (default = 0 meaning unlimited)

PasswordCharacter: a single character specifying the echo for a password text field (default = "")

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type TimeField in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

MinTime: the smallest time that can be entered in the control. Default = 0

MaxTime: the largest time that can be entered in the control. Default = 24h

Valore restituito:

An instance of SFDialogs.DialogControl service or 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

Create a new control of type TreeControl in the current dialog.

Sintassi:

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

Parametri:

ControlName: the name of the new control. It must not exist yet.

Place: either …

All elements are expressed in Map AppFont units.

Border: "3D" (default) or "FLAT" or "NONE"

Valore restituito:

An instance of SFDialogs.DialogControl service or 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)
   
tip

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


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.


OrderTabs

Set the tabulation index of a series of controls. The sequence of controls are given as an array of control names from the first to the last.

warning

Controls with an index >= 1 are not accessible with the TAB key if:
- they are omitted from the given list
- their type is FixedLine, GroupBox or ProgressBar
- they are disabled


Sintassi:

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

Parametri:

TabsList: an array of valid control names in the order of tabulation

Start: the tab index to be assigned to the 1st control in the list. Default = 1

Increment: the difference between 2 successive tab indexes. Default = 1

Valore restituito:

True when successful.

Esempio:

In Basic

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

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

Resize

Moves the topleft corner of a dialog to new coordinates and/or modify its dimensions. All distances are expressed in AppFont units. Without arguments, the method resets the initial dimensions. Return True if the resize was successful.

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

Missing arguments are left unchanged

Esempio:

In Basic

     oDlg.Resize(1000, 2000, Height := 6000) ' Width is not changed
   
In Python

     dlg.Resize(1000, 2000, Height = 6000)  # Width is not changed
   

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:

tip

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