Serviço SFDocuments.Document

Conteúdo

# SFDocuments.Document serviço

A biblioteca SFDocuments disponibiliza métodos e propriedades para facilitar a gestão e a manipulação de documentos LibreOffice.

Os métodos aplicáveis a todos os tipos de documentos (documentos de texto, folhas de cálculo, apresentações, etc.) são fornecidos pelo serviço SFDocuments.Document. Alguns exemplos são:

- Abrir, fechar e guardar documentos

- Aceder a propriedades padrão ou personalizadas dos documentos

As propriedades, métodos ou argumentos assinalados com (*) NÃO se aplicam aos documentos Base.

Os métodos e propriedades específicos de determinados componentes LibreOffice são armazenados em serviços separados, tais como SFDocuments.SF_Calc e SFDocuments.SF_Base.

Embora a linguagem Basic não ofereça herança entre classes de objetos, estes últimos serviços podem ser considerados subclasses do serviço SFDocuments.Document. Essas subclasses podem invocar as propriedades e os métodos descritos abaixo.

## Chamada de serviço

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

A seguir apresentam-se três formas de invocar o serviço Document.

##### Em Basic

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

Em alternativa, pode utilizar os métodos CreateDocument e OpenDocument do serviço UI.

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

Utilizar o nome da janela, caso o documento já esteja aberto.

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

Utilizar o documento referenciado por ThisComponent. Isto é especialmente útil ao executar uma macro a partir do IDE do Basic.

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

A partir de uma macro acionada 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 com os serviços UI e FileSystem.

Exceto quando o documento for fechado pelo programa através do método CloseDocument (caso em que é supérfluo), recomenda-se libertar os recursos após a utilização:

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

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

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

A utilização do prefixo «SFDocuments.» ao chamar o serviço é opcional.

## Propriedades

Nome | Esta penalização ocorre de um incumprimento anterior (ainda não liquidado) sejasuperior a quatro trimestres consecutivos. | Tipo | Descrição
--- | --- | --- | ---
CustomProperties (*) | Não | Dictionary service | Devolve uma instância do objeto ScriptForge.Dictionary. Após a atualização, pode ser novamente passada à propriedade para atualizar o documento. Os itens individuais do dicionário podem ser cadeias de caracteres, números, datas (básicas) ou itens com.sun.star.util.Duration.
Description (*) | Não | String | Dá acesso à propriedade «Descrição» do documento (também conhecida como «Comentários»)
DocumentProperties (*) | Sim | Dictionary service | Devolve um objeto ScriptForge.Dictionary que contém todas as entradas. As estatísticas do documento estão incluídas. Note-se que estas são específicas do tipo de documento. Por exemplo, um documento Calc inclui uma entrada «CellCount». Outros documentos não a incluem.
DocumentType | Sim | String | Valor de cadeia de caracteres com o tipo de documento («Base», «Calc», «Writer», etc.)
ExportFilters (*) | Sim | String array | Devolve uma lista com os nomes dos filtros de exportação aplicáveis ao documento atual, sob a forma de uma matriz de cadeias de caracteres com indexação a partir de zero. Os filtros utilizados tanto para a importação como para a exportação também são devolvidos.
FileSystem | Sim | String | Devolve uma cadeia de caracteres com o caminho da URL para a raiz do sistema de ficheiros virtual do documento. Utilize o serviço FileSystem para visualizar o seu conteúdo, bem como para criar, abrir e ler os ficheiros nele armazenados. Consulte esta página de ajuda para saber mais sobre como aceder e manipular pastas e ficheiros no sistema de ficheiros virtual de um ficheiro LibreOffice.
ImportFilters (*) | Sim | String array | Devolve uma lista com os nomes dos filtros de importação aplicáveis ao documento atual, sob a forma de uma matriz de cadeias de caracteres com indexação a partir de zero. Os filtros utilizados tanto para a importação como para a exportação também são devolvidos.
IsAlive | Sim | Boolean | True quando o documento não foi fechado (por exemplo, por ação do utilizador).
IsBase IsCalc IsDraw IsFormDocument IsImpress IsMath IsWriter | Sim | Boolean | Exatamente uma destas propriedades é True para um determinado documento.
Keywords (*) | Não | String | Dá acesso à propriedade «Keywords» do documento. É representada como uma lista de palavras-chave separadas por vírgulas
MenuHeaders | Sim | String array | Devolve uma lista com os nomes dos menus presentes na barra de menus.
Readonly (*) | Sim | Boolean | True se o documento estiver efetivamente no modo de só leitura
StyleFamilies (*) | Sim | String array | Lista das famílias de estilos disponíveis. Aplicável a todos os tipos de documento, exceto o «Base».
Subject (*) | Não | String | Permite aceder à propriedade «Assunto» do documento.
Title (*) | Não | String | Permite aceder à propriedade «Title» do documento.
XComponent | Sim | Objeto UNO | O objeto UNO com.sun.star.lang.XComponent ou com.sun.star.comp.dba. ODatabaseDocument que representa o documento.
XDocumentSettings (*) | Sim | Objeto UNO | Um objeto UNO com.sun.star.XXX.DocumentSettings, em que XXX pode ser sheet, text, drawing ou presentation. Este objeto permite aceder às propriedades internas do UNO específicas do tipo de documento.

