Serviço SFDocuments.FormControl

O serviço FormControl provê acesso aos controles que pertencem a um formulário, subformulário ou controle de tabela de um FormDocument. Cada instância do serviço FormControl se refere a um único controle no formulário. Este serviço permite:

Para usar o serviço FormControl em um formulário, subformulário ou controle de tabela em particular, todos os controles devem ter nomes únicos.

warning

Botões de opção que compartilham o mesmo nome de grupo também devem ter nomes de controle únicos.


O propósito principal do serviço FormControl é obter e definir propriedades e valores mostrados pelos controles em um formulário.

Todos os controles têm a propriedade Value. Contudo, seu conteúdo variará de acordo com o tipo de controle. Para maiores informações, leia A propriedade Value abaixo.

Também é possível formatar os controles usando as propriedades XControlModel eXControlView.

tip

O serviço SFDocuments.FormControl está intimamente relacionado com o serviço SFDocuments.Form.


note

Este serviço está disponível a partir do LibreOffice 7.2 em diante.


Invocando o Serviço

O serviço FormControl é invocado a partir de uma instância existente do serviço Form através do método Controls.


      Dim oDoc as Object, myForm As Object, myControl As Object
      Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
      Set myForm = oDoc.Forms("formDocumentName", "formName") ' SFDocuments.Form
      Set myControl = myForm.Controls("myTextBox") ' SFDocuments.FormControl
      myControl.Value = "Current time = " & Now()
   
Em Python

      

from scriptforge import CreateScriptService

from time import localtime, strftime svc = CreateScriptService('ScriptForge.Basic')

doc = CreateScriptService('SFDocuments.Document', svc.ThisDatabaseDocument)

form = doc.Forms('formDocumentName', 'formName') # SFDocuments.Form

control = form.Controls('myTextBox') # SFDocuments.FormControl

control.Value = 'Hora atual = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())
tip

Para saber mais sobre como abrir um FormDocument e acessar seus formulários, consulte a página de ajuda SFDocuments.Form.


Alternativamente, uma instância FormControl pode ser obtida usando o serviço SFDocuments.FormEvent, o qual retorna uma instância da classe SFDocuments.FormControl que disparou o evento.


      Sub OnEvent(ByRef poEvent As Object)
          Dim oControl As Object
          Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)
          ' oControl agora representa a instância da classe FormControl representando o controle que disparou o evento atual
          ' ...
      End Sub
   
Em Python

      def onEvent(event: uno):
          control = CreateScriptService('SfDocuments.FormEvent', event)
   

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

note

O serviço FormEvent é usado exclusivamente para criar instâncias dos serviços SFDocuments.Form e SFDocuments.FormControl quando um evento de formulário ou controle ocorrer.


Tipos de Controles

O serviço FormControl está disponível para os seguintes tipos de controles:

Propriedades

Nome

Somente leitura

Tipo

Aplicável a

Descrição

Action

Não

String

Button

Especifica a ação disparada quando o botão é clicado. Os seguintes valores são aceitos: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord.

Caption

Não

String

Button, CheckBox, FixedText, GroupBox, RadioButton

Especifica o texto a ser mostrado no controle.

ControlSource

Sim

String

CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField

Especifica o campo do conjunto de registros a ser mapeado no controle atual.

ControlType

Sim

String

Todos

Um dos tipos de controle listados acima.

Default

Não

Boolean

Button

Especifica se um botão de comando é o botão OK padrão.

DefaultValue

Não

Variant

CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField

Especifica o valor padrão usado para inicializar o controle em um novo registro.

Enabled

Não

Boolean

Todos (exceto em um HiddenControl)

Especifica se o controle é acessível com o cursor.

Format

Não

String

DateField, TimeField, FormattedField (read-only)

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

Retorna o número de linhas em um ListBox ou em um ComboBox.

ListIndex

Não

Long

ComboBox, ListBox

Especifica qual item está selecionado em um ListBox ou em um ComboBox. Em casos de seleções múltiplas, o índice do primeiro item é retornado ou apenas um item é definido.

ListSource

Não

Variant

ComboBox, ListBox

Especifica os dados contidos em um ComboBox ou em um ListBox como um Array de Strings indexado em zero.

