Ajuda do LibreOffice 24.8
O serviço Form fornece métodos e propriedades para gerenciar formulários em documentos do LibreOffice. Este serviço suporta formulários de documentos Base, Calc e Writer e permite:
Abrir e ativar formulários.
Navegar pelos registros mostrados no formulário.
Acessar os controles do formulário.
Acessar os subformulários de um formulário pai.
O serviço SFDocuments.Form está disponível a partir do LibreOffice 7.2.
Formulários são geralmente usados em documentos do LibreOffice para criar interfaces de usuário conectadas a bancos de dados relacionais. Assim, o serviço Form fornece acesso rápido à base de dados associada através do serviço SFDatabases.Database.
O serviço SFDocuments.Form está intimamente relacionado com o serviço SFDocuments.FormControl.
Formulários são geralmente criados em documentos Base, mas também podem ser adicionados a documentos Writer e Calc.
No Base, cada formulário criado com a funcionalidade ou através do Assistente de Formulários é na verdade um FormDocument (documento de formulário) que pode ser manuseado com o serviço Form. Documentos Base podem conter uma quantidade ilimitada de documentos de formulário.
Abaixo é dado um exemplo ilustrando a hierarquia de todos os elementos envolvidos ao acessar formulários e subformulários em um documento Base. Imagine que você tem um arquivo Base com o nome Employees.odb e dentro dele você criou um documento de formulário para adicionar novos funcionários ao banco de dados. O documento de formulário contém um formulário principal com o nome EmployeeData que dá acesso à tabela. Há também um subformulário WorksAtPlant que permite associar o novo empregado a uma das instalações da empresa.
    Employees.odb (documento Base)
     |
     |-- AddEmployee (FormDocument)
          |
          |-- EmployeeData (Formulário principal)
               |
               |-- WorksAtPlant (SubForm)
  Um FormDocument pode ser visto como um conjunto de formulários que dão acesso a conjuntos de dados (datasets) como as tabelas do banco de dados ou consultas a partir de um documento LibreOffice. Os nomes dos formulários e subformulários em um FormDocument pode ser acessados usando o Navegador de formulários.
Um documento de formulário é composto por um ou mais formulários que, por sua vez, podem também conter um número qualquer de subformulários. Um formulário é um conjunto abstrato de controles que estão ligados a uma fonte de dados, a qual pode ser uma tabela de um banco de dados, uma consulta ou uma instrução SELECT do SQL.
Em documentos Calc e Writer, cada formulário pode estar ligado a conjuntos de dados localizados em diferentes bancos de dados. Por outro lado, em documentos Base o banco de dados contudo no documento é comum a todos os formulários.
Para invocar o serviço SFDocuments.Form utilize os métodos Forms(), FormDocuments() e OpenFormDocument() do serviço SFDocuments.Document.
Antes de usar o serviço Form a biblioteca ScriptForge precisa ser carregada ou importada:
O trecho de código abaixo mostra como acessar o formulário chamado Form1 que está em um arquivo do Writer.
      Dim oDoc As Object, myForm As Object, ui as Object
      Set ui = CreateScriptService("UI")
      Set oDoc = ui.OpenDocument("/home/user/Documents/MyForm.odt")
      Set myForm = oDoc.Forms("Form1")
   
     from scriptforge import CreateScriptService
     ui = CreateScriptService('UI') 
     doc = ui.OpenDocument('/home/user/Documents/MyForm.odt')
     my_form = doc.Forms('Form1')
   Formulários podem ser acessado por seus nomes ou por seus índices, conforme mostrado abaixo:
     Set myForm = oDoc.Forms(0)
   
     my_form = doc.Forms(0)
   Se você tentar acessar um FormDocument que estiver atualmente aberto no Modo de Edição uma exceção será lançada.
