Ajuda do LibreOffice 24.8
O serviço DialogControl gerencia os controles pertencentes a caixas de diálogo criadas com o Editor de Diálogos do Basic. Cada instância deste serviço representa um único controle em uma caixa de diálogo.
O foco deste serviço está na obtenção e definição de valores apresentados pelos controles de uma caixa de diálogo. A formatação é acessível por meio das propriedades XControlModel e XControlView.
Note que o conteúdo da propriedade DialogControl.Value varia de acordo com o tipo do controle.
Atenção especial é dada aos controles do tipo Árvore. É fácil povoar uma árvore, tanto ramo a ramo como diversos ramos de uma única vez. Inserir itens em um controle do tipo Árvore pode ser feito tanto de maneira estática como dinâmica.
O serviço SFDialogs.DialogControl está intimamente relacionado com o serviço SFDialogs.Dialog.
Antes de utilizar o serviço DialogControl, a biblioteca ScriptForge deve ser carregada ou importada:
O serviço DialogControl é invocado a partir de uma instância do serviço Dialog existente através de seu método Controls(). A caixa de diálogo deve ser inicializada com o serviço SFDialogs.Dialog.
      Dim myDialog As Object, myControl As Object
      Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)
      Set myControl = myDialog.Controls("myTextBox")
      myControl.Value = "Diálogo iniciado às " & Now()
      myDialog.Execute()
      ' ... processa os valores dos controles
      myDialog.Terminate()
   
     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "Diálogo iniciado às " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # ... processa os valores dos controles
     dlg.Terminate()
   Uma instância do serviço DialogControl pode ser recuperada por meio do serviço SFDialogs.DialogEvent, desde que o diálogo tenha sido iniciado com o serviço Dialog. No exemplo abaixo, oControl contém a instância DialogControl que acionou o evento de controle.
      Sub aControlEventHandler(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDialogs.DialogEvent", poEvent)
          ' ...
      End Sub
  Ou usando Python:
     def control_event_handler(event: uno):
         oControl = CreateScriptService('SFDialogs.DialogEvent', event)
         # ...
  Note que nos exemplos anteriores o prefixo "SFDialogs." pode ser omitido quando for considerado apropriado.
Ao criar um manipulador de eventos para eventos de controle, considera-se boa prática tratar os erros dentro da própria sub rotina. Por exemplo, suponha que o manipulador de eventos abaixo seja chamado quando o botão for clicado.
    Sub OnButtonClicked(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oControl As Object
        oControl = CreateScriptService("DialogEvent", oEvent)
        ' Processa o evento
        Exit Sub
    Catch:
        MsgBox SF_Exception.Description
        SF_Exception.Clear
    End Sub
  Chame SF_Exception.Clear se não quiser que o erro se propague após o término da execução do diálogo.
Em Python, use blocos nativos try/except para tratamento de exceções, conforme mostrado abaixo:
    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # Processa o evento
        except Exception as e:
            # O objeto "bas" abaixo é uma instância do serviço Basic
            bas.MsgBox(str(e))
  O serviço DialogControl está disponível para estes tipos de controles:
| • Button | • FixedLine | • ListBox | • TableControl | 
| Nome | Somente leitura | Tipo | Aplicável a | Descrição | 
|---|---|---|---|---|
| Border | Sim | String | Button, … | A propriedade Border refere-se ao entorno do controle: "3D", "FLAT" ou "NONE". | 
| Cancel | Não | Boolean | Button | Especifica se um botão de comando tem ou não o comportamento de um botão Cancelar. | 
| Caption | Não | String | Button, CheckBox, FixedLine, FixedText, GroupBox, Hyperlink, RadioButton | Especifica o texto associado com o controle. | 
| ControlType | Sim | String | Todos | Um dos tipos listados acima. | 
| CurrentNode | Não | Objeto | TreeControl | Nó selecionado mais ao topo do controle de Árvore. Consulte a documentação API XmutableTreeNode para maiores detalhes. | 
| Default | Não | Boolean | Button | Especifica se o botão de comando é o botão OK padrão. | 
| Enabled | Não | Boolean | Todos | Especifica se o controle é acessível com o cursor. | 
| Format | Não | String | DateField, TimeField, FormattedField (somente leitura) | Especifica o formato usado para mostrar datas e horas. Deve ser uma das Strings a seguir: Para datas: "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". Para horas: "24h short", "24h long", "12h short", "12h long". | 
| ListCount | Sim | Long | ComboBox, ListBox, TableControl | Especifica o número de linhas em uma caixa de listagem (ListBox) e caixa de combinação (ComboBox) ou um controle de tabela (TableControl). | 
| ListIndex | Não | Long | ComboBox, ListBox, TableControl | Especifica que item está selecionado numa caixa de listagem (ListBox), caixa de combinação (ComboBox) ou num controle de tabela (TableControl). | 
| Locked | Não | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, TextField, TimeField | Especifica se o controle é somente leitura. | 
| MultiSelect | Não | Boolean | ListBox | Especifica se o usuário pode fazer múltiplas seleções em um List Box. | 
| Name | Sim | String | Todos | Nome do controle. | 
| Page | Não | Integer | Todos | Uma caixa de diálogo pode ter várias páginas que podem ser percorridas pelo usuário uma a uma. A propriedade "Page" do objeto "Dialog" define qual página está ativa no diálogo. A propriedade Page de um controle define a página da caixa de diálogo em que o controle é visível. | 
| Parent | Sim | Serviço | Todos | Instância pai do objeto SFDialogs.Dialog. | 
| Picture | Não | String | Button, ImageControl | Especifica o nome de arquivo contendo um Bitmap ou outro tipo gráfico a ser apresentado no controle. O nome do arquivo deve seguir a notação definida no atributo FileNaming do serviço ScriptForge.FileSystem. | 
| RootNode | Sim | Objeto | TreeControl | Objeto representando o nó raiz de nível mais baixo (geralmente há apenas um nó desse tipo). Consulte a documentação API XmutableTreeNode para maiores detalhes. | 
| RowSource | Não | Array of strings | ComboBox, ListBox | Especifica os dados contidos em um List Box ou Combo Box. | 
| TabIndex | Sim | Numeric | All | A propriedade TabIndex especifica a posição de um controle na ordem de tabulação da caixa de diálogo. | 
| Text | Sim | String | ComboBox, FileControl, FormattedField, PatternField, TextField | Dá acesso ao texto sendo apresentado pelo controle. | 
| TipText | Não | String | Todos | Especifica o texto que aparece como dica quando o ponteiro do mouse passar sobre o controle. | 
| TripleState | Não | Boolean | CheckBox | Especifica se o controle caixa de seleção pode ou não aparecer esmaecido (em cinza claro). | 
| URL | Não | String | Hyperlink | A URL a ser aberta quando o controle é clicado. | 
| Value | Não | Variant | Consulte a propriedade Value | |
| Visible | Não | Boolean | Todos | Especifica se o controle está oculto ou visível. | 
| XControlModel | Sim | Objeto | Todos | Objeto UNO representando o modelo do controle. Consulte XControlModel e UnoControlDialogModel na documentação da API para mais detalhes. | 
| XControlView | Sim | Objeto | Todos | Objeto UNO representando a visualização do controle. Consulte XControl e UnoControlDialog na documentação da API para mais detalhes. | 
| XTreeDataModel | Sim | Objeto | TreeControl | Objeto UNO representando o modelo de dados do controle de Árvore. Consulte a documentação API XMutableTreeDataModel para maiores detalhes. | 
| Tipo do Controle | Tipo | Descrição | 
|---|---|---|
| Button | Boolean | Apenas para botões de ativação | 
| CheckBox | Boolean ou Integer | 0, False: não ativado | 
| ComboBox | String | Valor selecionado. A propriedade ListIndex é uma opção alternativa. | 
| CurrencyField | Numérico | |
| DateField | Date | |
| FileControl | String | Um nome de arquivo formatado de acordo com a propriedade FileNaming do serviço ScriptForge.FileSystem. | 
| FormattedField | String ou Numérico | |
| ListBox | String ou array de strings | A(s) linha(s) selecionada(s) como um escalar ou como um Array, dependendo do atributo MultiSelect | 
| NumericField | Numérico | |
| PatternField | String | |
| ProgressBar | Numérico | Deve estar dentro dos limites pré-definidos | 
| RadioButton | Boolean | Cada botão tem um nome próprio. Eles estão conectados se suas posições TAB são contíguas. Se um Radio Button estiver ativado com o valor True, os demais botões relacionados automaticamente serão ajustados para o valor False | 
| ScrollBar | Numérico | Deve estar dentro dos limites pré-definidos | 
| TableControl | Array | Matriz unidimensional com os dados da linha selecionada. | 
| TextField | String | Texto sendo apresentado no campo | 
| TimeField | Date | 
Não há propriedade Value para os controles de diálogo GroupBox, Hyperlink, ImageControl e TreeControl.
| Nome | Somente leitura | Descrição usada pela IDE Basic | 
|---|---|---|
| OnActionPerformed | Sim | Ação Executar | 
| OnAdjustmentValueChanged | Sim | Ao ajustar | 
| OnFocusGained | Sim | Quando receber o foco | 
| OnFocusLost | Sim | Quando perder o foco | 
| OnItemStateChanged | Sim | Ao alterar o estado do item | 
| OnKeyPressed | Sim | Ao pressionar uma tecla | 
| OnKeyReleased | Sim | Ao soltar uma tecla | 
| OnMouseDragged | Sim | Quando mover o mouse com tecla pressionada | 
| OnMouseEntered | Sim | Quando o mouse estiver dentro | 
| OnMouseExited | Sim | Quando o mouse estiver fora | 
| OnMouseMoved | Sim | Ao mover o mouse | 
| OnMousePressed | Sim | Ao pressionar o botão do mouse | 
| OnMouseReleased | Sim | Ao soltar o botão do mouse | 
| OnNodeExpanded | Não | (Não disponível na IDE Basic) quando o botão de expansão é pressionado em um nó do controle de Árvore | 
| OnNodeSelected | Não | (Não disponível na IDE Basic) quando um nó do controle de Árvore é selecionado | 
| OnTextChanged | Sim | Ao modificar o texto | 
| Lista de Métodos no Serviço DialogControl | ||
|---|---|---|
Cria e retorna um novo nó do controle de Árvore como um objeto UNO subordinado ao nó pai. Consulte a documentação da API XMutableTreeNode para maiores detalhes.
Este método pode ser chamado antes de mostrar a caixa de diálogo para construir a árvore inicial. Também pode ser chamado a partir de um evento de controle do diálogo usando o evento OnNodeExpanded para preencher a árvore dinamicamente.
svc.AddSubNode(parentnode: uno, displayvalue: str, opt datavalue: any): uno
parentnode: Objeto UNO do tipo com.sun.star.awt.tree.XMutableTreeNode que representa um nó.
displayvalue: Texto a ser mostrado no controle.
datavalue: Valor associado ao novo nó. datavalue pode ser uma string, um número ou uma data. Este argumento pode ser omitido se não for aplicável.
Os exemplos em LibreOffice Basic e Python acessam o diálogo myDialog da biblioteca Standard do documento atual.
      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 ...")
   
     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     tree = dlg.Controls('myTreeControl')
     root = tree.CreateRoot('Tree top')
     node = tree.AddSubNode(root, 'A branch ...')
   Retorna True quando uma sub-árvore, subordinada a um nó pai, pode ser inserida com sucesso em um controle de Árvore. Se o no pai já possuía nós filhos antes de chamar este método, os nós filhos são apagados.
svc.AddSubTree(parentnode: uno, flattree: any, opt withdatavalue: bool): bool
parentnode: Objeto UNO do tipo com.sun.star.awt.tree.XMutableTreeNode.
flattree: Array de 2 dimensões ordenados pela coluna que contém os valores apresentados. O Array pode ser obtido pelo método GetRows aplicado ao serviço SFDatabases.Database. Quando valor apresentado de um item do Array for igual a Empty ou Null, nenhum sub-nó é criado e o restante da linha é ignorada.
      Árvore Plana    >>>>    Sub-árvore resultante
      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: Quando for False (valor padrão), todas as colunas em flattree contém o texto a ser apresentado no controle de Árvore. Se for True, os textos a serem apresentados (displayvalue) estão nas colunas 0, 2, 4, ... enquanto os valores de dados (datavalue) estão nas colunas 1, 3, 5, ...
      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)
   
     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)
   Retorna um novo nó raiz do controle de Árvore, como um objeto UNO do tipo com.sun.star.awt.tree.XMutableTreeNode. A nova raiz da árvore é inserida abaixo dos nós raiz pré-existentes. Consulte a documentação da API XMutableTreeNode para maiores detalhes.
