Serviço SFDialogs.DialogControl

Conteúdo

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

• Button • CheckBox • ComboBox • CurrencyField • DateField • FileControl | • FixedLine • FixedText • FormattedField • GroupBox • Hyperlink • ImageControl | • ListBox • NumericField • PatternField • ProgressBar • RadioButton • ScrollBar | • TableControl • TabPageContainer • TextField • TimeField • TreeControl

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

## Propriedades

Nome | Somente leitura | Tipo | Aplicável a | Descrição
--- | --- | --- | --- | ---
Border | Sim | String | Button, … | A propriedade Border refere-se à moldura do controlo: «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 ao controlo.
ControlType | Sim | String | Todos | Um dos tipos acima referidos.
CurrentNode | Não | Objeto UNO | TreeControl | O nó atualmente selecionado no topo do controlo de árvore. Consulte XmutableTreeNode na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
Default | Não | Boolean | Button | Especifica se um botão de comando é o botão predefinido (OK).
Enabled | Não | Boolean | Todos | Especifica se o controlo é acessível com o cursor.
Format | Não | String | DateField, TimeField, FormattedField (somente leitura) | Especifica o formato utilizado para apresentar datas e horas. Deve ser uma destas cadeias de caracteres: Para datas: «Padrão (curto)», «Padrão (curto AA)», «Padrão (curto AAAA)», «Padrão (longo)», «DD/MM/AA», «MM/DD/AA», «AA/MM/DD», «DD/MM/AAAA», «MM/DD/AAAA», «AAAA/MM/DD», «AA-MM-DD», «AAAA-MM-DD». Para os horários: «24h curto», «24h longo», «12h curto», «12h longo».
ListCount | Sim | Long | ComboBox, ListBox, TableControl | Especifica o número de linhas numa ListBox, numa ComboBox ou num TableControl.
ListIndex | Não | Long | ComboBox, ListBox, TableControl | Especifica qual o elemento selecionado numa ListBox, numa ComboBox ou num TableControl.
Locked | Não | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, TextField, TimeField | Especifica se o controlo é de leitura apenas.
MultiSelect | Não | Boolean | ListBox | Especifica se um utilizador pode efetuar várias seleções numa caixa de lista.
Name | Sim | String | Todos | O nome do controlo.
Page | Não | Integer | Todos | Uma caixa de diálogo pode ter várias páginas que o utilizador pode percorrer passo a passo. A propriedade Page do objeto Dialog define qual a página da caixa de diálogo que está ativa. A propriedade Page de um controlo define a página da caixa de diálogo na qual o controlo está visível.
Parent | Sim | Diálogo serviço | Todos | A instância do objeto da classe pai SFDialogs.Dialog.
Picture | Não | String | Button, ImageControl | Especifica o nome do ficheiro que contém um bitmap ou outro tipo de imagem a ser apresentado no controlo especificado. O nome do ficheiro deve estar em conformidade com o atributo FileNaming do serviço ScriptForge.FileSystem.
RootNode | Sim | UNO objeto | TreeControl | Um objeto que representa o nó raiz mais baixo (normalmente existe apenas um nó raiz deste tipo). Consulte XmutableTreeNode na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
RowSource | Não | Array of strings | ComboBox, ListBox | Especifica os dados contidos numa caixa de combinação ou numa caixa de lista.
TabIndex | Sim | Numeric | All | A propriedade TabIndex especifica a posição de um controlo na ordem de tabulação da caixa de diálogo.
Text | Sim | String | ComboBox, FileControl, FormattedField, PatternField, TextField | Permite aceder ao texto que está a ser apresentado pelo controlo.
TipText | Não | String | Todos | Especifica o texto que aparece como dica de ferramenta quando se mantém o ponteiro do rato sobre o controlo.
TripleState | Não | Boolean | CheckBox | Especifica se o controlo de caixa de seleção pode aparecer esbatido (a cinzento) ou não.
URL | Não | String | Hyperlink | O URL a abrir quando se clicar no controlo.
Value | Não | Variant |  | Consulte Propriedade «Value»
Visible | Não | Boolean | Todos | Especifica se o controlo está oculto ou visível.
XControlModel | Sim | Objeto UNO | Todos | O objeto UNO que representa o modelo de controlo. Consulte XControlModel e UnoControlDialogModel na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
XControlView | Sim | Objeto UNO | Todos | O objeto UNO que representa a vista de controlo. Consulte XControl e UnoControlDialog na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
XTreeDataModel | Sim | Objeto UNO | TreeControl | O objeto UNO que representa o modelo de dados do controlo em árvore. Consulte XMutableTreeDataModel na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
XGridColumnModel | Sim | Objeto UNO | TableControl | O objeto UNO que representa o modelo de dados do controlo de tabela. Consulte XGridColumnModel na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
XGridDataModel | Sim | Objeto UNO | TableControl | O objeto UNO que representa o modelo de dados do controlo de grelha. Consulte XGridDataModel na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.

