SFDocuments.Calc service

Conteúdo

# Serviço SFDocuments.Calc

A biblioteca partilhada SFDocuments disponibiliza vários métodos e propriedades para facilitar a gestão e o manuseamento de documentos LibreOffice.

O serviço SFDocuments.Calc é uma subclasse do serviço SFDocuments.Document. Todos os métodos e propriedades definidos para o serviço Document também podem ser acedidos utilizando uma instância do serviço Calc.

O serviço Calc centra-se em:

- Manipular folhas num documento do Calc (copiar, inserir, mover, etc.)

- Troca de dados entre estruturas de dados básicas e intervalos do Calc

- Copiar e importar grandes quantidades de dados

- Formatação simples de intervalos de células

Esta página de ajuda descreve métodos e propriedades que se aplicam apenas a documentos do Calc.

## Chamada de serviço

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

O serviço Calc está intimamente relacionado com o serviço UI da biblioteca ScriptForge. Seguem-se alguns exemplos de como o serviço Calc pode ser invocado.

##### Em Basic

O trecho de código abaixo cria uma instância do serviço Calc que corresponde ao documento do Calc atualmente ativo.

        Set oDoc = CreateScriptService("Calc")

Outra forma de criar uma instância do serviço Calc é utilizando o serviço UI. No exemplo seguinte, é criado um novo documento Calc e oDoc é uma instância do serviço Calc:

        Dim ui As Object, oDoc As Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.CreateDocument("Calc")

Ou utilizando o método OpenDocument do serviço UI:

        Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")

Também é possível instanciar o serviço Calc especificando um nome de janela para o método CreateScriptService:

        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")

No exemplo acima, «MyFile.ods» é o nome de uma janela de documento aberta. Se este argumento não for fornecido, considera-se a janela ativa.

Também é possível invocar o serviço Calc utilizando 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("Calc", ThisComponent)

Recomenda-se libertar os recursos após a utilização:

        Set oDoc = oDoc.Dispose()

No entanto, se o documento tiver sido fechado através do método CloseDocument, não é necessário libertar os recursos utilizando o comando acima descrito.

##### Em Python

        myDoc = CreateScriptService("Calc")

        ui = CreateScriptService("UI")
        myDoc = ui.CreateDocument("Calc")

        myDoc = ui.OpenDocument(r"C:\Documents\MyFile.ods")

        myDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")
        myDoc.Dispose()

        bas = CreateScriptService("Basic")
        myDoc = CreateScriptService("Calc", bas.ThisComponent)

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

## Definições

Muitos métodos requerem uma «Sheet» ou um «Range» como argumento. As células individuais são consideradas um caso especial de um Range.

Ambos podem ser expressos como uma cadeia de caracteres ou como uma referência (= objeto), dependendo da situação:

- Numa instância específica do Calc, as folhas e os intervalos são indicados como cadeias de caracteres, tais como «Sheet1» e «D2:F6».

- Além disso, as propriedades .Sheet e .Range devolvem uma referência que pode ser utilizada como argumento de um método chamado a partir de outra instância do serviço Calc.

### Exemplo:

O exemplo abaixo copia dados do documento A (aberto em modo de leitura e oculto) para o documento B.

##### Em Basic

        Dim oDocA As Object, oDocB As Object
        Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
        Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
        oDocB.CopyToRange(oDocA.Range("SheetX.D4:F8"), "D2:F6") 'CopyToRange(source, target)

##### Em Python

        docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopyToRange(docA.Range("SheetX.D4:F8"), "D2:F6")

### SheetName

O nome da folha como uma string ou um object gerado pela propriedade .Sheet.

O atalho "~" (til) representa a folha atual.

### RangeName

Pode ser uma cadeia de caracteres que designa um conjunto de células contíguas localizadas numa folha da instância atual ou um object gerado pela propriedade .Range.

O atalho «~» (tilde) representa a seleção atual ou o primeiro intervalo selecionado, caso estejam selecionados vários intervalos.

O atalho «*» representa todas as células utilizadas.

O nome da folha é opcional ao definir um intervalo. Se não for indicado nenhum nome de folha, é utilizada a folha ativa. As aspas simples e os símbolos $ à esquerda e à direita são permitidos, mas são ignorados.

Ao especificar um SheetName como uma cadeia de caracteres, é necessário utilizar aspas simples para delimitar o nome da folha, caso este contenha espaços " " ou pontos ".".

Os exemplos abaixo ilustram em que casos é obrigatório o uso de aspas simples:

          O uso de aspas simples é opcional
          oDoc.clearAll("SheetA.A1:B10")
          oDoc.clearAll("'SheetA'.A1:B10")
          ' É obrigatório o uso de aspas simples
          oDoc.clearAll("'Sheet.A'.A1:B10")

Com exceção da propriedade CurrentSelection, o serviço Calc considera apenas intervalos únicos de células.

Exemplos de intervalos válidos
1) $'SheetX'.D2 2) $D$2 | Uma única célula
1) $'SheetX'.D2:F6 2) D2:D10 | Gama única com várias células
$'SheetX'.* | Todas as células utilizadas na folha em questão
1) $'SheetX'.A:A (coluna A) 2) 3:5 (linhas 3 a 5) | Todas as células em colunas ou linhas contíguas até à última célula utilizada
myRange | Um intervalo denominado «myRange» ao nível da folha de cálculo
1) ~.someRange 2) SheetX.someRange | Um nome de intervalo ao nível da folha
myDoc.Range("SheetX.D2:F6") | Um intervalo na folha SheetX do ficheiro associado à instância myDoc Calc
~.~ ou ~ | A seleção atual na folha ativa

## Propriedades

Todas as propriedades genéricas de qualquer documento aplicam-se implicitamente também aos documentos do Calc. Para mais informações, consulte a página de ajuda do serviço de documentos .

As propriedades especificamente disponíveis para documentos do Calc são:

Nome | Somente leitura | Argumento | Tipo de retorno | Descrição
--- | --- | --- | --- | ---
CurrentSelection | Não | Nenhum | Cadeia de caracteres ou matriz de cadeias de caracteres | O intervalo único selecionado como uma cadeia de caracteres ou a lista de intervalos selecionados como uma matriz.
DefinedNames | Sim | Nenhum | Cadeia de caracteres ou matriz de cadeias de caracteres | Devolve a lista completa e ordenada de todos os intervalos nomeados no documento. Os nomes definidos numa única folha são precedidos do nome da folha.
FirstCell | Sim | Nome da folha ou Nome do intervalo como String | String | Devolve a primeira célula utilizada num determinado intervalo ou folha.
FirstColumn | Sim | Nome da folha ou Nome do intervalo como String | Long | Devolve o número da coluna mais à esquerda num determinado intervalo ou folha.
FirstRow | Sim | Nome da folha ou Nome do intervalo como String | Long | Devolve o número da linha superior de um determinado intervalo ou folha.
Height | Sim | RangeName como String | Long | O número de linhas (>= 1) no intervalo indicado.
LastCell | Sim | SheetName ou RangeName como uma String | String | Devolve a última célula utilizada num determinado intervalo ou folha.
LastColumn | Sim | SheetName ou RangeName como uma String | Long | A última coluna utilizada num determinado intervalo ou folha.
LastRow | Sim | SheetName ou RangeName como uma String | Long | A última linha utilizada num determinado intervalo ou folha.
Range | Sim | RangeName como uma String | Object | Uma referência a um intervalo que pode ser utilizada como argumento de métodos como CopyToRange.
Region | Sim | RangeName como uma String | String | Devolve o endereço da área mais pequena que contém o intervalo especificado, de modo a que essa área esteja rodeada por células vazias ou pelas margens da folha. Isto equivale a aplicar o atalho de teclado Command + *Ctrl + * ao intervalo indicado.
Sheet | Sim | SheetName como uma String | Object | Uma referência a uma folha que pode ser utilizada como argumento de métodos como CopySheet.
SheetName | Sim | RangeName como uma String | String | Devolve o nome da folha correspondente a um determinado endereço de intervalo.
Sheets | Sim | Nenhum | Matriz de cadeias de caracteres | A lista com os nomes de todas as folhas existentes.
Width | Sim | RangeName como uma String | Long | O número de colunas (>= 1) no intervalo indicado.
XCellRange | Sim | RangeName como uma String | Object | Um objeto UNO com.sun.star.Table.XCellRange.
XRectangle | Sim | RangeName como uma String | Object | Uma estrutura UNO com.sun.star.awt.Rectangle, que descreve, em píxeis, a área do ecrã onde o intervalo se encontra.
XSheetCellCursor | Sim | RangeName como uma String | Object | Um objeto UNO com.sun.star.sheet.XSheetCellCursor. Após mover o cursor, o endereço do intervalo resultante pode ser acedido através da propriedade UNO AbsoluteName do objeto cursor, que devolve um valor de cadeia de caracteres que pode ser utilizado como argumento para propriedades e métodos do serviço Calc.
XSpreadsheet | Sim | SheetName como uma String | Object | Um objeto UNO com.sun.star.sheet.XSpreadsheet.

Visite o site da documentação da API LibreOffice para saber mais sobre XCellRange,XSheetCellCursor e XSpreadsheet objetos UNO.

## Métodos

Lista de métodos no serviço Calc
A1Style Activate AlignRange BorderRange Charts ClearAll ClearFormats ClearValues ColorizeRange CompactLeft CompactUp CopySheet CopySheetFromFile CopyToCell CopyToRange CreateChart CreatePivotTable DAvg | DCount DecorateFont DefineName DMax DMin DSum ExportRangeToFile FormatRange Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase ImportStylesFromFile InsertSheet Intersect MoveRange | MoveSheet Offset OpenRangeSelector PrintOut Printf RemoveDuplicates RemoveSheet RenameSheet SetArray SetCellStyle SetFormula SetValue ShiftDown ShiftLeft ShiftRight ShiftUp SortRange

## A1Style

Devolve o endereço de um intervalo como uma cadeia de caracteres com base nas coordenadas da folha, ou seja, nos números da linha e da coluna.

Se for fornecido apenas um par de coordenadas, é devolvido o endereço de uma única célula. Argumentos adicionais podem especificar a célula inferior direita de um intervalo retangular.

### Sintaxe:

svc.A1Style(row1: int, column1: int, row2: int = 0; column2: int = 0; sheetname: str = "~"): str

### Parâmetros:

row1, column1: Especifique os números da linha e da coluna da célula no canto superior esquerdo do intervalo a considerar. Os números das linhas e das colunas começam em 1.