Este método pode ser chamado antes de mostrar a caixa de diálogo para construir a árvore inicial. Também pode ser chamado a partir de uma caixa de diálogo ou um evento de controle para preencher a árvore dinamicamente.
svc.CreateRoot(displayvalue: str, opt datavalue: any): uno
displayvalue: Texto a ser mostrado no controle.
      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.CreateRoot("Tree starts here ...")
   
     tree = dlg.Controls('myTreeControl')
     node = tree.CreateRoot('Tree starts here ...')
   Percorre a árvore e encontra recursivamente, iniciando a partir da raiz, um nó que satisfaz um dado critério: Ou o valor apresentado corresponde ao padrão displayvalue (apenas 1 correspondência já é suficiente) ou é igual ao valor datavalue. As comparações pode ou não ser sensíveis à caixa. A primeira ocorrência é retornada como um objeto UNO do tipo com.sun.star.awt.tree.XMutableTreeNode. Consulte a documentação da API XMutableTreeNode para maiores detalhes.
Quando não encontrado, o método retorna Nothing, o qual pode ser testado com a função interna IsNull().
Este método pode ser chamado antes de mostrar a caixa de diálogo para construir a árvore inicial. Também pode ser chamado a partir de uma caixa de diálogo ou um evento de controle.
svc.FindNode(displayvalue: str = '', opt datavalue: any, casesensitive = False): uno
Um argumento displayvalue ou datavalue deve ser especificado. Se ambos estiverem presentes, uma correspondência é suficiente para selecionar o nó.
displayvalue: Padrão a ser procurado. Consulte a documentação do método SF_String.IsLike() para ver a lista de todos os caracteres coringa aceitos. Se este parâmetro for igual a uma String de comprimento zero (padrão), o valor apresentado não é usado na busca.
casesensitive: O valor padrão é False
      Dim myTree As Object, myNode As Object
      Set myTree = myDialog.Controls("myTreeControl")
      Set myNode = myTree.FindNode("*Sophie*", CaseSensitive := True)
   
     tree = dlg.Controls('myTreeControl')
     node = FindNode('*Sophie*', casesensitive=True)
     if node is None:
         # ...
   Move o canto superior esquerdo de um controle para novas coordenadas e/ou modifique suas dimensões. Retorna True se o redimensionamento foi bem-sucedido.