Um formulário em um arquivo Calc deve ter um nome único dentro de uma mesma planilha. Assim, o método Forms necessita de dois argumentos, o primeiro indicando o nome da planilha e o segundo especificando o nome do formulário.
      Dim oDoc As Object, myForm As Object, ui as Object
      Set ui = CreateScriptService("UI")
      Set oDoc = ui.OpenDocument("/home/user/Documents/MyForms.ods")
      Set myForm = oDoc.Forms("Sheet1", "Form1")
   Isso é realizado de forma idêntica em Python:
     ui = CreateScriptService('UI')
     doc = ui.OpenDocument('/home/user/Documents/MyForms.ods')
     my_form = doc.Forms('Sheet1', 'Form1')
   Um FormDocument dentro de um documento Base é acessado por seu nome. O exemplo a seguir abre o documento de formulário thisFormDocument e acessa o formulário MainForm:
      Dim oDb As Object, myForm As Object
      Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)
      ' A instrução abaixo é necessária somente se o formulário ainda não tiver sido aberto
      oDb.OpenFormDocument("thisFormDocument")
      Set myForm = oDoc.Forms("thisFormDocument", "MainForm")
      ' Alternativamente é possível acessar o formulário por seu índice
      Set myForm = oDb.Forms("thisFormDocument", 0)
   Para realizar qualquer ação em um formulário usando o serviço Form, o FormDocument deve ter sido aberto manualmente pelo usuário ou usando linguagem de programação em um script. A segunda opção pode ser usada ao chamar o método OpenFormDocument do serviço Base.
Para acessar um dado subformulário de um formulário, use o método SubForms. Note que no exemplo abaixo mySubForm é uma nova instância do serviço Form.
     Dim mySubForm As Object
     Set mySubForm = myForm.SubForms("mySubForm")
   Os exemplos anteriores pode ser traduzidos para Python da seguinte forma:
     db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())
     # A instrução abaixo é necessária somente se o formulário não tiver sido aberto ainda
     form_doc = db.OpenFormDocument('thisFormDocument')
     form = form_doc.Forms('thisFormDocument', 'MainForm')
     # Ou alternativamente, para acessar o formulário usando seu índice...
     form = form_doc.Forms('thisFormDocument', 0)
     sub_form = form.SubForms('mySubForm')
   Para invocar o serviço Form quando um evento de formulário ocorrer:
      Sub OnEvent(ByRef poEvent As Object)
          Dim myForm As Object
          Set myForm = CreateScriptService("SFDocuments.FormEvent", poEvent)
          '(...)
      End sub
   
     def OnEvent(event: uno):
         form = CreateScriptService('SFDocuments.FormEvent', event)
         pass
   É recomendável liberar os recursos após o uso do serviço Form.
     myForm.Dispose() ' Basic
   
     form.Dispose()  # Python
   Esta operação é feita implicitamente quando um documento de formulário é fechado com o método CloseFormDocument() descrito abaixo.
