SFDialogs.DialogControl serviço

O serviço DialogControl gere os controlos pertencentes a uma caixa de diálogo definida com o Editor de Caixas de Diálogo da Basic. Cada instância do serviço atual representa um único controlo dentro de uma caixa de diálogo.

O foco está em obter e definir os valores apresentados pelos controlos da caixa de diálogo. A formatação é acedida através das propriedades XControlModel e XControlView.

Note-se que o conteúdo da propriedade DialogControl.Value, que é único, varia consoante o tipo de controlo.

Note-se que o conteúdo da propriedade DialogControl.Value, que é único, varia consoante o tipo de controlo.

O serviço SFDialogs.DialogControl está intimamente relacionado com o serviço SFDialogs.Dialog.

Chamada de serviço

Antes de utilizar o serviço DialogControl, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

O serviço DialogControl é invocado a partir de uma instância existente do serviço Dialog através do seu método Controls(). A caixa de diálogo deve ser iniciada 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 = "A caixa de diálogo foi iniciada às " & Now()
      myDialog.Execute()
      ' ... processar os valores reais dos controlos
      myDialog.Terminate()
   

     from time import localtime, strftime
     dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)
     text = dlg.Controls('myTextBox')
     text.Value = "A caixa de diálogo foi iniciada às " + strftime("%a, %d %b %Y %H:%M:%S", localtime())
     dlg.Execute()
     # ... processar os valores reais dos controlos
     dlg.Terminate()
   

# ... processar os valores reais dos controlos

É possível recuperar uma instância do serviço DialogControl através do serviço SFDialogs.DialogEvent, desde que a caixa de diálogo tenha sido iniciada com o serviço Dialog. No exemplo abaixo, oControl contém a instância de DialogControl que desencadeou o evento de controlo.

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

Ou utilizando Python:

     def control_event_handler(event: uno):
         oControl = CreateScriptService('SFDialogs.DialogEvent', event)
         # ...
  

Note-se que, nos exemplos anteriores, o prefixo "SFDialogs." pode ser omitido quando se considerar adequado.

Tratamento de exceções nos manipuladores de eventos

