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.

Serviço.ScriptForge Basic

SFDocuments.Form serviço

SFDocuments.Document serviço