Servizio SFDialogs.DialogControl

Il servizio DialogControl gestisce i controlli appartenenti a una finestra di dialogo definita dall'Editor delle finestre di Basic. Ogni istanza del servizio corrente rappresenta un singolo controllo all'interno della finestra di dialogo.

Lo scopo è quello di ottenere ed impostare i valori visualizzati dai controlli della finestra di dialogo. La formattazione è accessibile tramite le proprietà XControlModel e XControlView.

Fate attenzione che il contenuto dell'unica proprietà DialogControl.Value varia in base al tipo di controllo.

Un'attenzione particolare è rivolta ai controlli del tipo ad albero. È facile popolare un albero, ramo per ramo, o con un insieme di rami contemporaneamente. Il popolamento di un controllo ad albero può essere eseguito staticamente o dinamicamente.

tip

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


Invocare il servizio

Il servizio DialogControl è invocato da un'istanza esistente del servizio Dialog attraverso il relativo metodo Controls(). La finestra di dialogo deve essere inizializzata con il servizio SFDialogs.Dialog.


      Dim myDialog As Object, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
      Set myControl = myDialog.Controls("myTextBox")
      myControl.Value = "Finestra di dialogo avviata il" & Now()
      myDialog.Execute()
      '... elabora i valori effettivi dei controlli
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Finestra di dialogo avviata il" + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     #... elabora i valori effettivi dei controlli
     dlg.Terminate()
   

In alternativa l'istanza di un controllo può essere richiamata tramite il servizio SFDialogs.DialogEvent, a patto che la finestra di dialogo sia stata inizializzata con il servizio Dialog. DialogEvent restituisce la classe dell'istanza SFDialogs.DialogControl che ha attivato l'evento.


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

     def some_event(event: uno):
         ctrl = CreateScriptService('SFDialogs.DialogEvent', event)
         # ...
   

Si noti che negli esempi precedenti il prefisso "SFDialogs." può essere omesso.

Tipi di controllo

Il servizio DialogControl è disponibile per questi tipi di controllo:

Proprietà

Nome

Sola lettura

Tipo

Applicabile a

Descrizione

Cancel

No

Boolean

Button

Specifica se un pulsante di comando ha o non ha il comportamento di un pulsante Annulla.

Caption

No

String

Button, CheckBox, FixedLine, FixedText, GroupBox, RadioButton

Specifica il testo associato al controllo.

ControlType

String

Tutto

Uno dei tipi elencati sopra.

CurrentNode

No

Oggetto della libreria UNO

TreeControl

Il nodo superiore attualmente selezionato nel controllo ad albero. Per informazioni più dettagliate fate riferimento a XmutableTreeNode nella documentazione delle API (Application Programming Interface).

Default

No

Boolean

Button

Specifica se un pulsante di comando è il pulsante predefinito (OK).

Enabled

No

Boolean

Tutto

Specifica se il controllo è accessibile con il cursore.

Format

No

String

DateField, TimeField, FormattedField

(sola lettura)

Specifica il formato usato per visualizzare le date e gli orari. Deve essere una delle seguenti stringhe:

Per le date: "Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY" , "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD".

Per gli orari: "24h short", "24h long", "12h short", "12h long".

ListCount

Long

ComboBox, ListBox, TableControl

Specifies the number of rows in a ListBox, a ComboBox or a TableControl.

ListIndex

No

Long

ComboBox, ListBox, TableControl

Specifies which item is selected in a ListBox, a ComboBox or a TableControl.

Locked

No

Boolean

ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, TextField, TimeField

Specifica se il controllo è di sola lettura.

MultiSelect

No

Boolean

ListBox

Specifica se un utente può eseguire selezioni multiple in una casella di riepilogo.

Name

String

Tutto

Il nome del controllo.

Page

No

Integer

Tutto

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 è attiva.

La proprietà Page di un controllo definisce la pagina della finestra di dialogo sulla quale è visibile il controllo.

Parent

Servizio
Dialog