row2, column2: Especifique os números da linha e da coluna da célula inferior direita do intervalo a considerar. Se estes argumentos não forem fornecidos, ou se forem fornecidos valores inferiores a row1 e column1, é devolvido o endereço da célula única representada por row1 e column1.

sheetname: O nome da folha a ser anexada ao endereço do intervalo devolvido. A folha deve existir. O valor predefinido é "~", correspondendo à folha atualmente ativa.

### Exemplo:

Os exemplos abaixo, em Basic e Python, partem do princípio de que a «Sheet1» é a folha atualmente ativa.

##### Em Basic

        Set oDoc = CreateScriptService("Calc")
        addr1 = oDoc.A1Style(1, 1) ' '$Sheet1'.$A$1
        addr2 = oDoc.A1Style(2, 2, 3, 6) ' '$Sheet1'.$B$2:$F$3
        addr3 = oDoc.A1Style(2, 2, 0, 6) ' '$Sheet1'.$B$2
        addr4 = oDoc.A1Style(3, 4, 3, 8, "Sheet2") ' '$Sheet2'.$D$3:$H$3
        addr5 = oDoc.A1Style(5, 1, SheetName := "Sheet3") ' '$Sheet3'.$A$5

##### Em Python

        doc = CreateScriptService("Calc")
        addr1 = doc.A1Style(1, 1) # '$Sheet1'.$A$1
        addr2 = doc.A1Style(2, 2, 3, 6) # '$Sheet1'.$B$2:$F$3
        addr3 = doc.A1Style(2, 2, 0, 6) # '$Sheet1'.$B$2
        addr4 = doc.A1Style(3, 4, 3, 8, "Sheet2") # '$Sheet2'.$D$3:$H$3
        addr5 = doc.A1Style(5, 1, sheetname="Sheet3") # '$Sheet3'.$A$5

O método A1Style pode ser combinado com qualquer uma das muitas propriedades e métodos do serviço Calc que exijam um intervalo como argumento, tais como GetValue, GetFormula, ClearAll, etc.

## Activate

Se for fornecido o argumento sheetname, a folha indicada é ativada e passa a ser a folha atualmente selecionada. Se o argumento não for fornecido, a janela do documento é ativada.

### Sintaxe:

svc.Activate(sheetname: str = ""): bool

### Parâmetros:

sheetname: O nome da folha a ativar no documento. O valor predefinido é uma cadeia de caracteres vazia, o que significa que a janela do documento será ativada sem alterar a folha ativa.

### Exemplo:

O exemplo abaixo ativa a folha denominada «Sheet4» no documento atualmente ativo.

##### Em Basic

        Dim ui as Variant, oDoc as Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.GetDocument(ui.ActiveWindow)
        oDoc.Activate("Sheet4")

##### Em Python

        ui = CreateScriptService("UI")
        myDoc = ui.GetDocument(ui.ActiveWindow)
        myDoc.Activate("Sheet4")

A ativação de uma folha só faz sentido se for realizada num documento Calc. Para se certificar de que tem um documento Calc disponível, pode utilizar a propriedade isCalc do objeto documento, que devolve True se for um documento Calc e False caso contrário.

## AlignRange

Alinhar horizontalmente ou verticalmente um intervalo de células.

É possível definir uma fórmula de filtro para determinar quais as células que serão afetadas.

### Sintaxe:

svc.AlignRange(targetrange: str, alignment: str, opt filterformula: str, opt filterscope: str)

### Parâmetros:

targetrange: A célula ou o intervalo, expresso como uma cadeia de caracteres, no qual as células devem ser realinhadas.

alinhamento: uma sequência que combina 1 ou 2 dos próximos caracteres maiúsculos (os restantes são ignorados):

- E, D ou C: esquerda, direita ou centro na horizontal.

- I, S ou C: inferior, superior ou centro na vertical (meio).

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

          ' Alinhar todas as células numéricas ao centro, tanto na horizontal como na vertical.
          doc.AlignRange("SheetX.A1:J30", "Middle,Center", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

          # Centralizar todas as células numéricas, tanto na horizontal como na vertical.
          doc.AlignRange('SheetX.A1:J30', 'Middle,Center', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## BorderRange

Aplicar um conjunto de bordas de linha dentro e à volta de um conjunto de células.

As células afetadas podem ser identificadas através de uma fórmula de filtro e do seu âmbito de aplicação.

Todas as bordas têm a mesma largura, estilo e cor padrão. As linhas de borda já existentes nas células, linhas ou colunas afetadas são primeiro removidas. As restantes células do intervalo permanecem inalteradas.

Para limpar todo o intervalo, defina border como "" e omita o argumento filterformula.

### Sintaxe:

svc.BorderRange(targetrange: str, border: str, opt filterformula: str, opt filterscope: str)

### Parâmetros:

targetrange: A célula ou o intervalo, expresso como uma cadeia de caracteres, ao qual devem ser aplicadas as bordas.

border: Uma cadeia de caracteres que combina os próximos caracteres maiúsculos (os restantes são ignorados):

- I, E, S, D: linhas exteriores inferior, esquerda, superior e direita.

- H, V: linhas internas horizontais e verticais.

- B, C: diagonais de baixo para cima e de cima para baixo.

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

            ' Aplique uma moldura com uma linha inferior a todas as células numéricas, incluindo as linhas horizontais internas.
            doc.BorderRange("SheetX.A1:J30", "HB", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

            # Aplique uma moldura inferior a todas as células numéricas, incluindo as linhas horizontais internas.
            doc.BorderRange('SheetX.A1:J30', 'HB', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## Charts

Devolve a lista com os nomes de todos os objetos de gráfico numa determinada folha ou uma única instância do serviço Chart.

- Se apenas sheetname for especificado, é devolvida uma matriz de cadeias de caracteres com índice a partir de zero, contendo os nomes de todos os gráficos.

- Se for fornecido um chartname, é devolvido um único objeto correspondente ao gráfico pretendido. O gráfico especificado deve existir.

### Sintaxe:

svc.Charts(sheetname: str, chartname: str = ""): obj

### Parâmetros:

sheetname: O nome da folha da qual se pretende recuperar a lista de gráficos ou onde se encontra o gráfico especificado.

chartname: O nome definido pelo utilizador do objeto gráfico a ser devolvido. Se o gráfico não tiver um nome definido pelo utilizador, pode ser utilizado o nome interno do objeto. Se este argumento estiver ausente, é devolvida a lista de nomes de gráficos na folha especificada.

Utilize a barra lateral Navegador para verificar os nomes atribuídos aos gráficos na categoria Objetos OLE.

### Exemplo:

##### Em Basic

O exemplo abaixo mostra o número de objetos de gráfico na «Folha1».

        Dim arrNames as Object
        arrNames = oDoc.Charts("Sheet1")
        MsgBox "There are " & UBound(arrNames) + 1 & " charts in Sheet1"

O exemplo seguinte acede ao gráfico denominado «MyChart» na «Sheet1» e apresenta o seu tipo.

        Dim oChart as Object
        oChart = oDoc.Charts("Sheet1", "MyChart")
        MsgBox oChart.ChartType

##### Em Python

        bas = CreateScriptService("Basic")
        chart_names = doc.Charts("Sheet1")
        bas.MsgBox(f"There are {len(chart_names)} charts in Sheet1")

        chart = doc.Charts("Sheet1", "MyChart")
        bas.MsgBox(chart.ChartType)

## ClearAll

Limpa todo o conteúdo e formata o intervalo indicado.

É possível definir uma fórmula de filtro para determinar quais as células que serão afetadas.

### Sintaxe:

svc.ClearAll(range: str, opt filterformula: str, opt filterscope: str)

### Parâmetros:

range: O intervalo a ser apagado, na forma de uma cadeia de caracteres.

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

        ' Limpa todas as células do intervalo FolhaX.A1:J10
        oDoc.ClearAll("SheetX.A1:J10")
        ' Limpa todas as células do intervalo FolhaX.A1:J10 que tenham um valor superior a 100
        oDoc.ClearAll("SheetX.A1:J10", "=SheetX.A1>100", "CELL")
        ' Limpa todas as linhas do intervalo SheetX.A1:J10 cuja soma seja superior a 500
        oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:J1)>500", "ROW")
        ' Limpa todas as colunas no intervalo SheetX.A1:J10 cuja soma seja superior a 500
        oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:A10)>500", "COLUMN")

##### Em Python

        myDoc.ClearAll("SheetX.A1:F10")
        myDoc.ClearAll("SheetX.A1:J10", "=SheetX.A1>100", "CELL")
        myDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:J1)>500", "ROW")
        myDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:A10)>500", "COLUMN")

## ClearFormats

Limpa os formatos e os estilos das células no intervalo indicado.

É possível definir uma fórmula de filtro para determinar quais as células que serão afetadas.

### Sintaxe:

svc.ClearFormats(range: str, opt filterformula: str, opt filterscope: str)

### Parâmetros:

range: O intervalo cujos formatos e estilos devem ser apagados, na forma de uma cadeia de caracteres.

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

          oDoc.ClearFormats("SheetX.*")

##### Em Python

        myDoc.ClearFormats("SheetX.*")

Consulte a documentação do método ClearAll para obter exemplos sobre como utilizar os argumentos filterformula e filterscope.

## ClearValues

Limpa os valores e as fórmulas no intervalo indicado.

É possível definir uma fórmula de filtro para determinar quais as células que serão afetadas.

### Sintaxe:

svc.ClearValues(range: str, opt filterformula: str, opt filterscope: str)

### Parâmetros:

range: O intervalo cujos valores e fórmulas devem ser apagados, na forma de uma cadeia de caracteres.

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

          oDoc.ClearValues("SheetX.A1:F10")

##### Em Python

        myDoc.ClearValues("SheetX.A1:F10")

Consulte a documentação do método ClearAll para obter exemplos sobre como utilizar os argumentos filterformula e filterscope.

## ColorizeRange

Defina as cores de primeiro plano e de fundo de um intervalo de células.

As células afetadas podem ser identificadas através de uma fórmula de filtro e do seu âmbito de aplicação.

### Sintaxe:

svc.ColorizeRange(targetrange: str, opt foreground: int, opt background: int, opt filterformula: str, opt filterscope: str)

### Parâmetros:

targetrange: a célula ou o intervalo, expresso como uma cadeia de caracteres, no qual as células devem ser (re)coloridas.

