Conteúdo
Índice 🔎︎

# Serviço SFDocuments.Document

A biblioteca SFDocuments fornece métodos e propriedades que facilitam a gestão e manuseio de documentos do LibreOffice.

Métodos aplicáveis a todos os tipos de documentos (documentos de texto, planilhas, apresentações, etc.) são disponibilizados pelo serviço SFDocuments.Document. Alguns exemplos são:

- Abrir, fechar e salvar documentos

- Acessar propriedades padrão e customizadas dos documentos

As propriedades, métodos ou argumentos marcados com (*) NÃO são aplicáveis a documentos Base.

Métodos e propriedades que são específicos a componentes específicos do LibreOffice são disponibilizados em serviços separados, tais como SFDocuments.SF_Calc e SFDocuments.SF_Base.

Apesar de a linguagem Basic não oferecer herança entre classes de objeto, os serviços específicos podem ser considerados como subclasses do serviço SFDocuments.Document. Tais subclasses também podem chamar os métodos e propriedades descritos abaixo.

## Invocação do serviço

Abaixo são apresentadas três variantes de como invocar o serviço Document.

##### Em Basic

Usando o método getDocument do serviço ScriptForge.UI:

        Dim ui As Object, oDoc As Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.GetDocument("Untitled 1")

Alternativamente você pode usar os métodos CreateDocument e OpenDocument do serviço UI.

        Set oDocA = ui.CreateDocument("Calc")
        Set oDocB = ui.OpenDocument("C:\Documents\MyFile.odt")

Diretamente se o documento já estiver aberto.

        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow

A partir de uma macro disparada por um evento de documento.

        Sub RunEvent(ByRef poEvent As Object)
            Dim oDoc As Object
            Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)
            ' (...)
        End Sub

O serviço Document está intimamente relacionado aos serviços UI e FileSystem.

Com exceção de quando o documento for fechado pela macro com o método CloseDocument (seria redundante liberar recursos), recomenda-se liberar os recursos usando:

        Set oDoc = oDoc.Dispose()

##### Em Python

        from scriptforge import CreateScriptService
        ui = CreateScriptService("UI")
        doc = ui.GetDocument("Untitled 1")
        # (...)
        doc.Dispose()

        docA = ui.CreateDocument("Calc")
        docB = ui.OpenDocument("C:\Documents\MyFile.odt")

        doc = CreateScriptService("SFDocuments.Document", "Untitled 1")

        def RunEvent(event)
            doc = CreateScriptService("SFDocuments.DocumentEvent", Event)
            # (...)

O uso do prefixo "SFDocuments." ao chamar o serviço é opcional.

## Propriedades

Nome | Somente leitura | Tipo | Descrição
CustomProperties (*) | Não | Dictionary service | Retorna um objeto ScriptForge.Dictionary. Após a atualização, pode ser passado novamente para a propriedade para atualizar o documento. Itens individuais do dicionário podem ser strings, números, datas (Basic) ou itens com.sun.star.util.Duration.
Description (*) | Não | String | Fornece acesso à propriedade "Description" do documento (também conhecida como "Comments")
DocumentProperties (*) | Sim | Dictionary service | Retorna um objeto ScriptForge.Dictionary contendo todas as entradas. Estatísticas do documento também estão inclusas. Note que os itens do dicionário dependem do tipo do documento. Por exemplo, um documento Calc inclui uma entrada "CellCount", ao passo que outros tipos de documento não têm essa entrada.
DocumentType | Sim | String | Valor string com o tipo do documento ("Base", "Calc", "Writer", etc)
IsBase IsCalc IsDraw IsImpress IsMath IsWriter | Sim | Boolean | Exatamente uma destas propriedades é True para um dado documento.
Keywords (*) | Não | String | Fornece acesso à propriedade "Keywords" do documento, a qual é representada como uma lista separada por vírgulas.
Readonly (*) | Sim | Boolean | True se o documento estiver no modo somente leitura.
Subject (*) | Não | String | Fornece acesso à propriedade "Subject" do documento.
Title (*) | Não | String | Fornece acesso à propriedade "Title" do documento.
XComponent | Sim | Objeto UNO | O objeto UNO com.sun.star.lang.XComponent ou com.sun.star.comp.dba.ODatabaseDocument representando o documento