### Exemplo:

##### Em Basic

O exemplo abaixo apresenta todas as propriedades de um documento. Note-se que o objeto oDoc devolvido 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 aceder às propriedades de um documento num script Python, o utilizador tem de aceder diretamente a essas propriedades utilizando os respetivos nomes, conforme ilustrado 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 de Documentos
Activate CloseDocument ContextMenus CreateMenu DeleteStyles Echo | ExportAsPDF PrintOut RemoveMenu RunCommand Save SaveAs | SaveCopyAs SetPrinter Style Toolbars XStyle

## Activate

Devolve True se o documento puder ser ativado. Caso contrário, não se verifica qualquer alteração na interface de utilizador. É equivalente ao método Activate do serviço UI.

Este método é útil quando é necessário atribuir o foco a um documento que está minimizado ou oculto.

### Sintaxe:

svc.Activate(): bool

### Exemplo:

O exemplo abaixo parte do princípio de que o ficheiro «My_File.ods» já está aberto, mas 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()

Tenha em atenção que pode invocar o serviço Document passando para o CreateScriptService «Document» ou «SFDocuments.Document»

## CloseDocument

Fecha o documento. Se o documento já estiver fechado, independentemente da forma como foi fechado, este método não tem qualquer efeito e devolve False.

O método também devolverá False se o utilizador se recusar a fechá-lo.

Devolve True se o documento tiver sido fechado com sucesso.

### Sintaxe:

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

### Parâmetros:

saveask : Se for True (valor predefinido), o utilizador é convidado a confirmar se as alterações devem ser gravadas no disco. Este argumento é ignorado se o documento não tiver sido modificado.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## ContextMenus

Este método devolve uma lista dos menus de contexto disponíveis no próprio documento ou uma instância do serviço SFWidgets.ContextMenu.

### Sintaxe:

svc.ContextMenus(opt contextmenuname: str, submenuchar: str = ">"): svc
svc.ContextMenus(): str[0..]

### Parâmetros:

nome-do-menu-de-contexto: Um dos menus de contexto disponíveis. O nome de um menu de contexto é o último componente do URL do recurso: "private:resource/popupmenu/o-nome-aqui".

submenuchar: O delimitador utilizado para criar árvores de menus ao chamar métodos como AddItem a partir do serviço ContextMenu. O valor predefinido é ">".

### Exemplo:

##### Em Basic

                Dim oContextMenu As Object
                Set oContextMenu = oDoc.ContextMenus("cell")

##### Em Python

                a_list = doc.ContextMenus()

## CreateMenu

Cria uma nova opção de menu na barra de menus de uma determinada janela de documento.

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

O menu criado só está disponível durante a sessão atual do LibreOffice e não é guardado nem no documento nem nas definições globais da aplicação. Por conseguinte, ao fechar a janela do documento, o menu desaparecerá. Só voltará a aparecer quando a macro que cria o menu for executada novamente.

### Sintaxe:

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

### Parâmetros:

menuheader: O nome de nível superior do novo menu.