foreground: a cor de primeiro plano como resultado da função RGB(). Um valor negativo apaga a cor de primeiro plano

background: a cor de fundo é o resultado da função RGB(). Um valor negativo apaga a cor de fundo

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

            ' Pinte a(s) célula(s) com valores numéricos a vermelho.
            doc.ColorizeRange("SheetX.A1:J30", background := RGB(255, 0, 0), filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

            # Pinte a(s) célula(s) com valores numéricos de vermelho.
            basic = CreateScriptService('basic')
            doc.ColorizeRange('SheetX.A1:J30', background = basic.RGB(255, 0, 0), filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## CompactLeft

Elimina as colunas de um intervalo especificado que correspondam a um filtro expresso como uma fórmula do Calc. O filtro é aplicado a cada coluna para determinar se esta será eliminada ou não.

A coluna a eliminar pode ser limitada à altura do intervalo especificado ou estender-se até à altura de toda a folha, permitindo assim eliminar colunas inteiras.

Este método devolve uma cadeia de caracteres com o endereço do intervalo compactado. Se todas as colunas forem eliminadas, é devolvida uma cadeia de caracteres vazia.

Se for selecionado um intervalo de células, a chamada deste método não afetará a seleção.

### Sintaxe:

svc.CompactLeft(range: str, wholecolumn: bool = False, opt filterformula: str): str

### Parâmetros:

intervalo: O intervalo a partir do qual as colunas serão eliminadas, expresso como uma cadeia de caracteres.

wholecolumn: Se esta opção for definida como True, toda a coluna será eliminada da folha. O valor predefinido é False, o que significa que a coluna eliminada ficará limitada à altura do intervalo especificado.

filterformula: O filtro a aplicar a cada coluna para determinar se esta será ou não eliminada. O filtro é expresso como uma fórmula do Calc que deve ser aplicada à primeira coluna. Quando a fórmula devolver True para uma coluna, essa coluna será eliminada. O filtro predefinido elimina todas as colunas vazias.

Por exemplo, suponha que o intervalo A1:J200 esteja selecionado (altura = 200), pelo que a fórmula predefinida é =(COUNTBLANK(A1:A200)=200). Isto significa que, se todas as 200 células da primeira coluna (Coluna A) estiverem vazias, a coluna é eliminada. Note que a fórmula é expressa apenas em relação à primeira coluna. Internamente, o método CompactLeft generalizará esta fórmula para todas as colunas restantes.

As funções do Calc utilizadas no argumento filterformula devem ser indicadas utilizando os seus nomes em inglês. Consulte a página da Wiki Lista de funções do Calc para obter uma lista completa das funções do Calc em inglês.

### Exemplo:

##### Em Basic

        ' Eliminar todas as colunas vazias no intervalo G1:L10 da Folha1
        newrange = oDoc.CompactLeft("Sheet1.G1:L10")
        ' O exemplo abaixo é semelhante, mas toda a coluna é eliminada da folha
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", WholeColumn := True)
        ' Elimina todas as colunas em que a primeira linha está marcada com um "X"
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Elimina todas as colunas em que a soma dos valores da coluna é ímpar
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")

##### Em Python

        newrange = myDoc.CompactLeft("Sheet1.G1:L10")
        newrange = myDoc.CompactLeft("Sheet1.G1:L10", wholecolumn = True)
        newrange = myDoc.CompactLeft("Sheet1.G1:L10", filterformula = '=(G1="X")')
        newrange = myDoc.CompactLeft("Sheet1.G1:L10", filterformula = '=(MOD(SUM(G1:G10);2)=1)')

## CompactUp

Elimina as linhas de um intervalo especificado que correspondam a um filtro expresso como uma fórmula do Calc. O filtro é aplicado a cada linha para determinar se esta será eliminada ou não.

As linhas a eliminar podem ser limitadas à largura do intervalo especificado ou abranger toda a largura da folha, eliminando assim linhas inteiras.

Este método devolve uma cadeia de caracteres com o endereço do intervalo compactado. Se todas as linhas forem eliminadas, é devolvida uma cadeia de caracteres vazia.

Se for selecionado um intervalo de células, a chamada deste método não afetará a seleção.

### Sintaxe:

svc.CompactUp(range: str, wholerow: bool = False, opt filterformula: str): str

### Parâmetros:

range: O intervalo a partir do qual as linhas serão eliminadas, expresso como uma cadeia de caracteres.

wholerow: Se esta opção for definida como True, toda a linha será eliminada da folha. O valor predefinido é False, o que significa que a linha eliminada ficará limitada à largura do range especificado.

filterformula: O filtro a aplicar a cada linha para determinar se esta será ou não eliminada. O filtro é expresso como uma fórmula do Calc que deve ser aplicada à primeira linha. Quando a fórmula devolver True para uma linha, essa linha será eliminada. O filtro predefinido elimina todas as linhas vazias.

Por exemplo, suponha que o intervalo A1:J200 esteja selecionado (largura = 10), pelo que a fórmula predefinida é =(COUNTBLANK(A1:J1)=10). Isto significa que, se todas as 10 células da primeira linha (Linha 1) estiverem vazias, essa linha será eliminada. Note que a fórmula é expressa apenas em relação à primeira linha. Internamente, o método CompactUp generalizará esta fórmula para todas as linhas restantes.

As funções do Calc utilizadas na fórmula especificada no argumento filterformula devem ser indicadas utilizando os seus nomes em inglês. Consulte a página da Wiki Lista de funções do Calc para obter uma lista completa das funções do Calc em inglês.

### Exemplo:

##### Em Basic

        ' Eliminar todas as linhas vazias no intervalo G1:L10 da Folha1
        newrange = oDoc.CompactUp("Sheet1.G1:L10")
        ' O exemplo abaixo é semelhante, mas toda a linha é eliminada da folha
        newrange = oDoc.CompactUp("Sheet1.G1:L10", WholeRow := True)
        ' Elimina todas as linhas em que a primeira coluna está marcada com um "X"
        newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Deletes all rows where the sum of values in the row is odd
        newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")

##### Em Python

        newrange = myDoc.CompactUp("Sheet1.G1:L10")
        newrange = myDoc.CompactUp("Sheet1.G1:L10", wholerow = True)
        newrange = myDoc.CompactUp("Sheet1.G1:L10", filterformula = '=(G1="X")')
        newrange = myDoc.CompactUp("Sheet1.G1:L10", filterformula = '=(MOD(SUM(G1:L1);2)=1)')

## CopySheet

Copia uma folha especificada antes de uma folha existente ou no final da lista de folhas. A folha a copiar pode estar contida em qualquer documento do Calc aberto. Retorna True se a operação for bem-sucedida.

### Sintaxe:

svc.CopySheet(sheetname: any, newname: str, [beforesheet: any]): bool

### Parâmetros:

nome_da_folha: O nome da folha a copiar, na forma de uma cadeia de caracteres, ou a sua referência, na forma de um objeto.

newname: O nome da folha a inserir. O nome não pode estar em uso no documento.

beforesheet: O nome (cadeia de caracteres) ou o índice (numérico, a partir de 1) da folha antes da qual se pretende inserir a folha copiada. Este argumento é opcional e, por predefinição, a folha copiada é adicionada na última posição.

### Exemplo:

##### Em Basic

O exemplo seguinte cria uma cópia da folha «SheetX» e coloca-a como última folha no documento atual. O nome da folha copiada é «SheetY».

        Dim oDoc as Object
        'Obtém o objeto Document da janela ativa
        Set oDoc = CreateScriptService("Calc")
        oDoc.CopySheet("SheetX", "SheetY")

O exemplo abaixo copia a «SheetX» do «FileA.ods» e cola-a na última posição do «FileB.ods» com o nome «SheetY»:

          Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
          Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
          oDocB.CopySheet(oDocA.Sheet("SheetX"), "SheetY")

##### Em Python

        myDoc.CopySheet("SheetX", "SheetY")

        docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopySheet(docA.Sheet("SheetX"), "SheetY")

Para copiar folhas entre documentos abertos, utilize CopySheet. Para copiar folhas de documentos que estejam fechados, utilize CopySheetFromFile.

## CopySheetFromFile

Copia uma folha especificada de um documento Calc fechado e cola-a antes de uma folha existente ou no final da lista de folhas do ficheiro a que se refere um objeto Document.

Se o ficheiro não existir, é gerado um erro. Se o ficheiro não for um ficheiro Calc válido, é inserida uma folha em branco. Se a folha de origem não existir no ficheiro de entrada, é inserida uma mensagem de erro na parte superior da folha recém-colada.

### Sintaxe:

svc.CopySheetFromFile(filename: str, sheetname: str, newname: str, [beforesheet: any]): bool

### Parâmetros:

nome do ficheiro: Identifica o ficheiro a abrir. Deve seguir a notação SF_FileSystem.FileNaming. O ficheiro não pode estar protegido por palavra-passe.

sheetname: O nome da folha a copiar, na forma de uma cadeia de caracteres.

newname: O nome da folha copiada a inserir no documento. O nome não pode já estar em uso no documento.

beforesheet: O nome (cadeia de caracteres) ou o índice (numérico, a partir de 1) da folha antes da qual se pretende inserir a folha copiada. Este argumento é opcional e, por predefinição, a folha copiada é adicionada na última posição.

### Exemplo:

O exemplo seguinte copia a «SheetX» do ficheiro «myFile.ods» e cola-a no documento referido por «oDoc» como «SheetY» na primeira posição.

##### Em Basic

        oDoc.CopySheetFromFile("C:\Documents\myFile.ods", "SheetX", "SheetY", 1)

##### Em Python

        myDoc.CopySheetFromFile(r"C:\Documents\myFile.ods", "SheetX", "SheetY", 1)

## CopyToCell

Copia um intervalo de origem especificado (valores, fórmulas e formatos) para um intervalo ou célula de destino. Este método reproduz o comportamento de uma operação de copiar/colar de um intervalo para uma única célula.

Devolve uma cadeia de caracteres que representa o intervalo de células modificado. A dimensão da área modificada é inteiramente determinada pela dimensão da área de origem.

O intervalo de origem pode pertencer a outro documento aberto.

### Sintaxe:

svc.CopyToCell(sourcerange: any, destinationcell: str): str

### Parâmetros:

sourcerange: O intervalo de origem como uma cadeia de caracteres, quando pertence ao mesmo documento, ou como uma referência, quando pertence a outro documento do Calc aberto.

destinationcell: A célula de destino onde o intervalo de células copiado será colado, expressa como uma cadeia de caracteres. Se for indicado um intervalo, apenas a célula do canto superior esquerdo é considerada.

### Exemplo:

##### Em Basic

Segue-se um exemplo em que a origem e o destino se encontram no mesmo ficheiro:

          oDoc.CopyToCell("SheetX.A1:F10", "SheetY.C5")

O exemplo abaixo mostra como copiar um intervalo de células de outro documento do Calc que esteja aberto:

        Dim ui as Variant : ui = CreateScriptService("UI")
        Dim oDocSource As Object, oDocDestination As Object
        «Abrir o documento de origem em segundo plano (oculto)»
        Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
        Set oDocDestination = CreateScriptService("Calc")
        oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        «Não se esqueça de fechar o documento de origem, pois foi aberto como oculto»
        oDocSource.CloseDocument()

##### Em Python

        docSource = ui.OpenDocument(r"C:\Documents\SourceFile.ods", hidden = True, readonly = True)
        docDestination = CreateScriptService("Calc")
        docDestination.CopyToCell(docSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        docSource.CloseDocument()

Para simular uma operação de copiar/colar de um intervalo para uma única célula, utilize CopyToCell. Para simular uma operação de copiar/colar de um intervalo para um intervalo maior (com as mesmas células a serem replicadas várias vezes), utilize CopyToRange.

## CopyToRange

Copia para baixo e/ou para a direita um intervalo de origem especificado (valores, fórmulas e formatos) para um intervalo de destino. Este método imita o comportamento de uma operação de copiar/colar de um intervalo de origem para um intervalo de destino maior.

- Se a altura (ou largura) da área de destino for superior a 1 linha (ou coluna), a altura (ou largura) da área de origem deve ser igual ou inferior à altura (ou largura) da área de destino. Caso contrário, nada acontece.

- Se a altura (ou largura) do destino for igual a 1, o destino é expandido para baixo (ou para a direita) até atingir a altura (ou largura) do intervalo de origem.

O método devolve uma cadeia de caracteres que representa o intervalo de células modificado.

O intervalo de origem pode pertencer a outro documento aberto.

### Sintaxe:

svc.CopyToRange(sourcerange: any, destinationrange: str): str

### Parâmetros:

sourcerange: O intervalo de origem como uma cadeia de caracteres, quando pertence ao mesmo documento, ou como uma referência, quando pertence a outro documento do Calc aberto.

destinationrange: O destino do intervalo de células copiado, na forma de uma cadeia de caracteres.

### Exemplo:

##### Em Basic

Copiar dentro do mesmo documento:

        oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
        ' Devolve uma cadeia de caracteres com o intervalo: "$SheetY.$C$5:$J$14"

Copiar de um ficheiro para outro:

        Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
        Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
        oDocB.CopyToRange(oDocA.Range("SheetX.A1:F10"), "SheetY.C5:J5")

##### Em Python

        doc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")

        docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopyToRange(docA.Range("SheetX.A1:F10"), "SheetY.C5:J5")

## CreateChart

Cria um novo objeto gráfico que apresenta os dados do intervalo especificado. O objeto gráfico devolvido pode ser posteriormente manipulado utilizando o serviço Chart.

### Sintaxe:

svc.CreateChart(chartname: str, sheetname: str, range: str, columnheader: bool = False, rowheader: bool = False): obj

### Parâmetros:

nome do gráfico: O nome definido pelo utilizador para o gráfico a criar. O nome deve ser único na mesma folha.

sheetname: O nome da folha onde o gráfico será inserido.

intervalo: O intervalo a utilizar como fonte de dados para o gráfico. O intervalo pode referir-se a qualquer folha do documento do Calc.

columnheader: Quando True, a linha superior do intervalo é utilizada como rótulos para o eixo de categorias ou para a legenda (Padrão = False).

rowheader: Quando True, a coluna mais à esquerda do intervalo é utilizada como rótulos para o eixo de categorias ou para a legenda. (Predefinição = False).

### Exemplo:

Os exemplos abaixo, em Basic e Python, criam um gráfico utilizando os dados contidos no intervalo «A1:B5» da «Folha1» e colocam o gráfico na «Folha2».

##### Em Basic

        Set oChart = oDoc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", RowHeader := True)
        oChart.ChartType = "Donut"

##### Em Python

        chart = doc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", rowheader=True)
        chart.ChartType = "Donut"

Consulte a página de ajuda sobre o serviço de gráficos do ScriptForge para saber mais sobre como manipular objetos de gráficos. É possível alterar propriedades como o tipo de gráfico, os títulos do gráfico e dos eixos e a posição do gráfico.

## CreatePivotTable

Cria uma nova tabela dinâmica com as propriedades definidas pelos argumentos passados ao método.

É necessário atribuir um nome à tabela dinâmica. Se já existir uma tabela dinâmica com o mesmo nome na folha de cálculo de destino, esta será substituída sem aviso prévio.

Este método devolve uma cadeia de caracteres que contém o intervalo onde a nova tabela dinâmica foi colocada.

### Sintaxe:

svc.CreatePivotTable(pivottablename: str, sourcerange: str, targetcell: str, datafields: str[0..*], rowfields: str[0..*], columnfields: str[0..*], filterbutton: bool = true, rowtotals: bool = true, columntotals: bool = true): str

### Parâmetros:

pivottablename: O nome definido pelo utilizador da nova tabela dinâmica.

sourcerange: O intervalo que contém os dados brutos, na forma de uma cadeia de caracteres. Presume-se que a primeira linha contenha os nomes dos campos utilizados pela tabela dinâmica.

targetcell: A célula do canto superior esquerdo onde a nova tabela dinâmica será colocada. Se for especificado um intervalo, apenas a célula do canto superior esquerdo desse intervalo será considerada.

datafields: Pode ser uma única cadeia de caracteres ou uma matriz contendo cadeias de caracteres que definem os nomes dos campos e as funções a aplicar. Quando se especifica uma matriz, esta deve seguir a sintaxe Array("NomeDoCampo[;Função]", ...).

As funções permitidas são: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP e Median. Os nomes das funções devem ser fornecidos em inglês. Quando todos os valores são numéricos, Sum é a função predefinida; caso contrário, a função predefinida é Count.

rowfields Uma única cadeia de caracteres ou uma matriz com os nomes dos campos que serão utilizados como linhas da tabela dinâmica.

columnfields: Uma única cadeia de caracteres ou uma matriz com os nomes dos campos que serão utilizados como colunas da tabela dinâmica.

filterbutton: Determina se será apresentado um botão de filtro acima da tabela dinâmica (Predefinição = True).

rowtotals: Especifica se será adicionada à tabela dinâmica uma coluna separada para os totais das linhas (Predefinição = True).

columntotals: Especifica se será adicionada uma linha separada para os totais das colunas à tabela dinâmica (Predefinição = True)

### Exemplo:

##### Em Basic

        Dim vData As Variant, oDoc As Object, ui As Object, sTable As String, sPivot As String
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.CreateDocument("Calc")
        vData = Array(Array("Item", "State", "Team", "2002", "2003", "2004"), _
            Array("Books", "Michigan", "Jean", 14788, 30222, 23490), _
            Array("Candy", "Michigan", "Jean", 26388, 15641, 32849), _
            Array("Pens", "Michigan", "Jean", 16569, 32675, 25396), _
            Array("Books", "Michigan", "Volker", 21961, 21242, 29009), _
            Array("Candy", "Michigan", "Volker", 26142, 22407, 32841))
        sTable = oDoc.SetArray("A1", vData)
        sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
            Array("2002", "2003;count", "2004;average"), _ ' Three data fields
            "Item", _ ' Um campo de uma única linha
            Array("State", "Team"), False) ' Campos com duas colunas

##### Em Python

        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Calc")
        vData = [["Item", "State", "Team", "2002", "2003", "2004"],
                 ["Books", "Michigan", "Jean", 14788, 30222, 23490],
                 ["Candy", "Michigan", "Jean", 26388, 15641, 32849],
                 ["Pens", "Michigan", "Jean", 16569, 32675, 25396)],
                 ["Books", "Michigan", "Volker", 21961, 21242, 29009],
                 ["Candy", "Michigan", "Volker", 26142, 22407, 32841]]
        sTable = doc.SetArray("A1", vData)
        sPivot = doc.CreatePivotTable("PT1", sTable, "H1",
                                      ["2002", "2003;count", "2004;average"],
                                      "Item",
                                      ["State", "Team"], False)

Para saber mais sobre as tabelas dinâmicas no LibreOffice Calc, consulte a página de ajuda Pivot Table.

## DAvg, DCount, DMax, DMin and DSum

Aplique as funções Média, Contagem, Máx., Mín. e Soma, respetivamente, a todas as células que contenham valores numéricos num determinado intervalo, excluindo os valores das linhas e colunas filtradas e ocultas, tal como acontece com as funções da barra de estado.

### Sintaxe:

svc.DAvg(range: str): float

svc.DCount(range: str): float

svc.DMax(range: str): float

svc.DMin(range: str): float

svc.DSum(range: str): float

### Parâmetros:

range: O intervalo ao qual a função será aplicada, na forma de uma cadeia de caracteres.

### Exemplo:

O exemplo abaixo aplica a função Sum ao intervalo "A1:A1000" da folha atualmente selecionada:

##### Em Basic

          result = oDoc.DSum("~.A1:A1000")

##### Em Python

        result = myDoc.DSum("~.A1:A1000")

As células do intervalo indicado que contenham texto serão ignoradas por todas estas funções. Por exemplo, o método DCount não contará as células com texto, mas apenas as células numéricas.

## DecorateFont

Especifique propriedades simples e fáceis da fonte a utilizar num intervalo de células.

As células afetadas podem ser identificadas através de uma fórmula de filtro e do seu âmbito de aplicação.

Para aplicar decorações de fonte mais complexas, utilize as numerosas propriedades habituais do UNO disponíveis nas interfaces XCell ou XCellRange.

### Sintaxe:

svc.DecorateFont(targetrange: str, opt fontname: str, opt fontsize: int, opt decoration: str, opt filterformula: str, opt filterscope: str)

### Parâmetros:

targetrange: A célula ou o intervalo, expresso como uma cadeia de caracteres, no qual as fontes das células devem ser reformatadas.

fontname: O nome da fonte a utilizar. O nome não é verificado. Padrão = sem alteração.

fontsize: O tamanho da fonte em pixels. Padrão = sem alteração.

decoration: Uma sequência de caracteres que combina um ou mais dos seguintes caracteres em maiúscula (os restantes são ignorados). Padrão = sem alteração:

- N, S, I, R: Negrito, Sublinhado, Itálico, Riscado.

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

            ' Altere o tamanho da fonte e aplique as propriedades de negrito e sublinhado às células numéricas.
            doc.DecorateFont("SheetX.A1:J30", fontsize := 15, decoration := "Bold,Underline", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

            # Altere o tamanho da fonte e aplique as propriedades de negrito e sublinhado às células numéricas.
            doc.DecorateFont('SheetX.A1:J30', fontsize = 15, decoration = 'Bold,Underline', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## DefineName

Defina um novo nome na folha de cálculo, a nível global ou da folha. Se o nome já existir, será substituído sem aviso prévio. Após a criação, o novo nome pode ser utilizado em fórmulas. Retorna True em caso de sucesso.

Utilize a propriedade DefinedNames para examinar os intervalos nomeados existentes.

### Sintaxe:

svc.DefineName(definedname: str, value: any, opt sheetname: str): boolean

### Parâmetros:

definedname: O nome a ser criado ou alterado sem aviso prévio. Note que podem existir homónimos, mas não na mesma folha e não a nível global.

value: O novo nome é:

- uma referência de intervalo na forma de uma cadeia de caracteres, frequentemente uma única célula

- um valor escalar, seja um número ou uma cadeia de caracteres

- uma fórmula que começa com o sinal «=»

Quando Value é um intervalo, a célula do canto superior esquerdo é definida como célula de referência.

sheetname: O âmbito do nome definido é o da folha especificada. É aceite o atalho "~".

### Exemplo:

##### Em Basic

            doc.DefineName("NewName", Sheet := "Sheet3", Value := "H2")

##### Em Python

            doc.DefineName('NewName', sheet = 'Sheet3', value = 'H2')

## ExportRangeToFile

Exporta o intervalo especificado como uma imagem ou um ficheiro PDF.

Este método devolve True se o ficheiro de destino tiver sido guardado com sucesso.

As linhas ou colunas ocultas no intervalo especificado não são exportadas para o ficheiro de destino.

### Sintaxe:

svc.ExportRangeToFile(range: str, filename: str, imagetype: str = "pdf", overwrite: bool = False): bool

### Parâmetros:

range: O nome de uma folha ou um intervalo de células a exportar, na forma de uma cadeia de caracteres.

filename: O nome do ficheiro a guardar. Deve seguir a notação SF_FileSystem.FileNaming.

imagetype: Identifica o tipo de ficheiro de destino. Os valores possíveis são «jpeg», «pdf» (padrão) e «png».

overwrite: Quando definido como True, o ficheiro de destino pode ser substituído (Predefinição = False).

### Exemplo:

##### Em Basic

        ' Exporta a folha inteira como um ficheiro PDF
        oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
        Exporta o intervalo como um ficheiro PNG e substitui o ficheiro de destino, caso este já exista
        oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)

##### Em Python

        doc.ExportRangeToFile("SheetX", r"C:\Temp\image.pdf")
        doc.ExportRangeToFile("SheetX.A1:D10", r"C:\Temp\image.png", "png", overwrite = True)

## FormatRange

Aplicar um determinado formato numérico a uma célula ou a um intervalo de células.

As células afetadas podem ser identificadas através de uma fórmula de filtro e do seu âmbito de aplicação.

### Sintaxe:

svc.FormatRange(targetrange: str, numberformat: str, opt locale: str, opt filterformula: str, opt filterscope: str)

### Parâmetros:

targetrange: A célula ou o intervalo, expresso como uma cadeia de caracteres, que deve receber o formato.

numberformat: O formato a aplicar, na forma de uma cadeia de caracteres.

locale: Uma combinação «língua-país» para indicar a configuração regional utilizada. A configuração regional predefinida é o resultado da propriedade platform.FormatLocale

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

            ' Aplique a formatação apenas às células que contenham um valor numérico.
            doc.FormatRange("SheetX.A1:J30", "0,00E+00", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

            # Formatar apenas as células que contêm um valor numérico.
            doc.FormatRange('SheetX.A1:J30', '0,00E+00', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## Forms

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

- Uma matriz com índice zero (ou uma tupla em Python) com os nomes de todos os formulários contidos numa determinada folha (caso o argumento form esteja ausente)

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

### Sintaxe:

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

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

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

### Parâmetros:

sheetname: O nome da folha, na forma de uma cadeia de caracteres, a partir da qual o formulário será recuperado.

form: O nome ou índice correspondente a um formulário guardado na folha especificada. Se este argumento não for fornecido, o método devolverá uma lista com os nomes de todos os formulários disponíveis na folha.

### Exemplo:

Nos exemplos seguintes, a primeira linha obtém os nomes de todos os formulários guardados na «Sheet1» e a segunda linha recupera o objeto Form do formulário denominado «Form_A», que se encontra guardado na «Sheet1».

##### Em Basic

        Set FormNames = oDoc.Forms("Sheet1")
        Set FormA = oDoc.Forms("Sheet1", "Form_A")

##### Em Python

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

## GetColumnName

Converte um número de coluna compreendido entre 1 e 1024 na letra correspondente (coluna «A», «B», ..., «AMJ»). Se o número de coluna fornecido estiver fora do intervalo permitido, é devolvida uma cadeia de caracteres de comprimento zero.

### Sintaxe:

svc.GetColumnName(columnnumber: int): str

### Parâmetros:

número da coluna: O número da coluna, expresso como um valor inteiro no intervalo de 1 a 16384.

### Exemplo:

##### Em Basic

Exibe uma caixa de mensagem com o nome da terceira coluna, que, por predefinição, é «C».

        MsgBox oDoc.GetColumnName(3)

##### Em Python

        bas = CreateScriptService("Basic")
        bas.MsgBox(myDoc.GetColumnName(3))

O número máximo de colunas permitido numa folha do Calc é 16 384.

## GetFormula

Recupere a(s) fórmula(s) armazenada(s) no intervalo de células indicado como uma única cadeia de caracteres, uma matriz unidimensional ou uma matriz bidimensional de cadeias de caracteres.

Os nomes das funções do Calc utilizadas nas fórmulas devolvidas são apresentados em inglês. Visite a página Wiki Lista de funções do Calc para obter uma lista completa das funções do Calc em inglês.

### Sintaxe:

svc.GetFormula(range: str): any

### Parâmetros:

range: O intervalo de onde obter as fórmulas, na forma de uma cadeia de caracteres.

### Exemplo:

##### Em Basic

O exemplo seguinte devolve uma matriz de 3 por 2 com as fórmulas do intervalo «A1:B3» (3 linhas por 2 colunas):

        arrFormula = oDoc.GetFormula("~.A1:B3")

##### Em Python

        arrFormula = myDoc.GetFormula("~.A1:B3")

## GetValue

Recupere o(s) valor(es) armazenado(s) no intervalo de células indicado como um único valor, uma matriz unidimensional ou uma matriz bidimensional. Todos os valores são do tipo double ou cadeias de caracteres.

### Sintaxe:

svc.GetValue(range: str): any

### Parâmetros:

range: O intervalo de onde se devem obter os valores, na forma de uma cadeia de caracteres.

### Exemplo:

##### Em Basic

          arrValues = oDoc.GetValue("~.B1:C100")

##### Em Python

        arrValues = myDoc.GetValue("~.B1:C100")

Se uma célula contiver uma data, será devolvido o número correspondente a essa data. Para converter valores numéricos em datas em scripts Basic, utilize a função incorporada Basic CDate. Em scripts Python, utilize a função CDate do serviço Basic.

## ImportFromCSVFile

Importa o conteúdo de um ficheiro de texto no formato CSV e insere-o numa célula de destino especificada.

A área de destino é limpa de todo o conteúdo e formatos antes da inserção do conteúdo do ficheiro CSV. O tamanho da área modificada é inteiramente determinado pelo conteúdo do ficheiro de entrada.

O método devolve uma cadeia de caracteres que representa o intervalo de células modificado.

### Sintaxe:

svc.ImportFromCSVFile(filename: str, destinationcell: str, [filteroptions: str]): str

### Parâmetros:

filename: Identifica o ficheiro a abrir. Deve seguir a notação SF_FileSystem.FileNaming.

destinationcell: A célula de destino onde os dados importados serão inseridos, expressa como uma cadeia de caracteres. Se for indicado um intervalo, apenas a célula do canto superior esquerdo será considerada.

filteroptions: Os argumentos para o filtro de entrada CSV. O filtro predefinido parte dos seguintes pressupostos:

- A codificação do ficheiro de entrada é UTF-8.

- O separador de campos é uma vírgula, um ponto e vírgula ou um caractere de tabulação.

- O delimitador da cadeia de caracteres é a aspa dupla (").

- Todas as linhas estão incluídas.

- As cadeias de caracteres entre aspas são formatadas como texto.

- São detetados números especiais.

- Presume-se que todas as colunas sejam texto, exceto se forem reconhecidas como números válidos.

- O idioma é o inglês (EUA), o que significa que o separador decimal é «.» e o separador de milhares é «,».

### Exemplo:

##### Em Basic

        oDoc.ImportFromCSVFile("C:\Temp\myCSVFile.csv", "SheetY.C5")

##### Em Python

        myDoc.ImportFromCSVFile(r"C:\Temp\myCSVFile.csv", "SheetY.C5")

Para saber mais sobre as opções de filtragem CSV, consulte a página de ajuda sobre as opções de filtragem CSV.

## ImportFromDatabase

Importa o conteúdo de uma tabela de base de dados, de uma consulta ou de um conjunto de resultados — ou seja, o resultado de um comando SELECT SQL —, inserindo-o numa célula de destino.

A área de destino é esvaziada de todo o conteúdo e formatos antes da inserção do conteúdo importado. O tamanho da área modificada é inteiramente determinado pelo conteúdo da tabela ou da consulta.

O método devolve True quando a importação é bem-sucedida.

### Sintaxe:

svc.ImportFromDatabase(filename: str = "", registrationname: str = "", destinationcell: str = "", sqlcommand: str = "", directsql: bool): bool

### Parâmetros:

filename: Identifica o ficheiro a abrir. Deve seguir a notação SF_FileSystem.FileNaming.

registrationname: O nome a utilizar para localizar a base de dados no registo de bases de dados. Este argumento é ignorado se for fornecido um filename.

destinationcell: O destino dos dados importados, na forma de uma cadeia de caracteres. Se for indicado um intervalo, apenas a célula do canto superior esquerdo é considerada.

sqlcommand: O nome de uma tabela ou de uma consulta (sem aspas nem parênteses retos) ou uma instrução SQL SELECT na qual os nomes das tabelas e dos campos podem ser colocados entre parênteses retos ou aspas para melhorar a sua legibilidade.

directsql: Quando True, o comando SQL é enviado ao motor da base de dados sem análise prévia. O valor predefinido é False. Este argumento é ignorado no caso das tabelas. No caso das consultas, a opção aplicada é aquela definida no momento em que a consulta foi criada.

### Exemplo:

##### Em Basic

        oDoc.ImportFromDatabase("C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")

##### Em Python

        myDoc.ImportFromDatabase(r"C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")

### ImportStylesFromFile

This method loads all the styles belonging to one or more style families from a closed file into the actual document. The actual document must be a Calc or a Writer document.

Are always imported together:

- ParagraphStyles and CharacterStyles

- NumberingStyles and ListStyles

Returns True if styles were successfully imported.

### Sintaxe:

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

### Parâmetros:

filename: The file from which to load the styles in the FileSystem notation. The file is presumed to be of the same document type as the actual document.

families: One of the style families present in the actual document, as a case-sensitive string or an array of such strings. Leave this argument blank to import all families.

overwrite: When True, the actual styles may be overwritten. Default is False.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## InsertSheet

Inserir uma nova folha vazia antes de uma folha existente ou no final da lista de folhas.

### Sintaxe:

svc.InsertSheet(sheetname: str, [beforesheet: any]): bool

### Parâmetros:

sheetname: O nome da nova folha.

beforesheet: O nome (cadeia de caracteres) ou o índice (numérico, a partir de 1) da folha antes da qual se pretende inserir a nova folha. Este argumento é opcional e, por predefinição, a folha é inserida na última posição.

### Exemplo:

O exemplo seguinte insere uma nova folha vazia chamada «SheetX» e coloca-a antes da «SheetY»:

##### Em Basic

        oDoc.InsertSheet("SheetX", "SheetY")

##### Em Python

        myDoc.InsertSheet("SheetX", "SheetY")

## Intersect

Devolve a cadeia de caracteres que representa a intersecção entre os dois intervalos de entrada, ou uma cadeia de caracteres de comprimento zero quando a intersecção estiver vazia.

### Sintaxe:

svc.Intersect(range1:str, range2: str): str

### Parâmetros:

range1: A cadeia de caracteres do endereço do intervalo 1.

range2: A cadeia de caracteres do endereço do intervalo 2.

### Exemplo:

O exemplo seguinte cruza dois intervalos e devolve o intervalo comum entre ambos:

##### Em Basic

        Dim commonrange As String
        commonrange = oDoc.Intersect("A1:D8", "C3:F4")
        Imprimir o intervalo comum ' exibe "$Sheet1.$C$3:$D$4"

##### Em Python

        common_range = myDoc.Intersect("A1:D8", "C3:F4")
        print(common_range)  # apresenta «$Sheet1.$C$3:$D$4» no shell do Python

## MoveRange

Mova um intervalo de células de origem especificado para um intervalo de células de destino. O método devolve uma cadeia de caracteres que representa o intervalo de células modificado. A dimensão da área modificada é inteiramente determinada pelo tamanho da área de origem.

### Sintaxe:

svc.MoveRange(source: str, destination: str): str

### Parâmetros:

source: O intervalo de células de origem, na forma de uma cadeia de caracteres.

destination: A célula de destino, expressa como uma cadeia de caracteres. Se for indicado um intervalo, a célula do canto superior esquerdo desse intervalo é considerada como o destino.

### Exemplo:

##### Em Basic

        oDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")

##### Em Python

        myDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")

## MoveSheet

Mova uma folha existente e coloque-a antes de uma folha especificada ou no final da lista de folhas.

### Sintaxe:

svc.MoveSheet(sheetname: str, [beforesheet: any]): bool

### Parâmetros:

sheetname: O nome da folha a mover. A folha tem de existir; caso contrário, é gerada uma exceção.

beforesheet: O nome (cadeia de caracteres) ou índice (numérico, a partir de 1) da folha antes da qual a folha original será colocada. Este argumento é opcional e o comportamento predefinido é mover a folha para a última posição.

### Exemplo:

O exemplo abaixo move a folha existente «SheetX» e coloca-a antes da «SheetY»:

##### Em Basic

        oDoc.MoveSheet("SheetX", "SheetY")

##### Em Python

        myDoc.MoveSheet("SheetX", "SheetY")

## Offset

Devolve um novo intervalo (na forma de uma cadeia de caracteres) deslocado um determinado número de linhas e colunas a partir de um intervalo especificado.

Este método tem o mesmo comportamento que a função homónima Offset do Calc.

### Sintaxe:

svc.Offset(reference: str, rows: int = 0, columns: int = 0, [height: int], [width: int]): str

### Parâmetros:

reference: O intervalo, na forma de uma cadeia de caracteres, que o método utilizará como referência para realizar a operação de deslocamento.

rows: O número de linhas em que o intervalo inicial é deslocado para cima (valor negativo) ou para baixo (valor positivo). Utilize 0 (valor predefinido) para permanecer na mesma linha.

columns: O número de colunas em que o intervalo inicial é deslocado para a esquerda (valor negativo) ou para a direita (valor positivo). Utilize 0 (valor predefinido) para permanecer na mesma coluna.

height: A altura vertical de uma área que começa na nova posição do intervalo. Omita este argumento quando não for necessário redimensionar verticalmente.

width: A largura horizontal de uma área que começa na nova posição do intervalo. Omita este argumento quando não for necessário redimensionar horizontalmente.

Os argumentos rows e columns não devem resultar numa linha ou coluna inicial igual a zero ou negativa.

Os argumentos height e width não devem resultar num número zero ou negativo de linhas ou colunas.

### Exemplo:

##### Em Basic

        oDoc.Offset("A1", 2, 2)
        'SheetX.$C$3 (A1 deslocada duas linhas e duas colunas para baixo)
        oDoc.Offset("A1", 2, 2, 5, 6)
        'SheetX.$C$3:$H$7 (A1 deslocado duas linhas e colunas, com uma largura de 5 linhas e 6 colunas)

##### Em Python

        myDoc.Offset("A1", 2, 2)
        myDoc.Offset("A1", 2, 2, 5, 6)

## OpenRangeSelector

Abre uma caixa de diálogo não modal que pode ser utilizada para selecionar um intervalo no documento e devolve uma cadeia de caracteres contendo o intervalo selecionado.

Este método abre a mesma caixa de diálogo utilizada pelo LibreOffice quando se clica no botão «Reduzir». Por exemplo, a caixa de diálogo Ferramentas - Busca de objetivo possui um botão «Reduzir» à direita do campo Célula da fórmula.

Este método não altera a seleção atual.

### Sintaxe:

svc.OpenRangeSelector(opt title: str, opt selection: str, singlecell: bool = False, closeafterselect: bool = True): str

### Parâmetros:

title: O título da caixa de diálogo, na forma de uma cadeia de caracteres.

selection: Um intervalo opcional que é selecionado inicialmente quando a caixa de diálogo é exibida.

singlecell: Quando True (padrão), só é permitida a seleção de uma única célula. Quando False, é permitida a seleção de um intervalo.

closeafterselect: Quando True (padrão), a caixa de diálogo é fechada imediatamente após a seleção ser efetuada. Quando False, o utilizador pode alterar a seleção quantas vezes for necessário e, em seguida, fechar manualmente a caixa de diálogo.

### Exemplo:

##### Em Basic

        Dim sRange as String
        sRange = oDoc.OpenRangeSelector(Title := "Select a range")

##### Em Python

        sRange = myDoc.OpenRangeSelector(title = "Select a range")

## Printf

Devolve a cadeia de caracteres de entrada após substituir os seus caracteres-token pelos respetivos valores num determinado intervalo.

Este método não altera a seleção atual.

Este método pode ser utilizado para extrair rapidamente partes específicas do nome de um intervalo, tais como o nome da folha ou a coluna e linha da primeira célula, e utilizá-las para compor um novo endereço de intervalo.

### Sintaxe:

svc.Printf(inputstr: str, range: str, tokencharacter: str = "%"): str

### Parâmetros:

inputstr: A cadeia de caracteres que contém os tokens que serão substituídos pelos valores correspondentes em range.

range: Um NomeDoIntervalo do qual serão extraídos os valores. Se contiver o nome de uma folha, essa folha deve existir.

tokencharacter: Caractere utilizado para identificar tokens. Por predefinição, o "%" é o caractere-token. São aceites os seguintes tokens:

- %S - O nome da folha que contém o intervalo, incluindo aspas simples quando necessário.

- %R1 - O número da linha da célula superior esquerda do intervalo.

- %C1 - A letra da coluna da célula superior esquerda do intervalo.

- %R2 - O número da linha da célula inferior direita do intervalo.

- %C2 - A letra da coluna da célula inferior direita do intervalo.

### Exemplo:

##### Em Basic

O exemplo abaixo extrai cada elemento do RangeName definido em sRange e utiliza-os para compor uma mensagem.

        Dim sRange as String, sInputStr as String
        sRange = "Sheet1.A1:E10"
        sInputStr = "Sheet name: %S" & Chr(10) & _
                    "First row: %R1" & Chr(10) & _
                    "First column %C1" & Chr(10) & _
                    "Last row %R2" & Chr(10) & _
                    "Last column %C2"
        MsgBox oDoc.Printf(sInputStr, sRange)

O método Printf pode ser combinado com o SetFormula para criar fórmulas em várias células. Por exemplo, considere uma tabela com valores numéricos no intervalo «A1:E10», a partir da qual se pretende criar fórmulas para somar os valores de cada linha e colocar os resultados no intervalo «F1:F10»:

        Dim sFormula as String, sRange as String
        sRange = "A1:E10"
        ' Repare na utilização do caractere "$"
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))

##### Em Python

        sRange = "Sheet1.A1:E10"
        sInputStr = "Sheet name: %S\n" \
                    "First row: %R1\n" \
                    "First column %C1\n" \
                    "Last row %R2\n" \
                    "Last column %C2"
        bas = CreateScriptService("Basic")
        bas.MsgBox(myDoc.Printf(sInputStr, sRange))

        sRange = "A1:E10
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        myDoc.SetFormula("F1:F10", myDoc.Printf(sFormula, sRange))

## PrintOut

Este método envia o conteúdo da folha indicada para a impressora predefinida ou para a impressora definida pelo método SetPrinter do serviço Document.

Retorna True se a folha tiver sido impressa com sucesso.

### Sintaxe:

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

### Parâmetros:

sheetname: A folha a imprimir; por predefinição, é a folha ativa.

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("SheetX", "1-4;10;15-18", Copies := 2) Then
            ' ...
        End If

##### Em Python

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

## RemoveDuplicates

Remove linhas duplicadas de um intervalo especificado. A comparação para determinar se uma determinada linha é uma duplicata é feita com base num subconjunto de colunas do intervalo.

Este método devolve uma cadeia de caracteres que contém o intervalo resultante.

A remoção de linhas duplicadas é feita a partir da primeira linha do intervalo, avançando para baixo; isto significa que, se houver duas ou mais linhas duplicadas, apenas a primeira é mantida.

### Sintaxe:

svc.RemoveDuplicates(range: str, opt columns: int[0..*], header: bool = False, casesensitive: bool = False, mode: str = "COMPACT"): str

### Parâmetros:

range: O intervalo do qual serão removidas as duplicatas, na forma de uma cadeia de caracteres.

columns: Uma matriz que contém números de colunas, indicando quais as colunas a ter em conta para determinar se uma linha é uma duplicado ou não. Se este argumento for deixado em branco, apenas a primeira coluna será utilizada. Os elementos desta matriz devem estar compreendidos entre 1 e a largura do intervalo.

header: Especifica se a primeira linha é uma linha de cabeçalho (Padrão = False).

casesensitive: Especifica se as comparações de cadeias de caracteres devem distinguir maiúsculas de minúsculas (Padrão = False).

modo: Especifica o que fazer com as linhas duplicadas. Se modo = "CLEAR", as duplicatas são simplesmente removidas da folha, deixando as células em branco. Se modo = "COMPACT", as duplicatas são removidas e as linhas vazias são compactadas (Predefinição = "COMPACT").

### Exemplo:

##### Em Basic

        ' Remove as linhas duplicadas em que os valores da coluna A são duplicados
        ' Note que todos os argumentos opcionais utilizam o seu valor por predefinição
        oDoc.RemoveDuplicates("A1:B10")
        ' Remove as linhas duplicadas, partindo do princípio de que a primeira linha contém os cabeçalhos
        As colunas A e B são utilizadas para determinar se uma linha é uma duplicata
        As células que contêm valores duplicados ficam em branco
        oDoc.RemoveDuplicates("A1:D10", columns := Array(1, 2), header := True, mode := "CLEAR")

##### Em Python

        myDoc.RemoveDuplicates("A1:B10")
        myDoc.RemoveDuplicates("A1:D10", columns = (1, 2), header = True, mode = "CLEAR")

## RemoveSheet

Remove uma folha existente do documento.

### Sintaxe:

svc.RemoveSheet(sheetname: str): bool

### Parâmetros:

sheetname: O nome da folha a remover.

### Exemplo:

##### Em Basic

        oDoc.RemoveSheet("SheetY")

##### Em Python

        myDoc.RemoveSheet("SheetY")

## RenameSheet

Renomeia a folha indicada e devolve True se a operação for bem-sucedida.

### Sintaxe:

svc.RenameSheet(sheetname: str, newname: str): bool

### Parâmetros:

sheetname: O nome da folha a renomear.

newname: o novo nome da folha. Ainda não pode existir.

### Exemplo:

Este exemplo renomeia a folha ativa para «SheetY»:

##### Em Basic

        oDoc.RenameSheet("~", "SheetY")

##### Em Python

        mydoc.RenameSheet("~", "SheetY")

## SetArray

Armazena o valor fornecido a partir de uma célula de destino especificada. A área atualizada expande-se a partir da célula de destino ou do canto superior esquerdo do intervalo indicado, de modo a acomodar o tamanho do argumento de entrada valor. Os vetores são sempre expandidos verticalmente.

O método devolve uma cadeia de caracteres que representa a área modificada como um intervalo de células.

### Sintaxe:

svc.SetArray(targetcell: str, value: any): str

### Parâmetros:

targetcell: A célula ou um intervalo, expresso como uma cadeia de caracteres, a partir do qual se deve começar a armazenar o valor indicado.

value: Um escalar, um vetor ou uma matriz (em Python, listas e tuplas unidimensionais ou bidimensionais) com os novos valores a serem armazenados a partir da célula de destino ou do canto superior esquerdo do intervalo, caso targetcell seja um intervalo. Os novos valores devem ser cadeias de caracteres, valores numéricos ou datas. Outros tipos de dados farão com que as células correspondentes fiquem vazias.

### Exemplo:

##### Em Basic

O exemplo seguinte utiliza a função integrada DimArray para criar uma matriz e, em seguida, armazená-la na célula «A1»:

        Dim arrData as Variant
        arrData = DimArray(2, 1)
        arrData(0, 0) = 1 : arrData(1, 0) = 2 : arrData(2, 0) = 3
        arrData(0, 1) = "One" : arrData(1, 1) = "Two" : arrData(2, 1) = "Three"
        oDoc.SetArray("Sheet1.A1", arrData)

Este exemplo utiliza o método RangeInit do serviço ScriptForge Array para criar uma matriz com valores que são, em seguida, armazenados a partir da célula «A1» e para baixo.

        «Preencha a primeira coluna com valores de 1 a 1000»
        oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))

##### Em Python

        arrData = ((1, "One"), (2, "Two"), (3, "Three"))
        myDoc.SetArray("Sheet1.A1", arrData)

        myDoc.SetArray("Sheet1.A1", tuple(i + 1 for i in range(1000)))

Para inserir todo o conteúdo de uma matriz numa folha, utilize SetArray. Para inserir o conteúdo de uma matriz apenas dentro dos limites do intervalo de células pretendido, utilize SetValue.

## SetCellStyle

Aplica o estilo de célula especificado ao intervalo de destino indicado. Todo o intervalo é atualizado e o resto da folha permanece inalterado. Se o estilo de célula não existir, é gerado um erro.

O método devolve uma cadeia de caracteres que representa a área modificada como um intervalo de células.

### Sintaxe:

svc.SetCellStyle(targetrange: str, style: str, opt filterformula: str, opt filterscope: str): str

### Parâmetros:

targetrange: O intervalo ao qual o estilo será aplicado, expresso como uma cadeia de caracteres.

style: O nome do estilo de célula a aplicar.

filterformula: Uma fórmula do Calc que deve ser aplicada ao intervalo indicado para determinar quais as células que serão afetadas. A fórmula especificada deve devolver True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é aplicada ao intervalo indicado. Este argumento é obrigatório se for especificada uma filterformula. São aceites os seguintes valores:

- "CELL": A fórmula especificada no argumento filterformula é aplicada uma vez a cada célula do range.

- "ROW": A fórmula especificada no argumento filterformula é aplicada uma vez a cada linha do range.

- "COLUMN": A fórmula especificada no argumento filterformula é aplicada uma vez a cada coluna do intervalo.

### Exemplo:

##### Em Basic

        oDoc.SetCellStyle("A1:J1", "Heading 1")
        oDoc.SetCellStyle("A2:J100", "Neutral")

##### Em Python

        myDoc.SetCellStyle("A1:J1", "Heading 1")
        myDoc.SetCellStyle("A2:J100", "Neutral")

Consulte a documentação do método ClearAll para obter exemplos sobre como utilizar os argumentos filterformula e filterscope.

## SetFormula

Inserir a fórmula ou o conjunto de fórmulas indicado(s) no intervalo especificado. A área alterada tem o mesmo tamanho que o intervalo.

O método devolve uma cadeia de caracteres que representa a área modificada como um intervalo de células.

### Sintaxe:

svc.SetFormula(targetrange: str, formula: any): str

### Parâmetros:

targetrange: O intervalo onde inserir as fórmulas, na forma de uma cadeia de caracteres.

formula: Uma cadeia de caracteres, um vetor ou uma matriz de cadeias de caracteres com as novas fórmulas para cada célula do intervalo de destino.

Todo o intervalo é atualizado e o resto da folha permanece inalterado.

Se a fórmula indicada for uma cadeia de caracteres, a fórmula única é inserida em todo o intervalo, com o ajuste das referências relativas.

Se o tamanho da formula for menor do que o tamanho do targetrange, as células restantes serão esvaziadas.

Se o tamanho da formula for superior ao tamanho do targetrange, as fórmulas serão copiadas apenas parcialmente, até preencherem o tamanho do intervalo de destino.

Os vetores são sempre expandidos verticalmente, exceto se targetrange tiver uma altura de exatamente 1 linha.

As funções do Calc utilizadas no argumento formula devem ser indicadas utilizando os seus nomes em inglês. Consulte a página da Wiki Lista de funções do Calc para obter uma lista completa das funções do Calc em inglês.

### Exemplo:

##### Em Basic

        oDoc.SetFormula("A1", "=A2")
        'Vetor horizontal, parcialmente vazio
        oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
        A célula D2 contém a fórmula «=H2»
        oDoc.SetFormula("A1:D2", "=E1")

##### Em Python

        myDoc.SetFormula("A1", "=A2")
        myDoc.SetFormula("A1:F1", ("=A2", "=B2", "=C2+10"))
        myDoc.SetFormula("A1:D2", "=E1")

## SetValue

Armazena o valor indicado no intervalo especificado. O tamanho da área modificada é igual ao tamanho do intervalo de destino.

O método devolve uma cadeia de caracteres que representa a área modificada como um intervalo de células.

### Sintaxe:

svc.SetValue(targetrange: str, value: any): str

### Parâmetros:

targetrange: O intervalo onde o valor fornecido deve ser armazenado, na forma de uma cadeia de caracteres.

value: Um escalar, um vetor ou uma matriz com os novos valores para cada célula do intervalo. Os novos valores devem ser cadeias de caracteres, valores numéricos ou datas. Outros tipos de dados farão com que as células correspondentes fiquem vazias.

Todo o intervalo é atualizado e o resto da folha permanece inalterado. Se o tamanho de value for menor do que o tamanho de intervalo-alvo, as células restantes serão esvaziadas.

Se o tamanho de value for superior ao tamanho de targetrange, então value é copiado apenas parcialmente, até preencher o tamanho de targetrange.

Os vetores são expandidos verticalmente, exceto se targetrange tiver uma altura de exatamente 1 linha.

### Exemplo:

##### Em Basic

        oDoc.SetValue("A1", 2)
        «A matriz Value é menor do que o TargetRange (as células restantes ficam vazias)»
        oDoc.SetValue("A1:F1", Array(1, 2, 3))
        'Abaixo de Value e TargetRange têm o mesmo tamanho»
        oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))

