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

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

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

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

Usando um nome de janela se o documento já estiver aberto.

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

Usando o documento referenciado por ThisComponent. É especialmente útil ao executar uma macro de dentro do IDE Basic.

    Dim oDoc As Object
    Set oDoc = CreateScriptService("Document", ThisComponent)
  

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

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

    bas = CreateScriptService("Basic")
    doc = CreateScriptService("Document", bas.ThisComponent)
  

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

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

Propriedades

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

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

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.

svc.Activate(): bool

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

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

    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.

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

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.

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

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

CreateMenu

Cria uma nova entrada de menu na barra de menus de uma dada janela de documento.

Este método retorna uma instância do serviço SFWidgets.Menu.

O menu criado está disponível apenas durante a sessão atual do LibreOffice e não é salvo no documento nem nas configurações globais do aplicativo. Portanto, fechar a janela do documento fará com que o menu desapareça. Ele só reaparecerá quando a macro que cria o menu for executada novamente.

svc.CreateMenu(menuheader: str, [before: any], submenuchar: str = ">"): svc

menuheader: o nome de nível mais alto do novo menu.

before: O nome (como uma string) ou posição (como um número inteiro começando em 1) de um menu existente antes do qual o novo menu será colocado. Se nenhum valor for definido para este argumento, o menu será criado na última posição da barra de menus.

submenuchar: Delimitador usado para criar árvores de menu chamando métodos como AddItem do serviço Menu. O valor padrão é ">".

    Dim oDoc as Object, oMenu as Object
    Set oDoc = CreateScriptService("Document")
    Set oMenu = oDoc.CreateMenu("Meu Menu")
    With oMenu
        ' Adiciona itens ao menu
        .AddItem("Item A")
        .AddItem("Item B")
        ' ...
        ' Após criar o menu, a instância do serviço pode ser descartada
        .Dispose()
    End With
  

    doc = CreateScriptService("Document")
    menu = doc.CreateMenu("Meu Menu")
    menu.AddItem("Item A")
    menu.AddItem("Item B")
    # ...
    menu.Dispose()
  

Consulte a página da ajuda do serviço SFWidgets.Menu para aprender mais sobre como criar/remover menus em janelas de documento do LibreOffice.

DeleteStyles

Remove um único estilo ou uma série de estilos indicados por seus nomes dentro de uma família de estilos específica. Somente estilos definidos pelo usuário podem ser excluídos; os estilos integrados são ignorados. Aplica-se a todos os tipos de documentos, exceto documentos Base e FormDocument.

svc.DeleteStyles(family: str, stylelist: str[1..*])

family: Uma das famílias de estilos presentes no documento, como uma string sensível à caixa. Nomes de família válidos podem ser obtidos usando a propriedade StyleFamilies.

stylelist: um nome de estilo único como uma string ou uma lista de nomes de estilos. Os nomes dos estilos podem ser localizados ou não. Um StylesList normalmente é a saída da execução do método Styles().

    ' Removendo estilos de parágrafo não utilizados
    Const family = "ParagraphStyles"
    aList = oDoc.Styles(family, used := False, userDefined := True)
    oDoc.DeleteStyles(family, aList)
  

    # Removendo estilos de acordo com um prefixo
    a_list = doc.Styles('ParagraphStyles', namepattern = "Py*")
    doc.Styles('ParagraphStyles', a_list)
  

Echo

Suspende atualizações da interface do usuário (UI) durante a execução de uma macro. Opcionalmente, o ponteiro do mouse pode ser transformado em uma ampulheta enquanto as atualizações da UI são suspensas.

Este método pode fornecer alguns benefícios de desempenho para macros que executam diversas operações que exigem atualizações da interface do usuário.

svc.Echo(echoon: bool = True, hourglass: bool = False)

echoon: especifique False para suspender as atualizações da interface. O valor padrão é True, que permite atualizações da interface em tempo real.

hourglass: especifique True para alterar o ponteiro do mouse para uma ampulheta (Padrão = False).

Mover o ponteiro do mouse depois de mudá-lo para uma ampulheta pode fazer com que ele mude para um ponteiro diferente dependendo do que estiver por trás do ponteiro.

    ' Suspende as atualizações da interface e altera o ponteiro do mouse para uma ampulheta
    oDoc.Echo(EchoOn := False, HourGlass := True)
    ' Outros comandos de macro
    ' ...
    ' Restaura as atualizações da interface e o ponteiro do mouse
    oDoc.Echo()
  

    doc.Echo(echoon = False, hourglass = True)
    ...
    doc.Echo()
  

ExportAsPDF

Exporta o documento diretamente como um arquivo PDF para o local especificado. Retorna True se o arquivo PDF foi criado com sucesso.

As opções de exportação podem ser definidas manualmente usando a caixa de diálogo Arquivo - Exportar como - Exportar como PDF ou chamando os métodos GetPDFExportOptions e SetPDFExportOptions do serviço Session .

svc.ExportAsPDF(filename: str, overwrite: bool = False, opt pages: str, opt password: str, opt watermark: str): bool