Tutto

La classe SFDialogs.Dialog genitrice dell'istanza dell'oggetto.

Picture

No

String

Button, ImageControl

Specifica il nome del file che contiene una bitmap o un altro tipo di immagine da visualizzare nel controllo specificato. Il nome del file deve essere conforme a quanto previsto per l'attributo FileNaming del servizio ScriptForge.FileSystem.

RootNode

Oggetto della libreria UNO

TreeControl

Un oggetto che rappresenta il nodo radice più in basso (di solito esiste solo un nodo così). Per informazioni dettagliate fate riferimento a XmutableTreeNode nella documentazione delle API (Application Programming Interface).

RowSource

No

Array of strings

ComboBox, ListBox

Specifica i dati contenuti in una casella combinata o in una casella di riepilogo.

Text

String

ComboBox, FileControl, FormattedField, PatternField, TextField

Fornisce l'accesso al testo visualizzato dal controllo.

TipText

No

String

Tutto

Specifica il testo che compare come suggerimento quando il puntatore del mouse viene posizionato sopra il controllo.

TripleState

No

Boolean

CheckBox

Specifica se la casella di controllo deve apparire disabilitata (in grigio) o no.

Value

No

Variant

Fate riferimento a proprietà Value

Visible

No

Boolean

Tutto

Specifica se il controllo è nascosto o visibile.

XControlModel

Oggetto della libreria UNO

Tutto

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

XControlView

Oggetto della libreria UNO

Tutto

L'oggetto UNO che rappresenta la vista del controllo. Per informazioni dettagliate fate riferimento a XControl e UnoControlDialog nella documentazione delle API (Application Programming Interface).

XTreeDataModel

Oggetto della libreria UNO

TreeControl

L'oggetto UNO che rappresenta il modello del controllo ad albero. Per informazioni dettagliate fate riferimento a XMutableTreeDataModel nella documentazione delle API (Application Programming Interface).


La proprietà Value

Tipo del controllo

Tipo

Descrizione

Button

Boolean

Solo per i pulsanti di tipo attiva/disattiva

CheckBox

Logico (booleano) o intero

0, False: non spuntato
1, True: spuntato
2: in grigio, non specificato

ComboBox

String

Il valore selezionato. La proprietà ListIndex è un opzione alternativa.

CurrencyField

Numerico

DateField

Date

FileControl

String

Un nome di file formattato in conformità con la proprietà FileNaming del servizio ScriptForge.FileSystem

FormattedField

Stringa o numerico

ListBox

Stringa o matrice di stringhe

Le righe selezionate in formato scalare o come matrice a seconda dell'attributo MultiSelect

NumericField

Numerico

PatternField

String

ProgressBar

Numerico

Deve essere compreso tra i limiti prestabiliti

RadioButton

Boolean

Ogni pulsante ha il proprio nome. Sono collegati se le loro posizioni di tabulazione (TAB) sono adiacenti. Se un Pulsante di scelta è impostato a True, gli altri pulsanti collegati vengono automaticamente impostati a False

ScrollBar

Numerico

Deve essere compreso entro limiti prestabiliti

TableControl

Array

One-dimensional array with the data of the currently selected row.

TextField

String

Il testo che appare nel campo

TimeField

Date


Proprietà dell'evento

Restituisce una stringa URI col riferimento allo script attivato dall'evento. Consultate le sue specifiche nella pagina wiki Scripting Framework URI Specification (in inglese).

Nome

Sola lettura

La descrizione come etichettata nella IDE di Basic

OnActionPerformed

Esegui azione

OnAdjustmentValueChanged

Durante la regolazione

OnFocusGained

Al ricevimento del fuoco

OnFocusLost

Alla perdita del fuoco

OnItemStateChanged

Lo stato dell'elemento è cambiato

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

OnNodeExpanded

No

(Non nella IDE di Basic) quando viene premuto il pulsante di espansione di un nodo di un controllo ad albero

OnNodeSelected

No