Ao criar um manipulador de eventos para eventos de controlo, é boa prática tratar os erros dentro da própria sub-rotina. Por exemplo, suponha que o manipulador de eventos abaixo é chamado quando se clica no botão.

    Sub OnButtonClicked(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oControl As Object
        oControl = CreateScriptService("DialogEvent", oEvent)
        ' Processar 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 da caixa de diálogo.

Em Python, utilize blocos try/except nativos para o tratamento de exceções, conforme ilustrado abaixo:

    def on_button_clicked(event=None):
        try:
            oControl = CreateScriptService("DialogEvent", event)
            # Processar o evento
        except Exception as e:
            # O objeto «bas» abaixo é uma instância do serviço Basic
            bas.MsgBox(str(e))
  

Tipos de controlo

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

O tipo de controlo TabPageContainer não está definido no Editor de Diálogos.

Propriedades

A propriedade Value

Não existe a propriedade Value para os controlos de diálogo GroupBox, Hyperlink, ImageControl e TreeControl.

Propriedades do evento

Dica: Todas as propriedades On… podem ser definidas programaticamente.
O exemplo Como apresentar dados num controlo de árvore na Wiki do LibreOffice ilustra isso mesmo.

A atribuição de eventos através do IDE Básico e a atribuição de eventos através de macros são mutuamente exclusivas.

Métodos

AddSubNode

Cria e devolve um novo nó do controlo de árvore como um objeto UNO subordinado a um nó pai. Consulte XMutableTreeNode na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.

Este método pode ser chamado antes de apresentar a caixa de diálogo, para construir a árvore inicial. Também pode ser chamado a partir de um evento de diálogo ou de controlo — utilizando o evento OnNodeExpanded — para completar a árvore dinamicamente.

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

parentnode: Um objeto UNO de nó, do tipo com.sun.star.awt.tree.XMutableTreeNode.

displayvalue: O texto que aparece na caixa de controlo em árvore.

datavalue: Qualquer valor associado ao novo nó. datavalue pode ser uma cadeia de caracteres, um número ou uma data. Omita o argumento quando não for aplicável.

LibreOffice Os exemplos básicos e em Python utilizam a caixa de diálogo myDialog do documento atual, proveniente da biblioteca Standard.

      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

Devolve True quando uma subárvore, subordinada a um nó pai, puder ser inserida com sucesso num controlo de árvore. Se o nó pai já tivesse nós filhos antes de se chamar este método, esses nós filhos são apagados.

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

parentnode: Um objeto UNO de nó, do tipo com.sun.star.awt.tree.XMutableTreeNode.

flattree: um array bidimensional ordenado pelas colunas que contêm os valores a apresentar. Esse array pode ser obtido através do método GetRows aplicado ao serviço SFDatabases.Database. Quando um elemento da matriz que contém o texto a apresentar é Empty ou Null, não é criado nenhum novo subnó e o restante da linha é ignorado.

      Á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 se utiliza o valor predefinido False, cada coluna de flattree contém o texto a apresentar no controlo de árvore. Quando True, os textos a exibir (displayvalue) encontram-se nas colunas 0, 2, 4, ... enquanto os valores dos dados (datavalue) se encontram 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

Devolve um novo nó raiz do controlo de árvore, como um objeto UNO de nó do tipo com.sun.star.awt.tree.XMutableTreeNode. A nova raiz da árvore é inserida abaixo dos nós raiz já existentes. Consulte XMutableTreeNode na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.

Este método pode ser chamado antes de apresentar a caixa de diálogo, para construir a árvore inicial. Também pode ser chamado a partir de um evento de uma caixa de diálogo ou de um controlo, para completar a árvore dinamicamente.

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

displayvalue: O texto que aparece na caixa de controlo em árvore.

      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 procura, de forma recursiva, a partir da raiz, um nó que cumpra determinados critérios. Basta uma correspondência: ou o seu valor de exibição corresponda ao padrão displayvalue, ou o seu valor de dados seja igual a datavalue. As comparações podem ou não distinguir maiúsculas de minúsculas. A primeira ocorrência correspondente é devolvida como um objeto UNO de nó do tipo com.sun.star.awt.tree.XMutableTreeNode. Consulte XMutableTreeNode na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.

Caso não seja encontrado, o método devolve Nothing, que deve ser verificado com a função incorporada IsNull().

Este método pode ser chamado antes de apresentar a caixa de diálogo, para construir a árvore inicial. Também pode ser chamado a partir de um evento de uma caixa de diálogo ou de um controlo.

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

É necessário especificar um dos argumentos displayvalue ou datavalue. Se ambos estiverem presentes, basta que um deles corresponda para selecionar o nó.

displayvalue: O padrão a ser comparado. Consulte o método SF_String.IsLike() para obter a lista de caracteres curinga possíveis. Quando for igual a uma cadeia de caracteres de comprimento zero (valor predefinido), este valor de exibição não é procurado.

distingue maiúsculas de minúsculas: O valor por predefiniçã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

Deslocar o canto superior esquerdo de um controlo de diálogo para novas coordenadas e/ou modificar as suas dimensões. Devolve True se o redimensionamento tiver sido bem-sucedido.

svc.Resize(opt Left: int, opt Top: int, opt Width: int, opt Height: int): bool

Todas as distâncias são expressas em unidades Map AppFont e são medidas a partir do canto superior esquerdo da caixa de diálogo principal. Sem argumentos, o método redimensiona o controlo para o seu «tamanho preferencial», um tamanho ajustado em função do seu conteúdo real. Os argumentos em falta permanecem inalterados.

Esquerda: A distância horizontal a partir do canto superior esquerdo

Topo: A distância vertical a partir do canto superior esquerdo

Largura: a largura horizontal do retângulo que contém o controlo

Altura: a altura vertical do retângulo que contém o controlo

      Dim oControl As Object
      Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")
      Set oControl = oDlg.Controls("thisControl")
      oControl.Resize(100, 200, Height:=6000) ' A largura permanece inalterada
    

      dlg = CreateScriptService('Dialog', None, None, 'myDialog')
      ctrl = dlg.Controls('thisControl')
      ctrl.Resize(300, 200, 1500)  # A altura permanece inalterada
    

SetFocus

Colocar o foco no controlo. Devolve True se o foco tiver sido estabelecido com sucesso.

Este método é frequentemente chamado a partir de um evento de caixa de diálogo ou de controlo.

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 TableControl com os dados fornecidos. Todos os dados já existentes são apagados antes da inserção dos novos dados passados como argumento.

Quando o TableControl é adicionado à caixa de diálogo, é possível utilizar o IDE do Basic para definir se os cabeçalhos das colunas e das linhas serão apresentados na tabela. Se o TableControl tiver cabeçalhos de colunas e/ou linhas, a primeira coluna e/ou linha do conjunto de dados fornecido são utilizadas como rótulos para os cabeçalhos da tabela.

Este método devolve True quando é bem-sucedido.

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

dataarray: Dados a introduzir na tabela, representados como um array de arrays em Basic ou uma tupla de tuplas em Python. Os dados devem incluir cabeçalhos de colunas e linhas, caso devam ser apresentados pelo TableControl.

larguras: Matriz que contém as larguras relativas de cada coluna. Por outras palavras, larguras = (1, 2) significa que a segunda coluna tem o dobro da largura da primeira. Se o número de valores na matriz for inferior ao número de colunas da tabela, então o último valor da matriz é utilizado para definir a largura das colunas restantes.

alinhamentos: Define o alinhamento em cada coluna como uma cadeia de caracteres em que cada caractere pode ser «L» (Esquerda), «C» (Centro), «R» (Direita) ou « » (espaço em branco, valor predefinido, o que significa alinhamento à esquerda para cadeias de caracteres e à direita para valores numéricos). Se o comprimento da cadeia de caracteres for inferior ao número de colunas da tabela, o último caractere da cadeia é utilizado para definir o alinhamento das colunas restantes.

RowHeaderWidth: largura da coluna do cabeçalho da linha, expressa em unidades Map AppFont. Valor predefinido = 10. O argumento é ignorado quando o TableControl não tem cabeçalho de linha.

O exemplo seguinte parte do princípio de que a caixa de diálogo myDialog possui um TableControl denominado Grid1, cujas propriedades «Mostrar cabeçalho de linha» e «Mostrar cabeçalho de coluna» estão definidas 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 devolve a linha selecionada na tabela. Se não estiver selecionada nenhuma linha, é devolvido um objeto Array vazio. O trecho de código seguinte mostra como verificar se está selecionada alguma linha na tabela.

     rowValues = oTable.Value
     If UBound(rowValues) < 0 Then
         MsgBox "Nenhuma 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 no final de um campo de texto com várias linhas. Será inserido um carácter de nova linha quando for necessário. O método devolve True em caso de sucesso.

É gerado um erro se o controlo em questão não for do tipo TextField ou não for multilinha.

svc.WriteLine(opt line: str): bool

Linha: A cadeia de caracteres a inserir. O valor predefinido é uma linha vazia.

      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 Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.