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

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.

note

Esta propriedade está disponível a partir do LibreOffice 7.2 em diante.


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

Especifica o número de linhas em uma Combo Box ou List Box.

ListIndex

Não

Long

ComboBox, ListBox

Item selecionado em uma List Box ou Combo Box.

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.

note

Esta propriedade está disponível a partir do LibreOffice 7.2 em diante.


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 Check Box pode ou não aparecer ofuscado (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.

note

Esta propriedade está disponível a partir do LibreOffice 7.2 em diante.



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

TextField

String

Texto sendo apresentado no campo

TimeField

Date


Propriedades de Evento

Retorna uma String URI com as referências para o script disparado pelo evento. Leia sua especificação na página Especificação do Framework URI.

note

Estas propriedades de evento estão disponíveis a partir do LibreOffice 7.2 em diante.


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
WriteLine


note

Estes métodos estão disponíveis a partir do LibreOffice 7.2 em diante.


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.


      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.

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:


      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.

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:


      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.

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:


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

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:


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

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


      oControl.WriteLine([Line As String]) As Boolean
   

Parâmetros:

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

Exemplo:


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

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.


♥ Doe para nosso projeto! ♥