| Nome | Somente leitura | Tipo | Descrição | 
|---|---|---|---|
| AllowDeletes | Não | Boolean | Especifica se o formulário permite que registros sejam apagados. | 
| AllowInserts | Não | Boolean | Especifica se o formulário permite que registros sejam adicionados. | 
| AllowUpdates | Não | Boolean | Especifica se o formulário permite que registros sejam atualizados. | 
| BaseForm | Sim | String | Especifica o nome hierárquico do formulário Base contido no documento atual. | 
| Bookmark | Não | Variant | Especifica de forma única o registro atual da tabela associada ao formulário, consulta ou instrução SQL. | 
| CurrentRecord | Não | Long | Identifica o registro atual no banco de dados sendo apresentado no formulário. Se o número da linha for positivo, o cursor se move para a linha especificada com relação ao início do conjunto de resultado. A contagem de linhas se inicia em 1. Se o número de linha for negativo, o cursor se move para uma posição de linha absoluta com relação ao final do conjunto de resultado. O valor -1 para a linha refere-se à ultima linha no conjunto de resultado. | 
| Filter | Não | String | Especifica um subconjunto de registros a serem apresentados como uma cláusula SQL WHERE sem a palavra chave WHERE. | 
| LinkChildFields | Sim | String | Especifica como os registros em um subformulário filho serão ligados aos registros de seu formulário pai. | 
| LinkParentFields | Sim | String | Especifica como os registros em um subformulário filho serão ligados aos registros de seu formulário pai. | 
| Name | Sim | String | O nome do formulário atual. | 
| OrderBy | Não | String | Especifica em que ordem os registros devem ser mostrados como uma cláusula SQL ORDER BY sem a palavra chave ORDER BY. | 
| Parent | Sim | Object | Pai do formulário atual. Pode ser um objeto SFDocuments.Form ou um SFDocuments.Document. | 
| RecordSource | Não | String | Especifica a fonte dos dados, como um nome de tabela, um nome de consulta ou uma instrução SQL. | 
| XForm | Sim | Objeto | Objeto UNO representando interações com o formulário. Consulte a documentação API de XForm e DataForm para maiores detalhes. | 
As propriedades abaixo retornam ou definem strings URI que definem os scripts a serem acionados pelo evento.
| Nome | Somente leitura | Descrição na IDE do Basic | 
|---|---|---|
| OnApproveCursorMove | Não | Antes da alteração do registro | 
| OnApproveParameter | Não | Parâmetros de preenchimento | 
| OnApproveReset | Não | Antes de redefinir | 
| OnApproveRowChange | Não | Antes de gravar ação | 
| OnApproveSubmit | Não | Antes de enviar | 
| OnConfirmDelete | Não | Confirmar exclusão | 
| OnCursorMoved | Não | Após alteração do registro | 
| OnErrorOccurred | Não | Ocorreu um erro | 
| OnLoaded | Não | Ao carregar | 
| OnReloaded | Não | Ao recarregar | 
| OnReloading | Não | Antes de recarregar | 
| OnResetted | Não | Após redefinir | 
| OnRowChanged | Não | Após gravar ação | 
| OnUnloaded | Não | Ao descarregar | 
| OnUnloading | Não | Antes de descarregar | 
Para aprender mais sobre Strings URI leia a página Scripting Framework URI Specification.
| Lista de Métodos no Serviço Form | ||
|---|---|---|
Coloca o foco na instância Form atual. Retorna True se a focalização foi bem-sucedida.
O comportamento do método Activate depende do tipo de documento onde o formulário está localizado:
Em documentos Writer: Coloca o foco no documento.
Em documentos Calc: Coloca o foco na planilha à qual o formulário pertence.
Em documentos Base: Coloca o foco no FormDocument ao qual a instância do serviço Form se refere.
svc.Activate(): bool
Os exemplos a seguir assume que você deseja ativar o formulário com nome FormA localizado na planilha Sheet1 do documento Calc atualmente aberto. Primeiramente é obtido acesso ao documento usando o serviço Document e ThisComponent e após isso o formulário é ativado.
     'Obtém acesso ao formulário que se deseja ativar
     Dim oDoc as Object, myForm as Object
     Set oDoc = CreateScriptService("Document", ThisComponent)
     Set myForm = oDoc.Forms("Sheet1", "FormA")
     'Ativa o formulário
     myForm.Activate()
   
     doc = CreateScriptService('Document', XSCRIPTCONTEXT.getDocument())
     form = doc.Forms('Sheet1', 'FormA')
     form.Activate()
   ThisComponent se aplica a documentos Calc e Writer. Em documentos Base use ThisDataBaseDocument.
Esse método está obsoleto; em vez disso, use o método ScriptForge.FormDocument.CloseDocument.
Fecha o documento de formulário contendo a instância Form atual. A instância Form é descartada.
svc.CloseFormDocument(): bool
      myForm.CloseFormDocument() ' Basic
   
      form.CloseFormDocument()  # Python
   O valor retornado pelo método Controls depende dos argumentos fornecidos:
Se o método for chamado sem argumentos, ele retornará a lista dos controles contidos no formulário. Esteja ciente de que a lista retornada não contém nenhum controle de subformulário.
Se o argumento opcional ControlName for fornecido, o método retornará uma instância da classe FormControl representando o controle especificado.
svc.Controls(opt controlname: str): any
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 myForm As Object, myList As Variant, myControl As Object
      Set myForm = myDoc.Forms("myForm")
      myList = myform.Controls()
      Set myControl = myform.Controls("myTextBox") ' SFDocuments.FormControl
   
      form = doc.Forms('myForm')
      form_names = form.Controls()
      form_control = form.Controls('myTextBox')  # SFDocuments.FormControl
   Retorna uma instância do serviço SFDatabases.Database permitindo a execução de comandos SQL no banco de dados que o formulário atual está conectado e/ou está armazenado no documento Base atual.
Cada formulário tem sua própria conexão de banco de dados, exceto documentos Base onde todos compartilham a mesma conexão.
svc.GetDatabase(opt user: str, opt password: str): svc
user, password: Parâmetros opcionais de login (Padrão = "").
      Dim myDb As Object ' SFDatabases.Database
      Set myDb = oForm.GetDatabase()
   
      db = form.GetDatabase()  # SFDatabases.Database
   O cursor do formulário é posicionado no primeiro registro. Retorna True se for bem-sucedido.
svc.MoveFirst(): bool
      myForm.MoveFirst() ' Basic
   
      form.MoveFirst()  # Python
   Posiciona o cursor do formulário no último registro. RetornaTrue se for bem-sucedido.
svc.MoveLast(): bool
      myForm.MoveLast() ' Basic
   
      form.MoveLast()  # Python
   Posiciona o cursor do formulário na área do novo registro. RetornaTrue se for bem sucedido.
svc.MoveNew(): bool
      myForm.MoveNew() ' Basic
   
      form.MoveNew()  # Python
   Posiciona o cursor do formulário no próximo registro. RetornaTrue se for bem-sucedido.
svc.MoveNext(opt offset: int): bool
offset: Quantidade de registros para avançar (Padrão = 1).
      myForm.MoveNext() ' Basic
   
      form.MoveNext()  # Python
   Posiciona o cursor do formulário no registro anterior. Retorna True se for bem-sucedido.
svc.MovePrevious(opt offset: int): bool
offset: Quantidade de registros a retroceder (Padrão = 1).
      myForm.MovePrevious() ' Basic
   
      form.MovePrevious()  # Python
   Recarrega os dados atuais do banco de dados e atualiza o formulário. O cursor é posicionado no primeiro registro. Retorna True se for bem sucedido.
svc.Requery(): bool
      myForm.Requery() ' Basic
   
      form.Requery()  # Python
   O valor retornado pelo método Subforms depende dos argumentos fornecidos:
Se o método for chamado sem argumentos, então será retornada a lista de subformulários contidos na instância de formulário ou subformulário atual.
Se o argumento opcional subform for fornecido, o método retornará uma nova instância do serviço SFDocuments.Form baseado no nome de formulário/subformulário ou índice especificado.
svc.Subforms(): str[0..*]
svc.Subforms(subform: str): svc
svc.Subforms(subform: int): svc
subform : Um subformulário armazenado na instância da classe atual Form fornecida por seu nome ou índice.
Quando esse argumento está ausente, o método retorna uma lista de subformulários disponíveis como uma matriz baseada em zero. Se o formulário tiver um único subformulário, você pode definir subform = 0 para obter acesso a ele.
      Dim myForm As Object, myList As Variant, mySubform As Object
      myList = myform.Subforms()
      Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form
   
      subform_names = form.Subforms()
     subform = form.Subforms('mySubform')  # SFDocuments.Form