Serviço SFDocuments.Form

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.

Definições

FormDocument

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 Inserir - Formulário 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.

Formulários e subformulá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.

Invocação do serviço

Antes de usar o serviço Form 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

Em documentos do Writer

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")

Em Python


     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)

Em Python


     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.

Em documentos do Calc

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')

Em documentos do Base

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')

Em eventos de formulário

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

Em Python


     def OnEvent(event: uno):
         form = CreateScriptService('SFDocuments.FormEvent', event)
         pass

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.

É 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.

Propriedades

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 UNO	Objeto UNO representando interações com o formulário. Consulte a documentação API de XForm e DataForm para maiores detalhes.

Propriedades de evento

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
Activate CloseFormDocument Controls GetDatabase	MoveFirst MoveLast MoveNext MoveNew	MovePrevious Requery SubForms

Activate

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.

Sintaxe:

svc.Activate(): bool

Exemplo:

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()

Em Python


     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.

CloseFormDocument

Fecha o documento de formulário contendo a instância Form atual. A instância Form é descartada.

Sintaxe:

svc.CloseFormDocument(): bool

Exemplo:


      myForm.CloseFormDocument() ' Basic

Em Python


      form.CloseFormDocument()  # Python

Este método apenas fecha documentos de formulário localizados em documentos Base. Se o formulário estiver armazenado em documentos Writer ou Calc, chamar o método CloseFormDocument não terá efeito algum.

Controls

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.

Sintaxe:

svc.Controls(opt controlname: str): any

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 myForm As Object, myList As Variant, myControl As Object
      Set myForm = myDoc.Forms("myForm")
      myList = myform.Controls()
      Set myControl = myform.Controls("myTextBox") ' SFDocuments.FormControl

Em Python


      form = doc.Forms('myForm')
      form_names = form.Controls()
      form_control = form.Controls('myTextBox')  # SFDocuments.FormControl

GetDatabase

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.

Sintaxe:

svc.GetDatabase(opt user: str, opt password: str): svc

Parâmetros:

user, password: Parâmetros opcionais de login (Padrão = "").

Exemplo:


      Dim myDb As Object ' SFDatabases.Database
      Set myDb = oForm.GetDatabase()

Em Python


      db = form.GetDatabase()  # SFDatabases.Database

MoveFirst

O cursor do formulário é posicionado no primeiro registro. Retorna True se for bem-sucedido.

Sintaxe:

svc.MoveFirst(): bool

Exemplo:


      myForm.MoveFirst() ' Basic

Em Python


      form.MoveFirst()  # Python

MoveLast

Posiciona o cursor do formulário no último registro. RetornaTrue se for bem-sucedido.

Sintaxe:

svc.MoveLast(): bool

Exemplo:


      myForm.MoveLast() ' Basic

Em Python


      form.MoveLast()  # Python

MoveNew

Posiciona o cursor do formulário na área do novo registro. RetornaTrue se for bem sucedido.

Sintaxe:

svc.MoveNew(): bool

Exemplo:


      myForm.MoveNew() ' Basic

Em Python


      form.MoveNew()  # Python

MoveNext

Posiciona o cursor do formulário no próximo registro. RetornaTrue se for bem-sucedido.

Sintaxe:

svc.MoveNext(opt offset: int): bool

Parâmetros:

offset: Quantidade de registros para avançar (Padrão = 1).

Exemplo:


      myForm.MoveNext() ' Basic

Em Python


      form.MoveNext()  # Python

MovePrevious

Posiciona o cursor do formulário no registro anterior. Retorna True se for bem-sucedido.

Sintaxe:

svc.MovePrevious(opt offset: int): bool

Parâmetros:

offset: Quantidade de registros a retroceder (Padrão = 1).

Exemplo:


      myForm.MovePrevious() ' Basic


      form.MovePrevious()  # Python

Requery

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.

Sintaxe:

svc.Requery(): bool

Exemplo:


      myForm.Requery() ' Basic

Em Python


      form.Requery()  # Python

Subforms

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.

Sintaxe:

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

svc.Subforms(subform: str): svc

svc.Subforms(subform: int): svc

Parâmetros:

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.

Exemplo:


      Dim myForm As Object, myList As Variant, mySubform As Object
      myList = myform.Subforms()
      Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form

Em Python


      subform_names = form.Subforms()
     subform = form.Subforms('mySubform')  # SFDocuments.Form

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.

Serviço SFDatabases.Database

Serviço SFDocuments.Document

Serviço ScriptForge.UI