Ajuda do LibreOffice 25.2
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.
Antes de utilizar o serviço FormControl, a biblioteca ScriptForge precisa ser carregada ou importada:
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()
   
      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
   
      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.
O serviço FormControl está disponível para os seguintes tipos de controles:
| Button | GroupBox | PatternField | 
| 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 | 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 | Todos | Objeto UNO representando a visualização do controle. Consulte XControl eUnoControl na documentação da API para maiores informações. | 
| 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 | 
| 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 | 
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 | |
|---|---|
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.
svc.Controls(): str[0..*]
svc.Controls(controlname: str): svc
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.
      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
   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.
svc.SetFocus(): bool
      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()
   
     bas = CreateScriptService('ScriptForge.Basic')
     doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)
     form = doc.Forms(0)
     control = form.Controls('thisControl')  # SFDocuments.FormControl
     control.SetFocus()
   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
   
     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
   
     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