Se pretender preencher uma única linha com valores, pode utilizar a função Offset. No exemplo abaixo, considere que arrData é uma matriz unidimensional:

        Dim firstCell As String : firstCell = "A1"
        Dim lenArray As Integer : lenArray = UBound(arrData) - LBound(arrData) + 1
        Dim newRange As String : newRange = oDoc.Offset(firstCell, width = lenArray)
        oDoc.SetValue(newRange, arrData)

##### Em Python

        myDoc.SetValue("A1", 2)
        myDoc.SetValue("A1:F1", (1, 2, 3))
        myDoc.SetValue("A1:D2", ((1, 2, 3, 4), (5, 6, 7, 8)))

        firstCell = "A1"
        newRange = doc.Offset(firstCell, width = len(arrData))
        doc.SetValue(newRange, arrData)

## ShiftDown

Desloca um determinado intervalo de células para baixo, inserindo linhas vazias. A seleção atual não é afetada.

Dependendo do valor do argumento wholerow, as linhas inseridas podem ocupar toda a largura do intervalo especificado ou todas as colunas da linha.

Este método devolve uma cadeia de caracteres que representa a nova localização do intervalo inicial.

Se a área deslocada ultrapassar as margens da folha, nada acontece.

### Sintaxe:

svc.ShiftDown(range: str, wholerow: bool = False, opt rows: int): str