filename: o caminho completo e o nome de arquivo do PDF a criar. Deve seguir a notação SF_FileSystem.FileNaming.

overwrite: especifica se o arquivo de destino pode ser sobrescrito (padrão = False ). Ocorrerá um erro se overwrite for definido como False e o arquivo de destino já existir.

pages: string que especifica quais páginas serão exportadas. Este argumento usa a mesma notação da caixa de diálogo Arquivo - Exportar como - Exportar como PDF.

password: especifica uma senha para abrir o arquivo PDF.

watermark: texto a ser usado como marca d'água no arquivo PDF, a ser desenhado em todas as páginas do PDF resultante.

O exemplo a seguir exporta o documento atual como um arquivo PDF, define uma senha e substitui o arquivo de destino se ele já existir.

    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf", Password := "1234", Overwrite := True)
  

O trecho de código abaixo obtém as opções de exportação de PDF atuais e as usa para criar o arquivo PDF.

    Dim exportSettings as Object, oSession as Object
    oSession = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    ' Define como verdadeiro a opção de exportar comentários como notas em PDF
    exportSettings.ReplaceItem("ExportNotes", True)
    oSession.SetPDFExportOptions(exportSettings)
    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf")
  

    doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf", password = "1234", overwrite = True)
  

    session = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    exportSettings.ReplaceItem("ExportNotes", True)
    session.SetPDFExportOptions(exportSettings)
    doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf")
  

ImportStylesFromFile

Este método carrega todos os estilos pertencentes a uma ou mais famílias de estilos de um arquivo fechado no documento. O documento deve ser do Calc ou Writer.

São sempre importados juntos:

• ParagraphStyles e CharacterStyles

• NumberingStyles e ListStyles

Retorna True se os estilos foram importados com sucesso.

svc.ImportStylesFromFile(filename: str, families: str[1..*], overwrite = False): bool

filename: O arquivo do qual serão carregados os estilos, expresso na notação FileSystem. Presume-se que o arquivo seja do mesmo tipo de documento que o documento atual.

families: Uma das famílias de estilos presentes no documento, informada como uma string sensível à caixa ou uma lista de strings. Padrão = todas as famílias.

overwrite: Quando True, os estilos podem ser substituídos. O padrão é False.

    oDoc.ImportStylesFromFile("C:\User\Documents\myFile.ods", "ParagraphStyles", True)
  

    doc.ImportStylesFromFile('C:\User\Documents\myFile.ods', ("ParagraphStyles",), False)
  

PrintOut

Este método envia o conteúdo do documento para a impressora padrão ou para a impressora definida pelo método SetPrinter.

Retorna True se a impressão do documento foi bem-sucedida.

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

pages: String contendo as páginas a serem impressas, da mesma forma como é feita a definição usando a interface do usuário. Por exemplo: "1-4;10;15-18". O valor padrão é a impressão de todas as páginas.

copies: Número de cópias. O padrão é 1.

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

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

RemoveMenu

Remove um menu de primeiro nível da barra de menus de uma janela de documento.

Retorna True se o menu especificado foi removido. Se o menu não existir, o método retorna False.

Este método pode ser usado para remover qualquer entrada do menu de uma janela de documento, incluindo menus padrão. Contudo, nenhuma dessas mudanças na barra de menus é salva no documento ou nas configurações da aplicação. Para restaurar as barras de menu às configurações padrão, simplesmente feche e reabra a janela do documento.

svc.RemoveMenu(menuheader: str): bool

menuheader: Nome de primeiro nível do menu a ser removido.

    Dim oDoc as Object
    Set oDoc = CreateScriptService("Document")
    oDoc.RemoveMenu("Meu Menu")
  

    doc = CreateScriptService("Document")
    doc.RemoveMenu("Meu Menu")
  

Consulte a página da ajuda do serviço SFWidgets.Menu para aprender mais sobre como criar/remover menus em janelas de documento do LibreOffice.

RunCommand

Executa um comando UNO na janela de documento associada à instância do serviço. Alguns comandos típicos são: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

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

Comandos podem ser executados com ou sem argumentos. Argumentos não são validados antes de executar o comando. Se o comando ou seus argumentos forem inválidos, então nada acontecerá.

Para uma lista completa de comandos UNO que podem ser executadas no LibreOffice, consulte a página Wiki Development/DispatchCommands.

svc.RunCommand(command: str, [args: any])

command: String sensível à caixa contendo o nome do comando UNO. A inclusão do prefixo ".uno" ao comando é opcional. O comando em si não é verificado. Se nada acontecer após a chamada do comando, então o comando está provavelmente errado.

args: Para cada argumento a ser passado ao comando, especifique um par contendo o nome do argumento e seu valor.

O exemplo a seguir executa o comando SelectData em um arquivo Calc chamado "MeuArquivo.ods", o qual resultará na seleção da área de dados com base na célula selecionada. Note que este comando não requer argumentos.

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

