Serviço SFDocuments.Base

Conteúdo

# 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

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

##### Em 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:

##### Em Basic

        oDoc.CloseFormDocument("Folder1/myFormDocument")

##### Em 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.

##### Em 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

##### Em 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».

##### Em Basic

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

##### Em 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:

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

##### Em 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:

##### Em Basic

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

##### Em 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:

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

##### Em 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:

##### Em Basic

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

##### Em 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:

##### Em Basic

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

##### Em 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:

##### Em Basic

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

##### Em 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.

impressora: O nome da fila de impressão para a qual se pretende imprimir. Se não for indicado, é utilizada a impressora predefinida.

orientação: Pode ser PORTRAIT ou LANDSCAPE. Se não for especificada, mantém-se inalterada em relação às definições da impressora.

paperformat: Especifica o formato do papel como um valor de cadeia de caracteres que pode ser A3, A4, A5, LETTER, LEGAL ou TABLOID. Se não for indicado, mantém-se inalterado.

### Exemplo:

##### Em Basic

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

##### Em 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.

Tópicos relacionados

Serviço SFDatabases.Database

SFDocuments.Document serviço

SFDocuments.Form service

ScriptForge.UI service

Necessitamos da sua ajuda!