Serviço SFDialogs.DialogControl

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.

Invocação do serviço

Antes de utilizar o serviço DialogControl, a biblioteca ScriptForge deve ser carregada ou importada:

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService

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

Recuperando a instância DialogControl que disparou um evento de controle

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.

Lidando com exceções em manipuladores de eventos

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

Tipos de Controles

O serviço DialogControl está disponível para estes tipos de controles:

Propriedades

A propriedade Value

A propriedade Value não existe para os controles do tipo GroupBox, Hyperlink, ImageControl e TreeControl.

Propriedades de Evento

Atribuir eventos com a IDE do Basic e atribuir eventos por meio de macros são mutuamente exclusivas.

Métodos

AddSubNode

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

AddSubTree

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)
   

CreateRoot

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

FindNode

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

Resize

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
    

SetFocus

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

SetTableData

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.")
   

WriteLine

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

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.