svc.Resize(opt Left: int, opt Top: int, opt Width: int, opt Height: int): bool
Todas as distâncias são expressas na unidade Map AppFont e são medidas a partir do canto superior esquerdo da caixa de diálogo pai. Sem argumentos o método redimensiona o controle para seu "tamanho preferido", um tamanho ajustado dependendo do seu conteúdo real. Os argumentos ausentes permanecem inalterados.
Left: distância horizontal do canto superior esquerdo.
Top: distância vertical do canto superior esquerdo.
Width: a largura horizontal do retângulo que contém o controle.
Height: a altura vertical do retângulo que contém o controle.
      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.Resize(100, 200, Height:=6000) ' A largura não é modificada
    
      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.Resize(300, 200, 1500)  # A altura não é modificada
    Coloca o foco no controle. Retorna True se a colocação do foco foi bem-sucedida.
Este método é frequentemente chamado a partir de um diálogo ou por um evento de controle.
svc.SetFocus(): bool
      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.SetFocus()
    
      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.SetFocus()
    Preenche um controle de tabela TableControl com dados fornecidos. Todos os dados preexistentes são limpos antes de inserir os novos dados passados como argumento.
Ao adicionar o controle de tabela TableControl à caixa de diálogo, é possível usar o IDE do Basic para definir se os cabeçalhos de coluna e linha serão mostrados na tabela. Se o controle TableControl tem cabeçalhos de coluna e / ou linha, a primeira coluna e / ou linha na matriz de dados fornecida são usados como rótulos para os cabeçalhos da tabela.
Este método retorna True quando for bem-sucedido.
svc.SetTableData(dataarray: any[0..*, 0..*], widths: int[0..*], alignments: str, RowHeaderWidth = 10): bool
dataarray: dados a serem inseridos na tabela representados como uma matriz de matrizes em Basic ou uma tupla de tuplas em Python. Os dados devem incluir cabeçalhos de coluna e linha se eles forem exibidos pelo controle TableControl.
widths: matriz contendo as larguras relativas de cada coluna. Em outras palavras, widths = (1, 2) significa que a segunda coluna tem o dobro da largura da primeira. Se o número de valores na matriz for menor que o número de colunas na tabela, o último valor na matriz será usado para definir a largura das colunas restantes.
alignments: define o alinhamento em cada coluna como uma string em que cada caractere pode ser "L" (esquerda), "C" (centro), "R" (direita) ou "" (espaço em branco, padrão, significando esquerda para strings e direita para valores numéricos). Se o comprimento da string for menor que o número de colunas da tabela, o último caractere da string será usado para definir o alinhamento das colunas restantes.
RowHeaderWidth: largura da coluna do cabeçalho da linha expressa usando a unidade Map AppFont. O padrão é 10. O argumento é ignorado quando TableControl não possui cabeçalho de linha.
O exemplo a seguir assume que a caixa de diálogo myDialog possui um controle do tipo TableControl chamado Grid1 com as propriedades "Mostrar cabeçalhos de linha" e "Mostrar cabeçalhos de coluna" definidos como "Sim".
     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()
   A propriedade Value retorna a linha selecionada na tabela. Se nenhuma linha for selecionada, um objeto Array vazio é retornado. O fragmento de código a seguir mostra como testar se alguma linha está selecionada na tabela.
     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "Sem linha selecionada."
     Else
         MsgBox "A linha " & oTable.ListIndex & " está selecionada."
     End If
   
     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.")
   Adiciona uma nova linha ao final de uma caixa de texto de múltiplas linhas. Um caractere de fim de linha será inserido quando apropriado. O método retorna True se bem-sucedido.
Um erro é lançado se o controle atual não é do tipo TextField ou se não suportar múltiplas linhas.
svc.WriteLine(opt line: str): bool
Line: String a ser inserida. O valor padrão é uma linha em branco.
      Dim oDlg As Object, oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.WriteLine("a new line")
   
     dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')
     ctrl = dlg.Controls('thisControl')
     ctr.WriteLine("a new line")