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:

tip

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.

tip

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

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.

tip

Para invocar o serviço SFDocuments.Form utilize os métodos Forms(), FormDocuments() e OpenFormDocument() do serviço SFDocuments.Document.


Invocando o Serviço

Em Documentos 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("~/Documents/MyForm.odt")
      Set myForm = oDoc.Forms("Form1")
   
Em Python

     from scriptforge import CreateScriptService
     svc = CreateScriptService('UI') 
     doc = svc.OpenDocument('~/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)
   
warning

Se você tentar acessar um FormDocument que estiver atualmente aberto no Modo de Edição uma exceção será lançada.


Em Documentos 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("~/Documents/MyForms.ods")
      Set myForm = oDoc.Forms("Sheet1", "Form1")
   

Isso é realizado de forma idêntica em Python:


     svc = CreateScriptService('UI')
     doc = svc.OpenDocument('~/Documents/MyForms.ods')
     my_form = doc.Forms('Sheet1', 'Form1')
   

Em documentos 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)
   
note

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
   
note

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


tip

Para aprender mais sobre strings URI consulte a página Wiki 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:

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

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
   
note

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:

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:

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
   
warning

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.


♥ Doe para nosso projeto! ♥