(Non nella IDE di Basic) quando viene selezionato un nodo di un controllo ad albero

OnTextChanged

Testo modificato


Metodi

Elenco dei metodi del servizio DialogControl

AddSubNode
AddSubTree
CreateRoot

FindNode
SetFocus

SetTableData
WriteLine


AddSubNode

Crea e restituisce un nuovo nodo di un controllo ad albero in formato oggetto UNO subordinato a un nodo genitore. Per informazioni dettagliate fate riferimento a XMutableTreeNode nella documentazione delle API (Application Programming Interface).

Questo metodo può essere chiamato prima di visualizzare la finestra di dialogo per creare l'albero iniziale. Può essere chiamato anche da un evento di una finestra di dialogo o di un controllo - usando l'evento OnNodeExpanded - per completare dinamicamente l'albero.

Sintassi:

svc.AddSubNode(parentnode: uno, displayvalue: str, opt datavalue: any): uno

Parametri:

parentnode: un nodo in formato oggetto UNO, del tipo com.sun.star.awt.tree.XMutableTreeNode.

displayvalue: il testo che compare nella finestra del controllo ad albero.

datavalue: qualsiasi valore associato al nuovo nodo. datavalue può essere una stringa, un numero o una data. Omettete l'argomento quando non è applicabile.

Esempio:

Esempi in LibreOffice Basic e Python che caricano nel documento attuale la finestra myDialog dalla libreria Standard.

In Basic

      Dim oDlg As Object, myTree As Object, myNode As Object, theRoot As Object
      Set oDlg = CreateScriptService("Dialog",,, "myDialog")
      Set myTree = oDlg.Controls("myTreeControl")
      Set theRoot = myTree.CreateRoot("Tree top")
      Set myNode = myTree.AddSubNode(theRoot, "A branch ...")
   
In Python

     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     tree = dlg.Controls('myTreeControl')
     root = tree.CreateRoot('Tree top')
     node = tree.AddSubNode(root, 'A branch ...')
   

AddSubTree

Restituisce True se un sottoalbero, subordinato a un nodo genitore, poteva essere inserito correttamente in un controllo ad albero. Se prima di chiamare questo metodo il nodo genitore aveva già dei nodi figli, questi vengono cancellati.

Questo metodo può essere chiamato prima di visualizzare la finestra di dialogo per creare l'albero iniziale. Può essere chiamato anche da un evento di una finestra di dialogo o di un controllo - usando l'evento OnNodeExpanded - per completare dinamicamente l'albero.

Sintassi:

svc.AddSubTree(parentnode: uno, flattree: any, opt withdatavalue: bool): bool

Parametri:

parentnode: Un nodo in formato oggetto UNO, del tipo com.sun.star.awt.tree.XMutableTreeNode.

flattree: una matrice bidimensionale ordinata in base alle colonne contenti i dati da visualizzare. Tale matrice può essere fornita dal metodo GetRows applicato al servizio SFDatabases.Database. Quando un elemento della matrice che contiene il testo da visualizzare è Empty o Null, non viene creato alcun nuovo nodo derivato ed il resto della riga viene saltato.


      Albero piatto >>>> Sottoalbero risultante
      A1	B1	C1             |__   A1	
      A1	B1	C2                   |__   B1
      A1	B2	C3                         |__  C1
      A2	B3	C4                         |__  C2
      A2	B3	C5                   |__   B2
      A3	B4	C6                         |__  C3
                             |__   A2
                                   |__   B3
                                         |__  C4
                                         |__  C5
                             |__   A3
                                   |__   B4
                                         |__  C6
   

withdatavalue: Se è False viene usato il valore predefinito, ogni colonna del flattree contiene il testo da visualizzare nel controllo ad albero. Se è True, i testi da visualizzare (displayvalue) si trovano nelle colonne 0, 2, 4, ... mentre i valori dei dati (datavalue) sono nelle colonne 1, 3, 5, ...

Esempio:

In Basic

      Dim myTree As Object, theRoot As Object, oDb As Object, vData As Variant
      Set myTree = myDialog.Controls("myTreeControl")
      Set theRoot = myTree.CreateRoot("By product category")
      Set oDb = CreateScriptService("SFDatabases.Database", "/home/.../mydatabase.odb")
      vData = oDb.GetRows("SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] " _
          & "FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] " _
          & "ORDER BY [Category].[Name], [Product].[Name]")
      myTree.AddSubTree(theRoot, vData, WithDataValue := True)
   
In Python

     SQL_STMT = "SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] \
         FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] \
         ORDER BY [Category].[Name], [Product].[Name]"
     tree = dlg.Controls('myTreeControl')
     root = tree.CreateRoot('By Product category')
     db = CreateScriptService('SFDatabases.Database', '/home/.../mydatabase.odb')
     sub_tree = db.GetRows(SQL_STMT)
     tree.AddSubTree(root, sub_tree, withdatavalue=True)
   

CreateRoot

Restituisce un nuovo nodo radice di un controllo ad albero, in formato oggetto UNO del tipo com.sun.star.awt.tree.XMutableTreeNode. La nuova radice dell'albero viene inserita sotto i nodi radice preesistenti. Per informazioni dettagliate fate riferimento a XMutableTreeNode nella documentazione delle API (Application Programming Interface).

Questo metodo può essere chiamato prima di visualizzare la finestra di dialogo per creare l'albero iniziale. Può essere chiamato anche dall'evento di una finestra di dialogo o di un controllo per completare l'albero dinamicamente.

Sintassi:

svc.CreateRoot(displayvalue: str, opt datavalue: any): uno

Parametri:

displayvalue: Il testo che compare nella finestra del controllo ad albero.

datavalue: qualsiasi valore associato al nuovo nodo. datavalue può essere una stringa, un numero o una data. Omettete l'argomento quando non è applicabile.

Esempio:

In Basic

      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.CreateRoot("Tree starts here ...")
   
In Python

     tree = dlg.Controls('myTreeControl')
     node = tree.CreateRoot('Tree starts here ...')
   

FindNode

Attraversa l'albero e trova ricorsivamente, a partire dalla radice, un nodo che rispetta determinati criteri. Sia - 1 condizione è sufficiente - che abbia il valore visualizzato corrispondente al criterio di ricerca displayvalue o che abbia il valore uguale a datavalue. La comparazione può essere o meno sensibile alla differenza tra maiuscole e minuscole. La prima occorrenza trovata viene restituita come nodo in formato oggetto UNO del tipo com.sun.star.awt.tree.XMutableTreeNode. Per informazioni dettagliate fate riferimento a XMutableTreeNode nella documentazione delle API (Application Programming Interface).

Se non trova nulla, il metodo restituisce Nothing, da controllare con la funzione incorporata IsNull().

Questo metodo può essere chiamato prima di visualizzare la finestra di dialogo per creare l'albero iniziale. Può essere chiamato anche da un evento di una finestra di dialogo o di un controllo.

Sintassi:

svc.FindNode(displayvalue: str = '', opt datavalue: any, casesensitive = False): uno

Parametri:

È necessario specificare un argomento tra displayvalue o datavalue. Se sono presenti entrambi è sufficiente una sola corrispondenza per selezionare il nodo.

displayvalue: il criterio di ricerca da trovare. Fate riferimento al metodo SF_String.IsLike() per l'elenco dei possibili caratteri jolly. Quando è uguale a una stringa di lunghezza zero (predefinito), questo valore di visualizzazione non viene ricercato.

datavalue: qualsiasi valore associato al nuovo nodo. datavalue può essere una stringa, un numero o una data. Omettete l'argomento quando non è applicabile.

casesensitive: Il valore predefinito è False

Esempio:

In Basic

      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.FindNode("*Sophie*", CaseSensitive := True)
   