Quando combinado com ListSourceType, pode também conter o nome de uma tabela, consulta ou um comando SQL completo.

ListSourceType

Não

Integer

ComboBox, ListBox

Especifica o tipo de dados contido em um ComboBox ou em um ListBox.

Deve ser uma das constantes definidas em com.sun.star.form.ListSourceType.*.

Locked

Não

Boolean

ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField

Especifica se o controle é somente leitura.

MultiSelect

Não

Boolean

ListBox

Especifica se o usuário pode selecionar múltiplos itens em um ListBox.

Name

Sim

String

Todos

Nome do controle.

Parent

Sim

Object

Todos

Dependendo do tipo do pai, um formulário, subformulário ou controle de tabela, retorna a instância da classe SFDocuments.Form ou SFDocuments.FormControl.

Picture

Não

String

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

Required

Não

Boolean

CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField

Um controle é considerado como requerido quando os dados associados não podem conter o valor null.

Text

Sim

String

ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField

Dá acesso ao texto sendo apresentado pelo controle.

TipText

Não

String

Todos (exceto HiddenControl)

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

Esta propriedade depende do tipo do controle atual. Consulte A propriedade Value para maiores informações.

Visible

Não

Boolean

Todos (exceto HiddenControl)

Especifica se o controle está oculto ou visível.

XControlModel

Sim

Objeto
UNO

Todos

Objeto UNO representando o modelo do controle. Consulte a documentação da API de XControlModel e UnoControlModel para maiores informações.

XControlView

Sim

Objeto
UNO

Todos

Objeto UNO representando a visualização do controle. Consulte XControl eUnoControl na documentação da API para maiores informações.


A Propriedade Value

Tipo de controle

Tipo

Descrição

Button

Boolean

Aplicável apenas a botões de alternância.

CheckBox

Boolean ou Integer

0, False: não marcado
1, True: marcado
2: cinza, não sabe (aplicável se TripleState for True)

ComboBox

String

O valor selecionado, como uma String. A propriedade ListIndex é uma opção alternativa para acessar o índice do valor selecionado.

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

HiddenControl

String

ListBox

String ou array de strings

Linha(s) selecionada(s) como uma string ou um array de strings. Apenas um valor único pode ser definido. Se a caixa estiver lidada a um banco de dados, esta propriedade obtém ou define os dados associados. Caso contrário, ela obtém ou define o valor sendo mostrado.

NumericField

Numérico

PatternField

String

RadioButton

Boolean

Cada botão tem seu próprio nome. Múltiplos controles RadioButton são relacionados quando compartilham o mesmo nome de grupo. Se um RadioButton estiver definido como True, todos os outros botões relacionados serão automaticamente definidos como False.

ScrollBar

Numérico

Deve estar dentro dos limites pré-definidos

SpinButton

Numérico

Deve estar dentro dos limites pré-definidos

TextField

String

Texto sendo apresentado no campo

TimeField

Date


Propriedades de evento

As propriedades abaixo retornam ou definem uma string URI que determinam o script a ser executado pelo evento.

Nome

Somente leitura

Descrição usada pela IDE Basic

OnActionPerformed

Não

Executar ação

OnAdjustmentValueChanged

Não

Ao ajustar

OnApproveAction

Não

Aprovar ação

OnApproveReset

Não

Antes de redefinir

OnApproveUpdate

Não

Antes de atualizar

OnChanged

Não

Quando alterado

OnErrorOccurred

Não

Ao ocorrer um erro

OnFocusGained

Não

Ao receber o foco

OnFocusLost

Não

Ao perder o foco

OnItemStateChanged

Não

Ao alterar o estado do item

OnKeyPressed

Não

Tecla pressionada

OnKeyReleased

Não

Tecla liberada

OnMouseDragged

Não

Mouse movido com tecla pressionada

OnMouseEntered

Não

Mouse dentro

OnMouseExited

Não

Mouse fora

OnMouseMoved

Não

Mouse movido

OnMousePressed

Não

Botão do mouse pressionado

OnMouseReleased

Não

Botão do mouse liberado

OnResetted

Não

Após redefinir

OnTextChanged

Não

Texto·modificado

OnUpdated

Não