### Exemplo:

##### Em Basic

O exemplo abaixo imprime todas as propriedades de um documento. Note que o objeto oDoc retornado pelo método UI.OpenDocument é um objeto SFDocuments.Document.

        Dim ui as Variant : Set ui = CreateScriptService("UI")
        Dim oDoc as Object
        Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")
        Dim propDict as Object
        Set propDict = oDoc.DocumentProperties
        Dim keys as Variant : propKeys = propDict.Keys
        Dim k as String, strProp as String
        For Each k In propKeys
            strProp = strProp & k & ": " & propDict.Item(k) & CHR$(10)
        Next k
        MsgBox strProp
        oDoc.CloseDocument()

##### Em Python

Para acessar as propriedades de documento em um script Python o usuário deve acessá-los diretamente usando seus nomes, como mostrado abaixo:

        doc = ui.GetDocument(r"C:\Documents\MyFile.ods")
        msg = doc.Title + '\n' + doc.Description + '\n' + doc.Keywords
        bas = CreateScriptService("Basic")
        bas.MsgBox(msg)
        doc.CloseDocument()

Lista de Métodos do Serviço Document
Activate CloseDocument Forms | RunCommand Save | SaveAs SaveCopyAs

## Activate

Retorna True se o documento foi efetivamente ativado. Senão, não há mudança na interface de usuário. É equivalente ao método Activate do serviço UI.

Este método é útil quando se precisa dar foco a um documento que está minimizado ou oculto.

### Sintaxe:

svc.Activate(): bool

### Exemplo:

O exemplo abaixo considera que "My_File.ods" já está aberto, porém não está ativo.

##### Em Basic

        Dim oDoc As Object
        Set oDoc = CreateScriptService("Document", "MyFile.ods")
        oDoc.Activate()

##### Em Python

        doc = CreateScriptService("Document", "MyFile.ods")
        doc.Activate()

Lembre-se que você pode chamar o serviço Document passando tanto a string "Document" como a string "SFDocuments.Document" para o método CreateScriptService

## CloseDocument

Fecha o documento. Se o documento estiver fechado, independentemente de como ele foi fechado, este método não tem efeito e retorna False.

Este método também retornará False se o usuário se recusar a fechá-lo.

Retorna True se o fechamento do arquivo foi bem-sucedido.

### Sintaxe:

svc.CloseDocument(saveask: bool = True): bool

### Parâmetros:

saveask: Se for True (padrão), o usuário é convidado a confirmar se as mudanças devem ser salvas no disco. Este argumento é ignorado se o documento não foi modificado.

### Exemplo:

##### Em Basic

        If oDoc.CloseDocument(True) Then
            ' ...
        End If

##### Em Python

        if doc.CloseDocument(True):
            # ...

## Forms

Dependendo dos parâmetros fornecidos este método retornará:

- Um Array indexado em zero (ou uma tupla em Python) com os nomes de todos os formulários contidos no documento (se o argumento form estiver ausente)

- Uma instância do serviço SFDocuments.Form representando o formulário especificado como argumento.

Este método é aplicável apenas a documentos do Writer. Documentos Calc e Base possuem sua própria implementação do método Forms nos serviços Calc e Base, respectivamente.

### Sintaxe:

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

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

svc.Forms(form: int): svc

### Parâmetros:

form: Nome ou índice correspondente a um formulário armazenado no documento. Se este argumento estiver ausente, o método retornará uma lista com os nomes de todos os formulários disponíveis no documento.

### Exemplo:

Nos exemplos abaixo, a primeira linha obtém os nomes de todos os formulários do documento e a segunda linha recupera o objeto Form do formulário com nome "Form_A".

##### Em Basic

        Define FormNames = oDoc.Forms()
        Define FormA = oDoc.Forms("Form_A")

##### Em Python

        form_names = doc.Forms()
        form_A = doc.Forms("Form_A")

## RunCommand

Executa um comando em um documento. O comando é executado sem argumentos.

Alguns comandos típicos são: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy, Paste, etc. Os nomes estão em inglês pois correspondem aos nomes usados na API do LibreOffice.

