Sumário

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

Tópicos relacionados

Serviço ScriptForge.Basic

Serviço SFDocuments.Form

Serviço SFDocuments.Document