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:

Obter e definir as propriedades do controle representado pela instância FormControl.
Acessa o valor atual mostrado pelo controle.
Coloca o foco no controle desejado.

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.

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.

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

Invocação do serviço

Antes de utilizar o serviço FormControl, a biblioteca ScriptForge precisa ser carregada ou importada:

• 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 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
      bas = CreateScriptService('ScriptForge.Basic')
      doc = CreateScriptService('SFDocuments.Document', bas.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())

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.

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:

Button
CheckBox
ComboBox
CurrencyField
DateField
FileControl
FixedText
FormattedField
GroupBox
HiddenControl
ImageButton
ImageControl
ListBox
NavigationBar
NumericField
PatternField
RadioButton
ScrollBar
SpinButton
TableControl
TextField
TimeField

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 caixa de seleção pode ou não aparecer esmaecido (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

Para aprender mais sobre Strings URI leia a página Scripting Framework URI Specification.

Lista de Métodos no Serviço FormControl
Controls	SetFocus

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


     bas = CreateScriptService('ScriptForge.Basic')
     doc = CreateScriptService('SFDocuments.Document', bas.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


     bas = CreateScriptService('ScriptForge.Basic')  # Métodos semelhantes ao Basic
     doc = CreateScriptService('SFDocuments.Document', bas.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


     bas = CreateScriptService('ScriptForge.Basic')  # Métodos semelhantes ao Basic
     doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)
     form = doc.Forms('formDocumentName', 'formName')
     radio_buttons = ['optA', 'optB', 'optC']
     for name in radio_buttons:
        control = form.controls(name)
        if control.Value == True:
           bas.MsgBox('Opção selecionada: ' + control.Caption)
           break

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.

Serviço ScriptForge.Basic

Serviço SFDocuments.Form

Serviço SFDocuments.Document