Serviço.SFDocumentsBase

O serviço Base disponibiliza vários métodos e propriedades para facilitar a gestão e o manuseamento de documentos LibreOffice Base.

Este serviço está intimamente relacionado com o serviço Document, que fornece métodos genéricos para o tratamento de documentos LibreOffice, incluindo documentos Base. Por conseguinte, o serviço Base estende o serviço Document e fornece métodos adicionais específicos para documentos Base, permitindo aos utilizadores:

Obter acesso à base de dados contida num documento Base.
Abrir documentos de formulário armazenados num documento Base.
Verifique se está carregado um documento de formulário proveniente de um documento Base.

Consulte o serviço Document para saber mais sobre os métodos e propriedades que podem ser utilizados para gerir documentos LibreOffice.

Chamada de serviço

Antes de utilizar o serviço Base, é 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

In Basic

O serviço Base pode ser invocado de várias formas. O trecho de código abaixo utiliza o método CreateBaseDocument do serviço UI para criar um novo ficheiro Base.

Note-se que, em todos os exemplos, o objeto oDoc é uma instância do serviço Base.


    Dim ui As Object, oDoc As Object
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.CreateBaseDocument("C:\Documents\MyFile.odb")

O serviço Base também pode ser instanciado ao abrir um ficheiro Base existente, conforme ilustrado abaixo:


    Set oDoc = ui.OpenBaseDocument("C:\Documents\MyFile.odb")

Se um documento Base já estiver aberto, é possível instanciar o serviço Base diretamente:


    Dim oDoc As Object
    Set oDoc = CreateScriptService("SFDocuments.Document", "MyFile.odb")

In Python

Os exemplos acima podem ser traduzidos para Python da seguinte forma:


    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
    doc = ui.CreateBaseDocument(r"C:\Documents\MyFile.odb")


    doc = ui.OpenBaseDocument(r"C:\Documents\MyFile.odb")


    doc = CreateScriptService("SFDocuments.Document", "MyFile.odb")

A utilização da subcadeia "SFDocuments." no exemplo anterior é opcional.

Lista de métodos no serviço Base
CloseFormDocument FormDocuments Forms GetDatabase	IsLoaded OpenFormDocument OpenQuery OpenTable	PrintOut SetPrinter

CloseFormDocument

Fecha o documento de formulário indicado. Devolve True se o encerramento for bem-sucedido.

O método CloseFormDocument está obsoleto desde a versão LibreOffice 7.6. Embora ainda esteja disponível, poderá ser removido do serviço Base numa versão futura. Em vez disso, utilize o método CloseDocument do serviço FormDocument.

Sintaxe:

svc.CloseFormDocument(formdocument: str): bool

Parâmetros:

formdocument: O nome do FormDocument a ser fechado, como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

Exemplo:

Se os documentos de formulário estiverem organizados em pastas, é necessário incluir o nome da pasta para especificar o documento de formulário a abrir, conforme ilustrado nos exemplos seguintes:

In Basic


    oDoc.CloseFormDocument("Folder1/myFormDocument")

In Python


    doc.CloseFormDocument('Folder1/myFormDocument')

FormDocuments

Devolve uma matriz com os nomes completos (caminho/nome) de todos os documentos do formulário no documento Base, sob a forma de uma matriz de cadeias de caracteres com indexação a partir de zero.

Sintaxe:

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

Exemplo:

O trecho de código abaixo apresenta os nomes de todos os documentos de formulário no documento Base atual.

In Basic


    Dim oDoc as Object, myForms as Object, formName as String
    Set oDoc = CreateScriptService("Document", ThisDataBaseDocument)
    Set myForms = oDoc.FormDocuments()
    For Each formName In myForms
        MsgBox formName
    Next formName

In Python


    bas = CreateScriptService("Basic")
    doc = CreateScriptService("Document", bas.ThisDataBaseDocument)
    myForms = doc.FormDocuments()
    for formName in myForms:
        bas.MsgBox(formName)

Para saber mais sobre documentos de formulário, consulte a página de ajuda do serviço ScriptForge.FormDocument.

Forms

Dependendo dos parâmetros fornecidos, este método irá devolver:

Uma matriz com índice zero contendo os nomes de todos os formulários incluídos num documento de formulários (caso o argumento Form esteja ausente)
Um objeto SFDocuments.Form que representa o formulário especificado no argumento Form.