antes: O nome (como uma cadeia de caracteres) ou a posição (como um número inteiro a partir de 1) de um menu existente, antes do qual o novo menu será colocado. Se não for definido qualquer valor para este argumento, o menu será criado na última posição da barra de menus.

submenuchar: O delimitador utilizado para criar árvores de menus ao chamar métodos como AddItem a partir do serviço Menu. O valor predefinido é ">".

### Exemplo:

##### Em Basic

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

##### Em Python

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

Consulte a página de ajuda SFWidgets.Menu para saber mais sobre como criar/remover menus nas janelas de documentos do LibreOffice.

## DeleteStyles

Suprime um único estilo ou um conjunto de estilos, indicados pelos seus nomes, dentro de uma família de estilos específica. Apenas os estilos definidos pelo utilizador podem ser eliminados; os estilos predefinidos são ignorados. Aplica-se a todos os tipos de documento, exceto Base e FormDocument.

### Sintaxe:

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

### Parâmetros:

família: Uma das famílias de estilos presentes no documento atual, representada por uma cadeia de caracteres que distingue maiúsculas de minúsculas. Os nomes de famílias válidos podem ser obtidos através da propriedade StyleFamilies.

styleslist: Um único nome de estilo, na forma de uma cadeia de caracteres, ou um conjunto de nomes de estilos. Os nomes de estilos podem ou não estar localizados. A StylesList é, normalmente, o resultado da execução do método Styles().

### Exemplo:

##### Em Basic

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

##### Em Python

        # Remoção de estilos com base num prefixo
        a_list = doc.Styles('ParagraphStyles', namepattern = "Py*")
        doc.Styles('ParagraphStyles', a_list)

## Echo

Suspende as atualizações da interface do utilizador (UI) durante a execução de uma macro. Opcionalmente, o ponteiro do rato pode ser alterado para uma ampulheta enquanto as atualizações da UI estão suspensas.

Este método pode proporcionar algumas vantagens em termos de desempenho para macros que executam inúmeras operações que exigem atualizações da interface do utilizador.

### Sintaxe:

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

### Parâmetros:

echoon: Especifique False para suspender as atualizações da interface do utilizador. O valor predefinido é True, o que ativa as atualizações da interface do utilizador em tempo real.

ampulheta: Especifique True para alterar o ponteiro do rato para uma ampulheta (Predefinição = False).

Se mover o ponteiro do rato depois de este ter mudado para uma ampulheta pode fazer com que ele mude para um ponteiro diferente, dependendo do seu novo fundo.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## ExportAsPDF

Exporta o documento diretamente como um ficheiro PDF para o local especificado. Devolve True se o ficheiro PDF tiver sido criado com sucesso.

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

### Sintaxe:

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

### Parâmetros:

nome do ficheiro: O caminho completo e o nome do ficheiro PDF a criar. Deve seguir a notação SF_FileSystem.FileNaming.

overwrite: Especifica se o ficheiro de destino pode ser substituído (Predefinição = False). Ocorrerá um erro se overwrite estiver definido como False e o ficheiro de destino já existir.

páginas: String que especifica quais as páginas que serão exportadas. Este argumento utiliza a mesma notação que na caixa de diálogo Ficheiro - Exportar como - Exportar como PDF.

palavra-passe: Especifica uma palavra-passe para abrir o ficheiro PDF.

marca de água: Texto a utilizar como marca de água no ficheiro PDF, que será inserido em todas as páginas do PDF resultante.

### Exemplo:

##### Em Basic

O exemplo seguinte exporta o documento atual como um ficheiro PDF, define uma palavra-passe e substitui o ficheiro de destino, caso este já exista.

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

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

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

##### Em Python

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

## PrintOut

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

Devolve True se o documento tiver sido impresso com sucesso.

### Sintaxe:

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

### Parâmetros:

páginas: As páginas a imprimir, expressas como uma cadeia de caracteres, tal como na interface do utilizador. Exemplo: «1-4;10;15-18». Por predefinição, são impressas todas as páginas.

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## RemoveMenu

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

Devolve True se for possível remover o menu especificado. Se o menu especificado não existir, o método devolve False.

Este método pode ser utilizado para remover qualquer opção do menu da janela do documento, incluindo os menus predefinidos. No entanto, nenhuma destas alterações na barra de menus é guardada no documento nem nas definições da aplicação. Para restabelecer as definições predefinidas da barra de menus, basta fechar e voltar a abrir a janela do documento.