Após atualizar


tip

Para saber mais sobre strings URI, consulte a página Scripting Framework URI Specification no Wiki.


Lista de Métodos no Serviço FormControl

Controls

SetFocus


note

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


Controls

Este método é aplicável apenas a controles do tipo TableControl. O valor retornado depende dos argumentos fornecidos.

Se o argumento opcional controlname estiver ausente, então um Array baseado em zero contendo os nomes de todos os controles é retornado.

Por outro lado, se um controlname é fornecido, o método retorna uma instância de classe FormControl correspondente ao controle especificado.

Sintaxe:

svc.Controls(): str[0..*]

svc.Controls(controlname: str): svc

Parâmetros:

controlname: String sensível à caixa com o nome válido de um controle. Se não for especificado, a lista de nomes de controles é retornada em um Array indexado em zero.

Exemplo:


      Dim myGrid As Object, myList As Variant, myControl As Object
      Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
      ' Retorna um Array com os nomes de todos os controles em "myTableControl"
      myList = myGrid.Controls()
      

' Retorna uma instância da classe FormControl correspondente ao controle "myCheckBox"

Set myControl = myGrid.Controls("myCheckBox")

Usando Python:


      grid = form.Controls('myTableControl')  # SFDocuments.FormControl
      control_names = form.Controls()
      control = grid.Controls('myCheckBox')  # SFDocuments.FormControl
   

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 formulário ou por um evento de controle em um formulário.

Sintaxe:

svc.SetFocus(): bool

Exemplo:


      Dim oDoc As Object, oForm As Object, oControl As Object
      Set oDoc = CreateScriptService("SFDocuments.Document", ThisComponent)
      Set oForm = oDoc.Forms(0)
      Set oControl = oForm.Controls("thisControl") ' SFDocuments.FormControl
      oControl.SetFocus()
   
Em Python

     ui = CreateScriptService('ScriptForge.Basic')
     doc = CreateScriptService('SFDocuments.Document', ui.ThisComponent)
     form = doc.Forms(0)
     control = form.Controls('thisControl')  # SFDocuments.FormControl
     control.SetFocus()
   

Exemplos adicionais

Abaixo são dados dois exemplos que ilustram o uso do serviço FormControl.

O primeiro exemplo lê o valor atual em um ComboBox contendo nomes de cidades e escreve-o em um controle do tipo Rótulo em um formulário.


     Dim oDoc as Object, myForm as Object, myControl as Object
     Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
     myForm = oDoc.Forms("formDocumentName", "formName")
     Dim lbCity : lbCity = myForm.Controls("labelCity")
     Dim cbCity : cbCity = myForm.Controls("comboboxCity")
     lbCity.Caption = "Selected City: " & cbCity.Value
   
Em Python

     ui = CreateScriptService('ScriptForge.Basic')  # Fornece métodos do Basic
     doc = CreateScriptService('SFDocuments.Document', ui.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     lbl_city = form.Controls('labelCity')
     combo_city = form.Controls('comboboxCity')
     lbl_city.Caption = "Cidade selecionada: " + combo_city.Value
   

O trecho de código abaixo pode ser usado para processar Botões de Opção que compartilham o mesmo nome de grupo. Neste exemplo, imagine que há três botões de opção com os nomes optA, optB eoptC e você deseja mostrar o rótulo da opção selecionada.


     Dim oDoc as Object, myForm as Object
     Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)
     myForm = oDoc.Forms("formDocumentName", "formName")
     Dim optNames As Object : optNames = Array("optA", "optB", "optC")
     Dim optControl as Object, opt as Variant
     For Each opt In optNames
         optControl = myForm.Controls(opt)
         If optControl.Value = True Then
             MsgBox "Opção selecionada: " & optControl.Caption
             Exit For
         End If
     Next opt
   
Em Python

     ui = CreateScriptService('ScriptForge.Basic')  # Fornece métodos do Basic
     doc = CreateScriptService('SFDocuments.Document', ui.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     radio_buttons = ['optA', 'optB', 'optC']
     for name in radio_buttons:
        control = form.controls(name)
        if control.Value == True:
           ui.MsgBox('Opção selecionada: ' + control.Caption)
           break
   
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! ♥