Abaixo é dado um exemplo que executa o comando UNO ReplaceAll e passa valores para os argumentos SearchString e ReplaceString. Este comando substituirá todas as ocorrências da string "abc" por "ABC" na planilha atual.

    ' Argumentos passados ao comando:
    ' SearchString  = "abc"
    ' ReplaceString = "ABC"
    oDoc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

Note que chamar o comando ReplaceAll sem argumentos abrirá a caixa de diálogo Localizar e substituir.

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

    doc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

Em Python também é possível chamar RunCommand usando argumentos de palavra-chave:

    doc.RunCommand(".uno:ReplaceAll", SearchString = "abc", ReplaceString = "ABC")
  

Cada módulo do LibreOffice tem seu próprio conjunto de comandos disponíveis. Uma forma fácil de aprender comandos é indo em Ferramentas - Personalizar - Teclado. Quando você posicionar o mouse sobre uma função na lista Função, uma caixa de 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.

svc.Save(): bool

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

    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.

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

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.

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

    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.

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

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.

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

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

SetPrinter

Define as opções de impressão para o documento.

Retorna True se bem-sucedida.

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

printer: Nome da fila de impressão para a qual a impressão será enviada. Se ausente, a impressora padrão é usada.

orientation: Pode ser PORTRAIT ou LANDSCAPE. Se ausente, a orientação não é alterada e o valor definido nas configurações da impressora será usado.

paperformat: especifica o formato do papel como um valor de string que pode ser A3, A4, A5, LETTER , LEGAL ou TABLOID. Deixado inalterado quando ausente.

    oDoc.SetPrinter(Orientation := "PORTRAIT")
  

    doc.SetPrinter(paperformat='TABLOID')
  

Styles

Retorna uma lista de estilos que correspondem a um critério composto opcional. A lista retornada pode estar vazia. Aplica-se a todos os tipos de documentos, exceto Base.

svc.Styles(family, opt namepattern: str, opt used: bool, opt userdefined: bool, opt parentstyle: str, opt category: str): str[0..*])

category: Uma string com um dos seguintes valores (sensíveis à caixa): TEXT, CHAPTER, LIST, INDEX, EXTRA, HTML. Para saber mais sobre seus significados, consulte a página de documentação da API ParagraphStyleCategory.

Este argumento é ignorado quando a família não for "ParagraphStyles".

namepattern: Um filtro a ser aplicado aos nomes dos estilos, como uma string sensível à caixa. Os nomes incluem os nomes internos e localizados.

Os caracteres curingas permitidos são:

• "?" representa qualquer caractere único.

• "*" representa zero, um ou múltiplos caracteres.

parentstyle: quando presente, apenas os filhos do nome do estilo pai fornecido, localizado ou não, são retidos.

used: quando True, o estilo deve ser utilizado no documento; quando ausente o argumento é ignorado.

userdefined: quando True, o estilo deve ter sido adicionado pelo usuário, seja no documento ou em seu template; quando ausente o argumento é ignorado.

    Dim vStyles As Variant
    vStyles = oDoc.Styles("ParagraphStyles") ' Todos os estilos na família
    vStyles = oDoc.Styles("ParagraphStyles", "T*") ' Título, Título 1, ...
    vStyles = oDoc.Styles("ParagraphStyles", Used := False, UserDefined := True) ' Todos os estilos definidos pelo usuário que não são usados
    vStyles = oDoc.Styles("ParagraphStyles", ParentStyle := "Standard") ' Todos os estilos derivados do 'Estilo de parágrafo Padrão'
  

    vStyles = doc.Styles('ParagraphStyles')  # Todos os estilos na família
    vStyles = doc.Styles('ParagraphStyles', 'T*')  # Título, Título 1, ...
    vStyles = doc.Styles('ParagraphStyles', Used = False, UserDefined = True)  # Todos os estilos definidos pelo usuário que não são usados
    vStyles = doc.Styles('ParagraphStyles', ParentStyle = 'Standard")  # Todos os estilos derivados do "Estilo de parágrafo Padrão"
  

Toolbars

Este método retorna uma lista de nomes de barras de ferramentas disponíveis no documento ou uma instância do serviço SFWidgets.Toolbar.

svc.Toolbars(opt ToolbarName: str): uno
svc.Toolbars(): str[0..]

ToolbarName: O nome de uma das barras de ferramenta disponíveis.

    Dim oToolbar As Object
    Set oToolbar = oDoc.Toolbars("myToolbar")
  

    a_list = doc.Toolbars()
  

XStyles

Este método retorna a representação UNO de um determinado estilo para todos os tipos de documentos, exceto Base. Nothing é retornado quando StyleName não existe na família fornecida.

svc.XStyles(family: str, stylename: str): uno

stylename: Um dos estilos presentes em uma determinada família, como uma string sensível à caixa. O StyleName pode ser localizado ou não.

    Dim oStyle As Object
    Set oStyle = oDoc.XStyle("ParagraphStyle", "Heading 2")
  

    oStyle = doc.XStyle('ParagraphStyle', 'Heading 2')
  

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.