O documento em si não precisa estar ativo para ser possível executar comandos.

### Sintaxe:

svc.RunCommand(command: str)

### Parâmetros:

command: String sensível ao caso contendo o comando em inglês. O comando não é verificado como sendo correto antes da execução. Se nada acontecer após a chamada do comando, então provavelmente o comando está errado.

### Exemplo:

O exemplo a seguir executa o comando "SelectData" em um arquivo Calc chamado "MyFile.ods", resultando na seleção da área de dados com base na célula selecionada no momento.

##### Em Basic

        Set oDoc = CreateScriptService("Document", "MyFile.ods")
        oDoc.RunCommand("SelectData")

##### Em Python

        doc = CreateScriptService("Document", "MyFile.ods")
        doc.RunCommand("SelectData")

O exemplo acima na verdade executa o comando UNO uno:SelectData. Logo, para usar o método RunCommand é necessário remover o prefixo "uno:".

Cada aplicação do LibreOffice possui seu conjunto próprio de comandos UNO disponíveis. Uma forma fácil de aprender os comandos é abrindo Ferramentas > Personalizar > Teclado. Se você posicionar o mouse em uma função na lista Função, uma dica será apresentada com o comando UNO correspondente.

## Save

Armazena o documento no arquivo e localização de onde ele foi carregado. O método é ignorado se o documento não foi modificado.

Retorna False se o documento não pode ser salvo. Um erro é lançado se o arquivo estiver aberto como somente leitura ou se for um arquivo novo que ainda não foi salvo.

O documento em si não precisa estar ativo para executar este método.

### Sintaxe:

svc.Save(): bool

### Exemplo:

##### Em Basic

        If Not oDoc.Save() Then
            ' ...
        End If

##### Em Python

        if not doc.Save():
            # ...

## SaveAs

Armazena o documento em um arquivo e localização especificado. O novo nome de arquivo é usado quando chamadas subsequentes do método Save forem realizadas.

Retorna False se o documento não pode ser salvo. Um erro é lançado se o usuário rejeitar sobrescrever o arquivo ou quando o atributo "somente leitura" estiver ativo no arquivo de destino.

O documento em si não precisa estar ativo para executar este método.

### Sintaxe:

svc.SaveAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

### Parâmetros:

filename: String contendo o nome do arquivo a ser usado. Deve seguir a notação SF_FileSystem.FileNaming.

overwrite: Se for True, o arquivo de destino pode ser sobrescrito (padrão = False).

password (*): String sem espaços com a senha usada para proteger o documento.

filtername (*): Nome do filtro que deve ser usado para salvar o documento. Se este argumento for passado, então o filtro deve existir.

filteroptions (*): Uma string opcional com as opções associadas ao filtro.

### Exemplo:

##### Em Basic

        oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)

##### Em Python

        doc.SaveAs(r"C:\Documents\NewCopy.odt", overwrite = True)

## SaveCopyAs

Armazena uma cópia ou exporta o documento para um arquivo e localização especificado. O arquivo atual não é modificado.

Retorna False se o documento não pode ser salvo. Um erro é lançado se o usuário rejeitar sobrescrever o arquivo ou quando o atributo "somente leitura" estiver ativo no arquivo de destino.

O documento em si não precisa estar ativo para executar este método.

### Sintaxe:

svc.SaveCopyAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

### Parâmetros:

filename: String contendo o nome do arquivo a ser usado. Deve seguir a notação SF_FileSystem.FileNaming.

overwrite: Se for True, o arquivo de destino pode ser sobrescrito (padrão = False).

password (*): String sem espaços com a senha usada para proteger o documento.

filtername (*): Nome do filtro que deve ser usado para salvar o documento. Se este argumento for passado, então o filtro deve existir.

filteroptions (*): Uma string opcional com as opções associadas ao filtro.

### Exemplo:

##### Em Basic

        oDoc.SaveCopyAs("C:\Documents\Copy2.odt", Overwrite := True)

##### Em Python

        doc.SaveCopyAs(r"C:\Documents\Copy2.odt", overwrite = True)

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.

Tópicos relacionados

Serviço ScriptForge.UI

Serviço ScriptForge.Dictionary