## A propriedade Value

Tipo de controlo | Tipo | Descrição
--- | --- | ---
Button | Boolean | Apenas para botões de alternância
CheckBox | Booleano ou Inteiro | 0, Falso: não marcado 1, Verdadeiro: marcado 2: a cinzento, não sei
ComboBox | String | O valor selecionado. A propriedade ListIndex é uma opção alternativa.
CurrencyField | Numérico |
DateField | Date |
FileControl | String | Um nome de ficheiro formatado de acordo com a propriedade FileNaming do serviço ScriptForge.FileSystem
FormattedField | Texto ou numérico |
ListBox | Cadeia de caracteres ou matriz de cadeias de caracteres | A(s) linha(s) selecionada(s) como um valor escalar ou como uma matriz, dependendo do atributo MultiSelect
NumericField | Numérico |
PatternField | String |
ProgressBar | Numérico | Tem de estar dentro dos limites predefinidos
RadioButton | Boolean | Cada botão tem o seu próprio nome. Estão interligados se as suas posições no TAB forem contíguas. Se um botão de opção estiver definido como True, os outros botões relacionados são automaticamente definidos como False
ScrollBar | Numérico | Tem de estar dentro dos limites predefinidos
TabPageContainer | Numeric | Uma caixa de diálogo pode ter vários separadores numerados, identificáveis ou modificáveis através da sua propriedade Value.
TableControl | Array | Matriz unidimensional com os dados da linha atualmente selecionada.
TextField | String | O texto que aparece no campo
TimeField | Date |

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

## Propriedades do evento

As propriedades de evento On… são cadeias de caracteres URI que fazem referência a um script acionado por um evento. Consulte a respetiva especificação na especificação URI da estrutura de scripting.

Nome (ligação para a API do evento) | Descrição tal como consta no IDE Básico
--- | ---
OnActionPerformed | Executar ação
OnAdjustmentValueChanged | Enquanto se faz o ajuste
OnFocusGained | Ao receber o foco
OnFocusLost | Quando se perde a concentração
OnItemStateChanged | O estado do artigo foi alterado
OnKeyPressed | Tecla premida
OnKeyReleased | Chave libertada
OnMouseDragged | O rato moveu-se enquanto se premiam as teclas
OnMouseEntered | Rato lá dentro
OnMouseExited | Rato lá fora
OnMouseMoved
OnMousePressed | Botão do rato premido
OnMouseReleased | Botão do rato solto
OnNodeExpanded | (Não no IDE Basic) quando se clica no botão de expansão de um nó num controlo de árvore
OnNodeSelected | (Não no IDE do Basic) quando um nó num controlo de árvore é selecionado
OnTabSelected | (Não no IDE do Basic) quando é selecionada uma separador num controlo TabPage
OnTextChanged | Texto alterado

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

Lista de métodos do serviço DialogControl
AddSubNode AddSubTree CreateRoot | FindNode Resize SetFocus | SetTableData WriteLine

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

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

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

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

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.

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.

### Sintaxe:

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

### Parâmetros:

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

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

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.

### Sintaxe:

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

### Parâmetros:

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.

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

### Sintaxe:

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

### Parâmetros:

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

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.

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

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

### Sintaxe:

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

### Parâmetros:

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

### Exemplo:

##### Em Basic

          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

##### Em Python

          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.

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

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

##### Em Basic

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

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

### Sintaxe:

svc.WriteLine(opt line: str): bool

### Parâmetros:

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

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

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.

Tópicos relacionados

SFDialogs.Dialog serviço

ScriptForge.String service

ScriptForge.UI service

Necessitamos da sua ajuda!