### Sintaxe:

svc.RemoveMenu(menuheader: str): bool

### Parâmetros:

menuheader: O nome de nível superior do menu a ser removido.

### Exemplo:

##### Em Basic

        Dim oDoc as Object
        Set oDoc = CreateScriptService("Document")
        oDoc.RemoveMenu("O meu menu")

##### Em Python

        doc = CreateScriptService("Document")
        doc.RemoveMenu("O meu menu")

Consulte a página de ajuda SFWidgets.Menu para saber mais sobre como criar/remover menus nas janelas de documentos do LibreOffice.

## RunCommand

Executa um comando UNO na janela do documento associada à instância do serviço. Alguns comandos típicos são: Guardar, Guardar como, Exportar para PDF, Desfazer, Copiar, Colar, etc.

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

Os comandos podem ser executados com ou sem argumentos. Os argumentos não são validados antes da execução do comando. Se o comando ou os seus argumentos forem inválidos, nada acontecerá.

Para obter uma lista completa dos comandos UNO que podem ser executados no LibreOffice, consulte a página da Wiki Development/DispatchCommands.

### Sintaxe:

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

### Parâmetros:

comando: Cadeia de caracteres que distingue maiúsculas de minúsculas e que contém o nome do comando UNO. A inclusão do prefixo «.uno:» no comando é opcional. A correção do comando em si não é verificada. Se nada acontecer após a execução do comando, é provável que o comando esteja errado.

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

### Exemplo:

##### Em Basic

O exemplo seguinte executa o comando SelectData num ficheiro do Calc denominado «MyFile.ods», o que resultará na seleção da área de dados com base na célula atualmente selecionada. Note-se que este comando não requer quaisquer argumentos.

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

Segue-se um exemplo que executa o comando UNO ReplaceAll e passa valores para os seus argumentos SearchString e ReplaceString. A execução deste comando irá substituir todas as ocorrências da cadeia de caracteres «abc» por «ABC» na folha atual.

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

Note que, ao executar o comando ReplaceAll sem argumentos, será aberta a caixa de diálogo Encontrar e Substituir.

##### Em Python

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

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

Em Python, também é possível chamar RunCommand utilizando argumentos-chave:

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

Cada componente LibreOffice tem o seu próprio conjunto de comandos disponíveis. Uma forma fácil de aprender os comandos é aceder a Ferramentas - Personalizar - Teclado. Quando passar o rato por cima de uma função na lista Função, aparecerá uma dica de ferramenta com o comando UNO correspondente.

## Save

Guarda o documento no local do ficheiro a partir do qual foi carregado. O método é ignorado se o documento não tiver sido alterado.

Devolve False se o documento não puder ser guardado. É gerado um erro se o ficheiro estiver aberto apenas para leitura ou se for um ficheiro novo que ainda não tenha sido guardado.

Não é necessário que o documento esteja 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

Guarda o documento no local de ficheiro indicado. O novo local passa a ser o novo nome do ficheiro ao qual serão aplicadas as chamadas simples ao método «Guardar».

Devolve False se o documento não puder ser guardado. É gerado um erro quando a substituição do destino é rejeitada ou quando o destino tem o atributo «somente leitura» definido.

Não é necessário que o documento esteja ativo para executar este método.

### Sintaxe:

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

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que contém o nome do ficheiro a utilizar. Deve seguir a notação SF_FileSystem.FileNaming.

substituir: Se True, o ficheiro de destino pode ser substituído (valor predefinido = False).

palavra-passe (*): Uma sequência de caracteres que não contenha espaços, para proteger o documento.

filtername (*): O nome de um filtro que deve ser utilizado para guardar o documento. Se este argumento for passado, o filtro tem de existir.

filteroptions (*): Uma cadeia de opções opcional associada 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

Guarda uma cópia do documento ou exporta-o para o local de ficheiro indicado. A localização original permanece inalterada.

Devolve False se o documento não puder ser guardado. É gerado um erro quando a substituição do destino é rejeitada ou quando o destino tem o atributo «somente leitura» definido.

