Conteúdo

# SFDocuments.FormControl serviço

O serviço FormControl permite aceder aos controlos que pertencem a um formulário, a um subformulário ou a um controlo de tabela de um FormDocument. Cada instância do serviço FormControl refere-se a um único controlo no formulário. Este serviço permite aos utilizadores:

- Obter e definir as propriedades do controlo representado pela instância FormControl.

- Aceda ao valor atual apresentado pelo controlo.

- Selecione o controlo pretendido.

Para utilizar o serviço FormControl num formulário, subformulário ou controlo de tabela específico, todos os controlos devem ter nomes únicos.

Os botões de opção que partilham o mesmo nome de grupo também devem ter nomes de controlo únicos.

O principal objetivo do serviço FormControl é definir e obter as propriedades e os valores apresentados pelos controlos num formulário.

Todos os controlos têm uma propriedade Value. No entanto, o seu conteúdo varia consoante o tipo de controlo. Para mais informações, consulte A propriedade Value abaixo.

Também é possível formatar os controlos através das propriedades XControlModel e XControlView.

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

## Chamada de serviço

Antes de utilizar o serviço FormControl, é 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 FormControl é invocado a partir de uma instância existente do serviço Form através do seu 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 aceder aos seus formulários, consulte a página de ajuda do serviço SFDocuments.Form.

Em alternativa, é possível recuperar uma instância de FormControl através do serviço SFDocuments.FormEvent, que devolve a instância da classe SFDocuments.FormControl que desencadeou o evento.

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

##### Em Python

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

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

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

## Tipos de controlo

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

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

## Características

Nome | Readonly | Tipo | Aplicável a | Descrição
--- | --- | --- | --- | ---
Action | Não | String | Button | Especifica a ação desencadeada quando se clica no botão. Os valores aceites são: none, submitForm, resetForm, refreshForm, moveToFirst, moveToLast, moveToNext, moveToPrev, saveRecord, moveToNew, deleteRecord, undoRecord.
Caption | Não | String | Button, CheckBox, FixedText, GroupBox, RadioButton | Especifica o texto apresentado pelo controlo.
ControlSource | Sim | String | CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField | Especifica o campo do conjunto de linhas mapeado para o controlo atual.
ControlType | Sim | String | Todos | Um dos tipos de controlo acima referidos.
Default | Não | Boolean | Button | Especifica se um botão de comando é o botão «OK» predefinido.
DefaultValue | Não | Variant | CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Especifica o valor predefinido utilizado para inicializar um controlo num novo registo.
Enabled | Não | Boolean | Todos (exceto HiddenControl) | Especifica se o controlo é acessível com o cursor.
Format | Não | String | DateField, TimeField, FormattedField (read-only) | Especifica o formato utilizado para apresentar datas e horas. Deve ser uma das seguintes 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 | Devolve o número de linhas numa ListBox ou numa ComboBox.
ListIndex | Não | Long | ComboBox, ListBox | Especifica qual o item selecionado numa ListBox ou ComboBox. No caso de seleção múltipla, é devolvido o índice do primeiro item ou é definido apenas um item.
ListSource | Não | Variant | ComboBox, ListBox | Especifica os dados contidos numa ComboBox ou numa ListBox como uma matriz de valores de cadeia de caracteres com índice a partir de zero. Quando combinado com ListSourceType, pode também conter o nome de uma tabela, uma consulta ou uma instrução SQL completa.
ListSourceType | Não | Integer | ComboBox, ListBox | Especifica o tipo de dados contidos numa caixa de combinação ou numa caixa de lista. Deve ser uma das constantes com.sun.star.form.ListSourceType.*.
Locked | Não | Boolean | ComboBox, CurrencyField, DateField, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField | Especifica se o controlo é de leitura apenas.
MultiSelect | Não | Boolean | ListBox | Especifica se o utilizador pode selecionar vários itens numa caixa de lista.
Name | Sim | String | Todos | O nome do controlo.
Parent | Sim | Object | Todos | Dependendo do tipo de elemento pai — um formulário, um subformulário ou um controlo de tabela —, devolve a instância do objeto da classe SFDocuments.Form ou SFDocuments.FormControl.
Picture | Não | String | Button, ImageButton, ImageControl | Especifica o nome do ficheiro que contém um bitmap ou outro tipo de imagem a ser apresentado no controlo. O nome do ficheiro deve estar em conformidade com o atributo FileNaming do serviço ScriptForge.FileSystem.
Required | Não | Boolean | CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField | Diz-se que um controlo é obrigatório quando os dados subjacentes não podem conter um valor null.
Text | Sim | String | ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField | Permite aceder ao texto que está a ser apresentado pelo controlo.
TipText | Não | String | Todos (exceto o HiddenControl) | Especifica o texto que aparece como dica de ferramenta quando se passa 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.
Value | Não | Variant |  | Esta propriedade depende do tipo de controlo atual. Consulte A propriedade Value para obter mais informações.
Visible | Não | Boolean | Todos (exceto o HiddenControl) | 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 UnoControlModel na documentação da API para obter mais informações.
XControlView | Sim | Objeto UNO | Todos | O objeto UNO que representa a vista de controlo. Consulte XControl e UnoControl na documentação da API para obter mais informações.