### Parâmetros:

range: O intervalo acima do qual serão inseridas as linhas, na forma de uma cadeia de caracteres.

wholerow: Se definido como False (padrão), a largura das linhas inseridas será igual à largura do intervalo especificado. Caso contrário, a linha inserida ocupará todas as colunas da folha.

rows: O número de linhas a inserir. O valor predefinido é a altura do intervalo original. O número de linhas deve ser um número positivo.

### Exemplo:

##### Em Basic

        ' Desloca o intervalo "A3:D3" uma linha para baixo; afeta apenas as colunas A a D
        oDoc.ShiftDown("A3:D3")
        ' A linha inserida ocupa todas as colunas da folha
        oDoc.ShiftDown("A3:D3", WholeRow := True)
        ' Desloca o intervalo "A3:D3" cinco linhas para baixo
        oDoc.ShiftDown("A3:D3", Rows := 5)
        ' Desloca o intervalo "A3:D10" duas linhas para baixo e mostra a nova localização do intervalo original
        Dim sNewRange as String
        sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
        MsgBox sNewRange   ' $Sheet1.$A$5:$D$12

##### Em Python

        myDoc.ShiftDown("A3:D3")
        myDoc.ShiftDown("A3:D3", wholerow = True)
        myDoc.ShiftDown("A3:D3", rows = 5)
        sNewRange = myDoc.ShiftDown("A3:D10", rows = 2)
        bas = CreateScriptService("Basic")
        bas.MsgBox(sNewRange)