O método Forms está obsoleto desde a versão LibreOffice 7.6. Embora ainda esteja disponível, poderá ser removido do serviço Base numa versão futura. Em vez disso, utilize o método Forms do serviço FormDocument.

Sintaxe:

svc.Forms(formdocument: str): str[0..*]

svc.Forms(formdocument: str, form: str = ''): svc

svc.Forms(formdocument: str, form: int): svc

Parâmetros:

formdocument: O nome de um documento de formulário válido, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

form: O nome ou número de índice do formulário armazenado no documento de formulários. Se este argumento não for fornecido, o método devolverá uma lista com os nomes de todos os formulários disponíveis no documento de formulários.

Embora seja possível utilizar números de índice para se referir a formulários, isso só é recomendado quando existe apenas um formulário no documento. Se houver dois ou mais formulários, é preferível utilizar o nome do formulário.

Exemplo:

A primeira linha do exemplo abaixo devolve uma lista de todos os formulários contidos no documento de formulários «myFormDocument». A segunda linha devolve uma instância do serviço Form que representa o formulário «myForm».

In Basic


    Dim formsList as Object : formsList = oDoc.Forms("myFormDocument")
    Dim oForm as Object : oForm = oDoc.Forms("myFormDocument", "myForm")

In Python


    formsList = doc.Forms("myFormDocument")
    form = doc.Forms("myFormDocument", "myForm")

GetDatabase

Devolve uma instância do serviço Database que permite a execução de comandos SQL na base de dados definida e/ou armazenada no documento Base atual

Sintaxe:

svc.GetDatabase(user: str = '', password: str = ''): svc

Parâmetros:

user, password Parâmetros de início de sessão opcionais sob a forma de cadeias de caracteres. O valor predefinido para ambos os parâmetros é uma cadeia de caracteres vazia "".

Exemplo:

In Basic


    Dim myDoc As Object, myDatabase As Object, ui As Object
    Set ui = CreateScriptService("UI")
    Set myDoc = ui.OpenBaseDocument("C:\Documents\myDb.odb")
    ' O nome de utilizador e a palavra-passe encontram-se abaixo, caso sejam necessários
    Set myDatabase = myDoc.GetDatabase()
    '   ... Executar consultas, instruções SQL, ...
    myDatabase.CloseDatabase()
    myDoc.CloseDocument()

In Python


    ui = CreateScriptService("UI")
    myDoc = ui.OpenBaseDocument(r"C:\Documents\myDb.odb")
    myDatabase = myDoc.GetDatabase()
    #   ... Executar consultas, instruções SQL, ...
    myDatabase.CloseDatabase()
    myDoc.CloseDocument()

IsLoaded

Retorna True se o FormDocument especificado estiver aberto neste momento.

Sintaxe:

svc.IsLoaded(formdocument: str): bool

Parâmetros:

formdocument: O nome de um FormDocument a ser verificado, como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

Exemplo:

In Basic


    If Not oDoc.IsLoaded("myFormDocument") Then
        oDoc.OpenFormDocument("myFormDocument")
    End If

In Python


    if not doc.IsLoaded("myFormDocument"):
        doc.OpenFormDocument("myFormDocument")

OpenFormDocument

Abre o FormDocument especificado, quer no modo normal, quer no modo de design. Este método devolve uma instância do serviço FormDocument correspondente ao documento de formulário especificado.

Se o documento do formulário já estiver aberto, é ativado sem alterar o seu modo.

Se o documento de formulário especificado não existir, é devolvido Nothing.

Sintaxe:

svc.OpenFormDocument(formdocument: str, designmode: bool = False): svc

Parâmetros:

formDocument: O nome do FormDocument a abrir, como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

designmode: Se este argumento for True, o FormDocument será aberto no modo de design.

Exemplo:

In Basic

A maioria dos documentos de formulário está armazenada na raiz do documento Base e pode ser aberta simplesmente utilizando os seus nomes, como no exemplo abaixo:


    Dim oFormDoc As Object
    oFormDoc = oDoc.OpenFormDocument("myFormDocument")

