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.

tip

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:

note

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

Alternativamente, uma instância de controle pode ser obtida usando o serviço SFDialogs.DialogEvent, desde que a caixa de diálogo tenha sido inicializada usando o serviço Dialog. DialogEvent retorna uma instância da classe SFDialogs.DialogControl que disparou o 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)
         # ...
   

Note que nos exemplos anteriores o prefixo "SFDialogs." pode ser omitido.

Tipos de Controles

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

Propriedades

Nome

Somente leitura

Tipo

Aplicável a

Descrição

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, RadioButton

Especifica o texto associado com o controle.

ControlType

Sim

String

Todos

Um dos tipos listados acima.

CurrentNode

Não

Objeto
UNO

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
Dialog

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
UNO

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.

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

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
UNO

Todos

Objeto UNO representando o modelo do controle. Consulte XControlModel e UnoControlDialogModel na documentação da API para mais detalhes.

XControlView

Sim

Objeto
UNO

Todos

Objeto UNO representando a visualização do controle. Consulte XControl e UnoControlDialog na documentação da API para mais detalhes.

XTreeDataModel

Sim

Objeto
UNO

TreeControl

Objeto UNO representando o modelo de dados do controle de Árvore. Consulte a documentação API XMutableTreeDataModel para maiores detalhes.


A propriedade Value

Tipo do Controle

Tipo

Descrição

Button

Boolean

Apenas para botões de ativação

CheckBox

Boolean ou Integer

0, False: não ativado
1, True: ativado
2: cinza, não sabe

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


Propriedades de Evento

Retorna uma String URI com a referência para o script disparado pelo evento. Leia sua especificação na página Scripting Framework.

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


Métodos

Lista de Métodos no Serviço DialogControl

AddSubNode
AddSubTree
CreateRoot

FindNode
SetFocus

SetTableData
WriteLine


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.

Sintaxe:

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

Parâmetros:

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.

Exemplo:

Os exemplos em LibreOffice Basic e Python acessam o diálogo myDialog da biblioteca Standard do documento atual.

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

     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.

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.

Sintaxe:

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

Parâmetros:

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

Exemplo:

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

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.

Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

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

     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.

Sintaxe:

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

Parâmetros:

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.

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.

casesensitive: O valor padrão é False

Exemplo:

Em Basic

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

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

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.

Sintaxe:

svc.SetFocus(): bool

Exemplo:

Em Basic

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

      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.

Sintaxe:

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

Parâmetros:

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 = Array(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.

Exemplo:

Em Basic

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

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.

Sintaxe:

svc.WriteLine(opt line: str): bool

Parâmetros:

Line: String a ser inserida. O valor padrão é uma linha em branco.

Exemplo:

Em Basic

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

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

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.


♥ Doe para nosso projeto! ♥