## ShiftLeft

Elimina as colunas mais à esquerda de um determinado intervalo e desloca para a esquerda todas as células à direita do intervalo afetado. A seleção atual não é afetada.

Dependendo do valor do argumento wholecolumn, as colunas eliminadas podem abranger a altura do intervalo especificado ou todas as linhas da coluna.

Este método devolve uma cadeia de caracteres que representa a localização da parte restante do intervalo inicial. Se todas as células do intervalo original tiverem sido eliminadas, é devolvida uma cadeia de caracteres vazia.

### Sintaxe:

svc.ShiftLeft(range: str, wholecolumn: bool = False, opt columns: int): str

### Parâmetros:

range: O intervalo a partir do qual as células serão eliminadas, expresso como uma cadeia de caracteres.

wholecolumn: Se definido como False (padrão), a altura das colunas eliminadas será igual à altura do intervalo especificado. Caso contrário, as colunas eliminadas abrangerão todas as linhas da folha.

columns: O número de colunas a eliminar do range especificado. O valor predefinido é a largura do range original, que é também o valor máximo deste argumento.

### Exemplo:

##### Em Basic

        ' Elimina o intervalo "B3:B6"; desloca todas as células à direita para a esquerda
        oDoc.ShiftLeft("B3:B6")
        ' Apaga a primeira coluna do intervalo "A3:D6"
        oDoc.ShiftLeft("A3:D6", Columns := 1)
        As colunas eliminadas (A a D) abrangem todas as linhas da folha
        oDoc.ShiftLeft("A3:D6", WholeColumn := True)