Se os documentos de formulário estiverem organizados em pastas, torna-se necessário incluir o nome da pasta para especificar o documento de formulário a abrir, conforme ilustrado no exemplo seguinte:


    oFormDoc = oDoc.OpenFormDocument("myFolder/myFormDocument")

In Python


    formDoc = doc.OpenFormDocument("myFormDocument")


    formDoc = doc.OpenFormDocument("myFolder/myFormDocument")

OpenQuery

Abre a janela «Data View» da consulta especificada e devolve uma instância do serviço Datasheet.

A consulta pode ser aberta tanto no modo normal como no modo de design.

Se a consulta já estiver aberta, a janela de visualização de dados será ativada.

Ao fechar o documento Base, a janela Visualização de dados também será fechada.

Sintaxe:

svc.OpenQuery(queryname: str, designmode: bool = False): obj

Parâmetros:

queryname: O nome de uma consulta existente, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

designmode: Se este argumento for definido como True, a consulta é aberta no modo de design. Caso contrário, é aberta no modo normal (Padrão = False).

Exemplo:

In Basic


      oDoc.OpenQuery("MyQuery", DesignMode := True)

In Python


      doc.OpenQuery("MyQuery", designmode=True)

OpenTable

Abre a janela «Data View» da tabela especificada e devolve uma instância do serviço Datasheet.

A tabela pode ser aberta tanto no modo normal como no modo de design.

Se a tabela já estiver aberta, a janela de visualização de dados será ativada.

Ao fechar o documento Base, a janela Visualização de dados também será fechada.

Sintaxe:

svc.OpenTable(tablename: str, designmode: bool = False): obj

Parâmetros:

tablename: O nome de uma tabela existente, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

designmode: Se este argumento for definido como True, a tabela é aberta no modo de design. Caso contrário, é aberta no modo normal (Padrão = False).

Exemplo:

In Basic


      oDoc.OpenTable("MyTable", DesignMode = False)

In Python


      doc.OpenTable("MyTable", designmode=False)

PrintOut

Este método envia o conteúdo do documento do formulário especificado para uma impressora predefinida ou para uma impressora definida pelo método SetPrinter().

Retorna True se o documento tiver sido impresso com sucesso.

O método PrintOut está obsoleto desde a versão LibreOffice 7.6. Embora ainda esteja disponível, poderá ser removido do serviço Base numa versão futura. Em vez disso, utilize o método PrintOut do serviço FormDocument.

Sintaxe:

svc.PrintOut(opt formdocument: str, pages: str = "", copies: num = 1): bool

Parâmetros:

formdocument: Um nome de formulário válido, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas. O formulário deve estar aberto. É ativado pelo método.

pages: As páginas a imprimir, indicadas como uma sequência de caracteres, tal como na interface do utilizador. Exemplo: "1-4;10;15-18". O valor predefinido é todas as páginas.

copies: O número de cópias. O valor predefinido é 1.

Exemplo:

In Basic


    If oDoc.PrintOut("myForm", "1-4;10;15-18", Copies := 2) Then
        ' ...
    End If

In Python


    if doc.PrintOut('myForm', copies=3, pages='45-88'):
        # ...

SetPrinter

Defina as opções de impressão para um documento de formulário. O documento de formulário deve estar aberto.

Retorna True em caso de sucesso.

O método SetPrinter está obsoleto desde a versão LibreOffice 7.6. Embora ainda esteja disponível, poderá ser removido do serviço Base numa versão futura. Em vez disso, utilize o método SetPrinter do serviço Document.

Sintaxe:

svc.SetPrinter(opt formdocument: str, opt printer: str, opt orientation: str, paperformat: str): bool

Parâmetros:

formdocument: Um nome de formulário válido, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas.

printer: The name of the printer queue where to print to. When absent, the default printer is set.

orientation: Either PORTRAIT or LANDSCAPE. When absent, left unchanged with respect to the printer settings.

paperformat: Specifies the paper format as a string value that can be either A3, A4, A5, LETTER, LEGAL or TABLOID. Left unchanged when absent.

Exemplo:

In Basic


    oDoc.SetPrinter("myForm", Orientation := "PORTRAIT")

In Python


    doc.SetPrinter('myForm', paperformat='TABLOID')

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.

SFDatabases.Database service

SFDocuments.Document service

SFDocuments.Form service

ScriptForge.UI service