## A propriedade Value

Tipo de controlo | Tipo | Descrição
--- | --- | ---
Button | Boolean | Aplicável apenas a botões de alternância.
CheckBox | Booleano ou Inteiro | 0, Falso: não marcado 1, Verdadeiro: marcado 2: desativado (a cinzento), não sei (aplicável se TripleState for True)
ComboBox | String | O valor selecionado, na forma de uma cadeia de caracteres. A propriedade ListIndex é uma opção alternativa para aceder ao índice do valor selecionado.
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 |
HiddenControl | String |
ListBox | Cadeia de caracteres ou matriz de cadeias de caracteres | A(s) linha(s) selecionada(s) como uma única cadeia de caracteres ou um conjunto de cadeias de caracteres. Só é possível definir um único valor. Se a caixa estiver ligada a uma base de dados, esta propriedade obtém ou define os dados subjacentes. Caso contrário, obtém ou define os dados que estão a ser apresentados.
NumericField | Numérico |
PatternField | String |
RadioButton | Boolean | Cada botão tem o seu próprio nome. Vários controlos RadioButton ficam ligados entre si quando partilham o mesmo nome de grupo. Se um RadioButton for definido como True, os outros botões relacionados são automaticamente definidos como False
ScrollBar | Numérico | Tem de estar dentro dos limites predefinidos
SpinButton | Numérico | Tem de estar dentro dos limites predefinidos
TextField | String | O texto que aparece no campo
TimeField | Date |

## Propriedades do evento

As propriedades abaixo devolvem ou definem cadeias de caracteres URI que definem o script acionado pelo evento.

Nome | Somente leitura | Descrição tal como consta no IDE Básico
--- | --- | ---
OnActionPerformed | Não | Executar ação
OnAdjustmentValueChanged | Não | Enquanto se faz o ajuste
OnApproveAction | Não | Aprovar ação
OnApproveReset | Não | Antes da reinicialização
OnApproveUpdate | Não | Antes de atualizar
OnChanged | Não | Alterado
OnErrorOccurred | Não | Ocorreu um erro
OnFocusGained | Não | Ao receber o foco
OnFocusLost | Não | Quando se perde a concentração
OnItemStateChanged | Não | O estado do artigo foi alterado
OnKeyPressed | Não | Tecla premida
OnKeyReleased | Não | Chave libertada
OnMouseDragged | Não | O rato moveu-se enquanto se premiam as teclas
OnMouseEntered | Não | Rato lá dentro
OnMouseExited | Não | Rato lá fora
OnMouseMoved | Não | O rato moveu-se
OnMousePressed | Não | Botão do rato premido
OnMouseReleased | Não | Botão do rato solto
OnResetted | Não | Após a reinicialização
OnTextChanged | Não | Texto alterado
OnUpdated | Não | Após a atualização

Para saber mais sobre cadeias de caracteres URI, consulte a Especificação de URI do Scripting Framework.

Lista de métodos do serviço FormControl
Controls | SetFocus

## Controls

Este método aplica-se apenas a controlos do tipo TableControl. O valor devolvido depende dos argumentos fornecidos.

Se o argumento opcional controlname não for fornecido, é devolvido um array com índice a partir de zero que contém os nomes de todos os controlos.

Por outro lado, se for fornecido um controlname, o método devolve uma instância da classe FormControl correspondente ao controlo especificado.

### Sintaxe:

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

svc.Controls(controlname: str): svc

### Parâmetros:

controlname: Um nome de controlo válido, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas. Se não for indicado, a lista de nomes de controlos é devolvida como um array com índice a partir de zero.

### Exemplo:

          Dim myGrid As Object, myList As Variant, myControl As Object
          Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl
          ' Devolve um array com os nomes de todos os controlos em «myTableControl»
          myList = myGrid.Controls()
          ' Devolve uma instância da classe FormControl correspondente a «myCheckBox»
          Set myControl = myGrid.Controls("myCheckBox")

Utilizando Python:

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

## SetFocus

Coloca 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 formulário ou de controlo.

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

Seguem-se dois exemplos que ilustram a utilização do serviço FormControl.

O primeiro exemplo lê o valor atual de uma ComboBox que contém nomes de cidades e insere-o num controlo FixedTest num Form:

         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 aos do 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 seguinte fragmento de código pode ser utilizado para processar controlos RadioButton que partilham o mesmo nome de grupo. Neste exemplo, suponha que existem três botões de opção com os nomes optA, optB e optC e que pretendemos apresentar o texto do controlo selecionado.

         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 aos do 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 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

Serviço.ScriptForge Basic

SFDocuments.Form serviço

SFDocuments.Document serviço

Necessitamos da sua ajuda!