##### Em Python

        myDoc.ShiftLeft("B3:B6")
        myDoc.ShiftLeft("A3:D6", Columns = 1)
        myDoc.ShiftLeft("A3:D6", WholeColumn = True)

## ShiftUp

Elimina as linhas superiores de um determinado intervalo e desloca para cima todas as células abaixo do intervalo afetado. A seleção atual não é afetada.

Dependendo do valor do argumento wholerow, as linhas eliminadas podem ocupar toda a largura do intervalo especificado ou todas as colunas da linha.

Este método devolve uma cadeia de caracteres que representa a localização da parte restante do intervalo inicial. Se todas as células do intervalo original tiverem sido eliminadas, é devolvida uma cadeia de caracteres vazia.

### Sintaxe:

svc.ShiftUp(range: str, wholerow: bool = False, opt rows: int): str

### Parâmetros:

range: O intervalo a partir do qual as células serão eliminadas, expresso como uma cadeia de caracteres.

wholerow: Se definido como False (valor predefinido), a largura das linhas eliminadas será igual à largura do range especificado. Caso contrário, a linha eliminada ocupará todas as colunas da folha.

rows: O número de linhas a eliminar do range especificado. O valor predefinido é a altura do range original, que é também o valor máximo deste argumento.

### Exemplo:

##### Em Basic

        ' Elimina o intervalo "A3:D3"; desloca todas as células abaixo desse intervalo uma linha para cima
        oDoc.ShiftUp("A3:D3")
        ' Elimina o intervalo "A3:D3"; desloca todas as células abaixo desse intervalo uma linha para cima
        oDoc.ShiftUp("A3:D6", Rows := 1)
        «As linhas eliminadas abrangem todas as colunas da folha»
        oDoc.ShiftUp("A3:D6", WholeRow := True)

##### Em Python

        myDoc.ShiftUp("A3:D3")
        myDoc.ShiftUp("A3:D6", rows = 1)
        myDoc.ShiftUp("A3:D6", wholerow = True)

## ShiftRight

Desloca um determinado intervalo de células para a direita, inserindo colunas vazias. A seleção atual não é afetada.

Dependendo do valor do argumento wholecolumn, as colunas inseridas podem ocupar toda a altura do intervalo especificado ou todas as linhas da coluna.

Este método devolve uma cadeia de caracteres que representa a nova localização do intervalo inicial.

Se a área deslocada ultrapassar as margens da folha, nada acontece.

### Sintaxe:

svc.ShiftRight(range: str, wholecolumn: bool = False, opt columns: int): str

### Parâmetros:

range: O intervalo no qual serão inseridas colunas vazias à sua esquerda, na forma de uma cadeia de caracteres.

wholecolumn: Se definido como False (padrão), a altura das colunas inseridas será igual à altura do range especificado. Caso contrário, as colunas inseridas abrangerão todas as linhas da folha.

columns: O número de colunas a inserir. O valor predefinido é a largura do range original.

### Exemplo:

##### Em Basic

        ' Desloca o intervalo "A3:A6" uma coluna para a direita; afeta apenas as linhas 3 a 6
        oDoc.ShiftRight("A3:A6")
        ' Desloca o intervalo "A3:A6" cinco colunas para a direita
        oDoc.ShiftRight("A3:A6", Columns := 5)
        A coluna inserida abrange todas as linhas da folha
        oDoc.ShiftRight("A3:A6", WholeColumn := True)

##### Em Python

        myDoc.ShiftRight("A3:A6")
        myDoc.ShiftRight("A3:A6", columns = 5)
        myDoc.ShiftRight("A3:A6", wholecolumn = True)

## SortRange

Ordene o intervalo indicado em qualquer número de colunas/linhas. A ordem de ordenação pode variar consoante a coluna/linha. Se o número de chaves de ordenação for superior a 3, o intervalo é ordenado várias vezes, em grupos de 3 chaves, começando pela última chave. Devolve uma cadeia de caracteres que representa o intervalo de células modificado. O tamanho da área modificada é inteiramente determinado pelo tamanho da área de origem.

### Sintaxe:

svc.SortRange(range: str, sortkeys: any, sortorder: any = "ASC", destinationcell: str = "", containsheader: bool = False, casesensitive: bool = False, sortcolumns: bool = False): str

### Parâmetros:

range: O intervalo a ser ordenado, na forma de uma cadeia de caracteres.

sortkeys: Um valor escalar (se for 1 coluna/linha) ou uma matriz de números de colunas/linhas a partir de 1.

sortorder: Um valor escalar ou uma matriz de cadeias de caracteres contendo os valores "ASC" (ascendente) e "DESC" (descendente). Cada item é emparelhado com o item correspondente em sortkeys. Se a matriz sortorder for mais curta do que sortkeys, as chaves restantes são ordenadas por ordem ascendente.

destinationcell: A célula de destino do intervalo de células ordenado, expressa como uma cadeia de caracteres. Se for indicado um intervalo, apenas a célula do canto superior esquerdo é considerada. Por predefinição, o intervalo de origem é substituído.

containsheader: Quando True, a primeira linha/coluna não é ordenada.

distingue maiúsculas e minúsculas: Apenas para comparações de cadeias de caracteres. Valor predefinido = False

sortcolumns: Quando True, as colunas são ordenadas da esquerda para a direita. Padrão = False: as linhas são ordenadas de cima para baixo.

### Exemplo:

##### Em Basic

        'Ordenar o intervalo com base nas colunas A (por ordem crescente) e C (por ordem decrescente)
        oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)

##### Em Python

        myDoc.SortRange("A2:J200", (1, 3), ("ASC", "DESC"), casesensitive = True)

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 SFDocuments.Chart

SFDocuments.Document serviço

ScriptForge.UI service

Necessitamos da sua ajuda!