In Python

     tree = dlg.Controls('myTreeControl')
     node = FindNode('*Sophie*', casesensitive=True)
     if node is None:
         # ...
   

SetFocus

Imposta il fuoco sul controllo. Restituisce True se l'impostazione del fuoco è riuscita.

Questo metodo viene chiamato spesso da un evento di un finestra di dialogo o di un controllo.

Sintassi:

svc.SetFocus(): bool

Esempio:

In Basic

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.SetFocus()
    
In Python

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.SetFocus()
    

SetTableData

Fills a TableControl with the given data. All preexisting data is cleared before inserting the new data passed as argument.

When the TableControl is added to the dialog, it is possible to use the Basic IDE to define whether column and row headers will be shown in the table. If the TableControl has column and/or row headers, the first column and/or row in the provided data array are used as labels for the table headers.

This method returns True when successful.

Sintassi:

svc.SetTableData(dataarray: any[0..*, 0..*], widths: int[0..*], alignments: str): bool

Parametri:

dataarray: Data to be entered into the table represented as an Array of Arrays in Basic or a tuple of tuples in Python. The data must include column and row headers if they are to be displayed by the TableControl.

widths: Array containing the relative widths of each column. In other words, widths = Array(1, 2) means that the second column is twice as wide as the first one. If the number of values in the array is smaller than the number of columns in the table, then the last value in the array is used to define the width of the remaining columns.

alignments: Defines the alignment in each column as a string in which each character can be "L" (Left), "C" (Center), "R" (Right) or " " (whitespace, default, meaning left for strings and right for numeric values). If the length of the string is shorter than the number of columns in the table, then the last character in the string is used to define the alignment of the remaining columns.

Esempio:

In Basic

The following example assumes that the dialog myDialog has a TableControl named Grid1 with "Show header row" and "Show column row" properties set to "Yes".


     Dim myDialog As Object, oTable As Object, tableData As Variant
     myDialog = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")
     oTable = myDialog.Controls("Grid1")
     tableData = Array("Column A", "Column B", "Column C")
     tableData = SF_Array.AppendRow(tableData, Array("Row 1", 1, 2))
     tableData = SF_Array.AppendRow(tableData, Array("Row 2", 3, 4))
     tableData = SF_Array.AppendRow(tableData, Array("Row 3", 5, 6))
     vAlignments = "LCC"
     vWidths = Array(2, 1, 1)
     oTable.SetTableData(tableData, vWidths, vAlignments)
     myDialog.Execute()
   

The Value property returns the selected row in the table. If no row is selected, an empty Array object is returned. The following code snippet shows how to test if any row is selected in the table.


     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "No row selected."
     Else
         MsgBox "Row " & oTable.ListIndex & " is selected."
     End If
   
In Python

     dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")
     table_control = dlg.Controls("Grid1")
     table_data = (("Column A", "Column B", "Column C"),
                   ("Row 1", 1, 2),
                   ("Row 2", 3, 4),
                   ("Row 3", 5, 6))
     alignments = "LCC"
     widths = (100, 50, 50)
     table_control.SetTableData(table_data, widths, alignments)
     dlg.Execute()
   

     bas = CreateScriptService("Basic")
     row_values = table_control.Value
     if len(row_values) == 0:
         bas.MsgBox("No row selected.")
     else:
         bas.MsgBox(f"Row {table_control.ListIndex} is selected.")
   

WriteLine

Aggiunge una nuova riga alla fine di un campo di testo con più righe. Se necessario viene inserito un carattere interruzione di riga. Il metodo restituisce True se eseguito con successo.

Viene generato un errore se il controllo attivo non è del tipo TextField o non è multiriga.

Sintassi:

svc.WriteLine(opt line: str): bool

Parametri:

Line: La stringa da inserire. Il valore predefinito è una riga vuota.

Esempio:

In Basic

      Dim oDlg As Object, oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.WriteLine("a new line")
   
In Python

     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     ctrl = dlg.Controls('thisControl')
     ctr.WriteLine("a new line")
   
warning

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.