Não é necessário que o documento esteja ativo para executar este método.

### Sintaxe:

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

### Parâmetros:

nome do ficheiro: Uma cadeia de caracteres que contém o nome do ficheiro a utilizar. Deve seguir a notação SF_FileSystem.FileNaming.

substituir: Se True, o ficheiro de destino pode ser substituído (valor predefinido = False).

palavra-passe (*): Uma sequência de caracteres que não contenha espaços, para proteger o documento.

filtername (*): O nome de um filtro que deve ser utilizado para guardar o documento. Se este argumento for passado, o filtro tem de existir.

filteroptions (*): Uma cadeia de opções opcional associada ao filtro.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## SetPrinter

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

Devolve True em caso de sucesso.

### Sintaxe:

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

### Parâmetros:

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(Orientation := "PORTRAIT")

##### Em Python

        doc.SetPrinter(paperformat='TABLOID')

## Styles

Recupera uma lista de estilos que correspondem a um critério composto opcional; o array devolvido pode estar vazio. Aplica-se a todos os tipos de documento, exceto Base.

### Sintaxe:

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

família: Uma das famílias de estilos presentes no documento atual, representada por uma cadeia de caracteres que distingue maiúsculas de minúsculas. Os nomes de famílias válidos podem ser obtidos através da propriedade StyleFamilies.

categoria: Uma cadeia de caracteres que não distingue maiúsculas de minúsculas: TEXT, CHAPTER, LIST, INDEX, EXTRA, HTML. Para conhecer os respetivos significados, consulte a documentação da API sobre categoria de estilo de parágrafo.

Este argumento é ignorado quando a «Família» difere de «ParagraphStyles».

namepattern: Um filtro para os nomes dos estilos, sob a forma de um padrão de cadeia de caracteres que distingue maiúsculas de minúsculas. Os nomes incluem os nomes internos e os nomes localizados.

Os participantes admitidos por convite são:

- o «?» representa qualquer carácter único.

- onde o «*» representa zero, um ou vários caracteres

parentstyle: Quando presente, apenas os elementos filhos do nome do estilo pai especificado, localizado ou não, são mantidos.

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

userdefined: Quando True, o estilo deve ter sido adicionado pelo utilizador, quer no documento, quer no respetivo modelo; caso não exista, o argumento é ignorado.

### Exemplo:

##### Em Basic

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

##### Em Python

        vStyles = doc.Styles('ParagraphStyles')  # Todos os estilos da família
        vStyles = doc.Styles('ParagraphStyles', 'H*')  #Título, Título 1, ...
        vStyles = doc.Styles('ParagraphStyles', Used = False, UserDefined = True)  # Todos os estilos definidos pelo utilizador que não estão a ser utilizados
        vStyles = doc.Styles('ParagraphStyles', ParentStyle = 'Standard')  # Todos os estilos derivados do «Estilo de parágrafo predefinido»

## Toolbars

Este método devolve uma lista dos nomes das barras de ferramentas disponíveis no documento em questão ou uma instância do serviço SFWidgets.Toolbar.

### Sintaxe:

svc.Toolbars(opt toolbarname: str): svc
svc.Toolbars(): str[0..]

### Parâmetros:

nome-da-barra-de-ferramentas: O nome habitual de uma das barras de ferramentas disponíveis.

### Exemplo:

##### Em Basic

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

##### Em Python

        a_list = doc.Toolbars()

## XStyles

Este método devolve a representação UNO de um determinado estilo para todos os tipos de documento, exceto Base. É devolvido Nothing quando o StyleName não existe na família indicada.

### Sintaxe:

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

### Parâmetros:

família: Uma das famílias de estilos presentes no documento atual, representada por uma cadeia de caracteres que distingue maiúsculas de minúsculas. Os nomes de famílias válidos podem ser obtidos através da propriedade StyleFamilies.

stylename: Um dos estilos presentes na família indicada, sob a forma de uma cadeia de caracteres que distingue maiúsculas de minúsculas. O StyleName pode ou não ser localizado.

### Exemplo:

##### Em Basic

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

##### Em Python

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

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

ScriptForge.Dicionário serviço

ScriptForge.UI service

SFWidgets.Menu service

Necessitamos da sua ajuda!