Sumário

# Serviço SFDocuments.Calc

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

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

O serviço Calc tem como foco:

- Manusear planilhas em um documento Calc (copiar, inserir, mover, etc)

- Trocar dados entre estruturas de dados Basic e células no 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 são aplicáveis apenas a documentos Calc.

## Invocação do serviço

Antes de usar o serviço Calc a biblioteca ScriptForge precisa ser carregada ou importada:

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService

O serviço Calc se relaciona com o serviço UI da biblioteca ScriptForge. Abaixo estão 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 Calc atualmente ativo.

        Set oDoc = CreateScriptService("Calc")

Outra forma de criar uma instância do serviço Calc é usando o serviço UI. No exemplo a seguir um novo documento Calc é criado e oDoc representa a instância do serviço Calc:

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

Ou usando 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 o nome da 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 aberto. Se este argumento não for fornecido, a janela ativa é considerada.

Também é possível chamar o serviço Calc referenciando o documento por meio de ThisComponent. Isto é especialmente útil em macros criadas por meio do IDE Basic nativo.

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

É recomendado liberar recursos após o uso:

        Set oDoc = oDoc.Dispose()

Entretanto, se o documento foi fechado usando o método CloseDocument, não é necessário liberar recursos usando o comando descrito acima.

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

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

## Definições

Muitos métodos requerem um Sheet ou um Range como argumento. Células individuais são consideradas como um caso especial de um Range.

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

- Dentro de uma instância Calc específica, planilhas e intervalos são expressos como strings tais como "Planilha1" e "D2:F6".

- Adicionalmente, as propriedades .Sheet e .Range retornam uma referência que pode ser usada 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 como somente-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

Pode ser um nome de planilha como uma String ou um Object produzido pela propriedade .Sheet.

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

### RangeName

Pode ser uma String designando um conjunto de células contíguas localizadas em uma planilha ou a instância atual de um Object produzido pela propriedade .Range.

O atalho "~" (til) representa a seleção atual ou o primeiro intervalo de células se múltiplos intervalos estiverem selecionados.

O atalho "*" representa todas as células usadas.

O nome da planilha é opcional ao definir um intervalo. Se nenhum nome de planilha for fornecido, então a planilha ativa é usada. Aspas e símbolos $ são permitidos, porém ignorados.

Ao especificar um SheetName como uma string, o uso de aspas simples em volta do nome da planilha é obrigatório se o nome contiver espaços em branco " " ou pontos ".".

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

          ' O uso de aspas simples é opcional
          oDoc.clearAll("SheetA.A1:B10")
          oDoc.clearAll("'SheetA'.A1:B10")
          ' O uso de aspas simples é obrigatório
          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) $'PlanilhaX'.D2 2) $D$2 | Célula única
1) $'PlanilhaX'.D2:F6 2) D2:D10 | Intervalo único com múltiplas células
$'PlanilhaX'.* | Todas as células usadas em uma dada planilha
1) $'PlanilhaX'.A:A (Coluna A) 2) 3:5 (Linhas 3 a 5) | Todas as células em colunas ou linhas contíguas até a última célula usada
umIntervalo | Um intervalo chamado "umIntervalo" no nível da planilha
1) ~.nomeIntervalo 2) PlanilhaX.nomeIntervalo | Um intervalo nomeado no nível da planilha
myDoc.Range("PlanilhaX.D2:F6") | Um intervalo dentro da PlanilhaX em um arquivo associado com a instância Calc "myDoc"
~.~ ou ~ | Seleção atual na planilha ativa

## Propriedades

Todas as propriedades genéricas para qualquer documento são implicitamente aplicáveis aos documentos Calc. Para mais informações, leia a página de ajuda do serviço Document.

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

Nome | Somente leitura | Argumento | Tipo de retorno | Descrição
--- | --- | --- | --- | ---
CurrentSelection | Não | Nenhum | String ou array de strings | O intervalo único selecionado como uma string ou uma lista de intervalos selecionados como um array.
DefinedNames | Sim | Nenhum | Cadeia de caracteres ou matriz de cadeias de caracteres | Retorna a lista completa e ordenada de todos os intervalos nomeados no documento. Os nomes definidos em uma única planilha são qualificados com o nome da planilha.
FirstCell | Sim | SheetName ou RangeName como uma String | String | Retorna a primeira célula usada em um determinado intervalo ou planilha.
FirstColumn | Sim | SheetName ou RangeName como uma String | Long | Retorna o número da coluna mais à esquerda em um determinado intervalo ou planilha.
FirstRow | Sim | SheetName ou RangeName como uma String | Long | Retorna o número da linha superior num determinado intervalo ou planilha.
Height | Sim | RangeName como uma String | Long | O número de linhas (>= 1) em um dado intervalo.
LastCell | Sim | SheetName ou RangeName como uma String | String | Retorna a última célula usada em um determinado intervalo ou planilha.
LastColumn | Sim | SheetName ou RangeName como uma String | Long | A última coluna usada em um determinado intervalo ou planilha.
LastRow | Sim | SheetName ou RangeName como uma String | Long | A última linha usada em um determinado intervalo ou planilha.
Range | Sim | RangeName como uma String | Object | Uma referência de intervalo que pode ser usada como argumento para métodos como CopyToRange.
Region | Sim | RangeName como uma String | String | Retorna o endereço da menor área que contém o intervalo especificado de tal forma que a área é envolvida por células vazias ou limites da planilha. É equivalente a aplicar o atalho Command + *Ctrl + * ao intervalo especificado.
Sheet | Sim | SheetName como uma String | Object | Uma referência de planilha que pode ser usada como argumento para métodos como CopySheet.
SheetName | Sim | RangeName como uma String | String | Retorna o nome da planilha de um dado endereço de intervalo.
Sheets | Sim | Nenhum | Array de strings | A lista com os nomes de todas as planilhas existentes.
Width | Sim | RangeName como uma String | Long | O número de colunas (>= 1) em um dado intervalo.
XCellRange | Sim | RangeName como uma String | Object | Um objeto UNO com.sun.star.Table.XCellRange.
XRectangle | Sim | NomeDoIntervalo Como String | Object | Uma estrutura UNO com.sun.star.awt.Rectangle, que descreve, em pixels, a área na tela onde o intervalo está localizado.
XSheetCellCursor | Sim | RangeName como uma String | Object | Um objeto UNO do tipo com.sun.star.sheet.XSheetCellCursor. Após mover o cursor, o endereço resultante pode ser acessado pela propriedade UNO AbsoluteName do objeto de cursor, o qual retorna uma string que pode ser usada 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 website da documentação da API do LibreOffice para saber mais sobre os objetos UNO XCellRange, XSheetCellCursor e XSpreadsheet.

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

Retorna um endereço de intervalo como uma string com base em coordenadas de planilha, tais como números de linha e coluna.

Se apenas um par de coordenadas forem fornecidas, então o endereço para uma célula única é retornado. Argumentos adicionais podem especificar a célula inferior esquerda de um intervalo retangular de células.

### Sintaxe:

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

### Parâmetros:

row1, column1: Especifica os números de linha e coluna da célula superior esquerda do intervalo a ser considerado. Números de linha e coluna se iniciam em 1.

row2, column2: Especifica o número da linha e da coluna da célula inferior direita do intervalo a ser considerado. Se estes argumentos não forem fornecidos, ou se seus valores forem inferiores que row1 e column1 então o endereço de uma célula única correspondente às coordenadas row1 e column1 será retornado.

sheetname: Nome da planilha que será acrescentado ao endereço retornado. A planilha deve existir. O valor padrão é "~" correspondendo à planilha ativa.

### Exemplo:

Os exemplos abaixo em Basic e Python consideram que "Sheet1" é a planilha 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 quaisquer das propriedades e métodos do serviço Calc que requerem um intervalo como argumento, tais como GetValue, GetFormula, ClearAll, etc.

## Activate

Se o argumento sheetname for fornecido, a planilha é ativada e se torna a planilha selecionada. Se este argumento não for fornecido, então a janela do documento é ativada.

### Sintaxe:

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

### Parâmetros:

sheetname: O nome da planilha a ser ativada no documento. O valor padrão é uma String vazia, o que fará com que o documento atual seja ativado sem modificar a planilha ativa.

### Exemplo:

O exemplo abaixo ativa a planilha chamada "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")

Ativar a planilha faz sentido apenas se for executado em um documento Calc. Para garantir que você tem um documento Calc em mãos, você pode usar a propriedade isCalc do objeto do documento, a qual retorna True se é um documento Calc e False caso contrário.

## AlignRange

Alinhar horizontalmente ou verticalmente um intervalo de células.

É possível especificar uma fórmula de filtro para determinar quais células 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, em formato de string, no qual as células devem ser realinhadas.

alinhamento: uma sequência de caracteres combinando 1 ou 2 caracteres maiúsculos subsequentes (outros caracteres são ignorados):

- L, R ou C: esquerda, direita ou centro horizontalmente.

- B, T ou M: inferior, superior ou central verticalmente (meio).

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

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

          ' Centralize todas as células numéricas, tanto horizontal quanto verticalmente.
          doc.AlignRange("SheetX.A1:J30", "Middle,Center", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

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

## BorderRange

Aplique um conjunto de bordas de linha dentro e ao redor de um intervalo de células.

As células afetadas podem ser identificadas por meio de uma fórmula de filtro e seu escopo.

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 demais 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, representado como uma string, ao qual as bordas devem ser aplicadas.

border: Uma sequência de caracteres que combina os próximos caracteres maiúsculos (os demais caracteres são ignorados):

- B, L, T, R: linhas externas inferior, esquerda, superior e direita.

- H, V: linhas internas horizontais e verticais.

- U, D: 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 células serão afetadas. A fórmula especificada deve retornar True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

            ' Coloque uma borda na parte inferior de 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 borda 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

Retorna a lista com os nomes de todos os objetos de gráfico em uma planilha ou uma instância do serviço Chart.

- Se apenas sheetname for especificado, retorna um Array indexado a partir de zero contendo os nomes de todos os objetos de gráfico.

- Se o argumento chartname for fornecido, então um objeto único correspondente ao gráfico desejado é retornado. O gráfico especificado deve existir.

### Sintaxe:

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

### Parâmetros:

sheetname: Nome da planilha da qual a lista de gráficos será obtida ou o nome da planilha onde o gráfico especificado está localizado.

chartname: Nome definido pelo usuário do objeto de gráfico a ser retornado. Se o gráfico não tiver um nome definido pelo usuário, então o nome interno do objeto pode ser usado. Se este argumento não for fornecido, então a lista com os nomes dos gráficos da planilha especificada será retornada.

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

### Exemplo:

##### Em Basic

O exemplo abaixo mostra o número de objetos de gráfico na planilha "Sheet1".

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

O exemplo a seguir acessa o gráfico chamado "MyChart" na planilha "Sheet1" e imprime 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 todos os conteúdos e formatos de um dado intervalo.

Uma fórmula de filtro pode ser usada para determinar quais células devem ser afetadas.

### Sintaxe:

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

### Parâmetros:

range: O intervalo a ser limpo, como uma string.

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

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

        ' Apaga todas as células no intervalo SheetX.A1:J10
        oDoc.ClearAll("SheetX.A1:J10")
        ' Limpa todas as células do intervalo PlanilhaX.A1:J10 que possuem um valor maior que 100
        oDoc.ClearAll("SheetX.A1:J10", "=PlanilhaX.A1>100", "CELL")
        ' Limpa todas as linhas do intervalo SheetX.A1:J10 cuja soma é maior que 500
        oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:J1)>500", "ROW")
        ' Limpa todas as colunas do intervalo SheetX.A1:J10 cuja soma é maior que 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 estilos de célula no intervalo especificado.

Uma fórmula de filtro pode ser usada para determinar quais células devem ser afetadas.

### Sintaxe:

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

### Parâmetros:

range: Intervalo cujos formatos e estilos devem ser limpos, como uma string.

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

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

          oDoc.ClearFormats("SheetX.*")

##### Em Python

        myDoc.ClearFormats("SheetX.*")

Consulte à documentação de método ClearAll para obter exemplos de como usar os argumentos filterformula e filterscope.

## ClearValues

Limpa os valores e fórmulas em um dado intervalo.

Uma fórmula de filtro pode ser usada para determinar quais células devem ser afetadas.

### Sintaxe:

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

### Parâmetros:

range: Intervalo cujos valores e fórmulas devem ser limpos, como uma string.

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

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

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

##### Em Python

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

Consulte à documentação de método ClearAll para obter exemplos de como usar 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 por meio de uma fórmula de filtro e seu escopo.

### 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, representado por uma sequência de caracteres, no qual as células devem ser (re)coloridas.

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

fundo: a cor de fundo como 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 células serão afetadas. A fórmula especificada deve retornar True ou False. Se este argumento não for especificado, todas as células do intervalo serão afetadas.

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CompactLeft

Remove as colunas de um dado intervalo que são selecionadas por um filtro expresso como uma fórmula do Calc. O filtro é aplicado a cada coluna para decidir se ela será excluída ou não.

A coluna removida pode ser limitada à altura do intervalo especificado ou se estender à altura total da planilha, consequentemente removendo colunas inteiras.

Este método retorna uma string com o endereço do intervalo compactado. Se todas as colunas forem removidas, então uma string vazia é retornada.

Se um intervalo de células estiver selecionado, chamar este método não impactará na seleção.

### Sintaxe:

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

### Parâmetros:

range: o intervalo do qual as colunas serão removidas, como uma string.

wholecolumn: Se esta opção for definida como True a coluna inteira será removida da planilha. O valor padrão é False, o que significa que a coluna removida será limitada à altura do intervalo definido no parâmetro range.

filterformula: Filtro a ser aplicada a cada uma das colunas para determinar se elas serão removidas ou não. O filtro é expresso como uma fórmula do Calc que deve ser aplicada a cada coluna. Se a fórmula retornar True para uma coluna, então a coluna será removida. O filtro padrão remove todas as colunas vazias.

Por exemplo, considere que o intervalo A1:J200 está selecionado (altura = 200), então a fórmula padrão é =(CONTAR.VAZIO(A1:A200)=200). Isto significa que se todas as 200 células estiverem vazias na primeira coluna (Coluna A), então a coluna será removida. Note que a fórmula é expressa com relação à primeira coluna apenas. Internamente o método CompactLeft generalizará a fórmula para todas as demais colunas.

As funções do Calc usadas no argumento filterformula devem ser expressas usando seus nomes 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.

### Exemplo:

##### Em Basic

        ' Remove todas as colunas vazias no intervalo G1:L10 da Planilha1
        newrange = oDoc.CompactLeft("Planilha1.G1:L10")
        ' O exemplo abaixo é similar, mas as colunas inteiras são removidas da planilha
        newrange = oDoc.CompactLeft("Planilha1.G1:L10", WholeColumn := True)
        ' Remove todas as colunas nas quais a primeira linha é marcada com "X"
        newrange = oDoc.CompactLeft("Planilha1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Remove todas as colunas cuja soma dos valores na coluna é ímpar
        newrange = oDoc.CompactLeft("Planilha1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")

##### Em Python

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

## CompactUp

Remove as linhas de um dado intervalo que são selecionadas por um filtro expresso como uma fórmula do Calc. O filtro é aplicado a cada linha para decidir se ela será excluída ou não.

As linhas removidas podem ser limitadas à largura do intervalo especificado ou se estender à largura total da planilha, consequentemente removendo linhas inteiras.

Este método retorna uma string com o endereço do intervalo compactado. Se todas as linhas forem removidas, então uma string vazia é retornada.

Se um intervalo de células estiver selecionado, chamar este método não impactará na seleção.

### Sintaxe:

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

### Parâmetros:

range: o intervalo do qual as linhas serão excluídas, como uma string.

wholecolumn: Se esta opção for definida como True a linha inteira será removida da planilha. O valor padrão é False, o que significa que a linha removida será limitada à largura do intervalo definido no parâmetro range.

filterformula: Filtro a ser aplicada a cada uma das linhas para determinar se elas serão removidas ou não. O filtro é expresso como uma fórmula do Calc que deve ser aplicada a cada linha. Se a fórmula retornar True para uma linha, então a linha será removida. O filtro padrão remove todas as linhas vazias.

Por exemplo, considere que o intervalo A1:J200 está selecionado (largura = 10), então a fórmula padrão é =(CONTAR.VAZIO(A1:J1)=10). Isto significa que se todas as 10 células estiverem vazias na primeira linha (Linha 1), então a linha será removida. Note que a fórmula é expressa com relação à primeira linha apenas. Internamente o método CompactUp generalizará a fórmula para todas as demais linhas.

As funções do Calc usadas na fórmula especificada no argumento filterformula devem ser expressas usando seus nomes 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.

### Exemplo:

##### Em Basic

        ' Remove todas as linhas vazias no intervalo G1:L10 da Planilha1
        newrange = oDoc.CompactUp("Planilha1.G1:L10")
        ' O exemplo abaixo é similar, mas as linhas inteiras são removidas da planilha
        newrange = oDoc.CompactUp("Planilha1.G1:L10", WholeRow := True)
        ' Remove todas as linhas nas quais a primeira coluna é marcada com "X"
        newrange = oDoc.CompactUp("Planilha1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Remove todas as linhas cuja soma dos valores na linha é ímpar
        newrange = oDoc.CompactUp("Planilha1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")

##### Em Python

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

## CopySheet

Copia uma planilha especificada antes de uma planilha existente ou ao final da lista de planilhas. A planilha a ser copiada pode estar contida em qualquer documento Calc aberto. Retorna True se bem-sucedido.

### Sintaxe:

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

### Parâmetros:

sheetname: Nome da planilha a ser copiada, como uma string, ou sua referência como um objeto.

newname: Nome da planilha a ser inserida. O nome não pode estar sendo usado no documento.

beforesheet: O nome (string) ou índice (numérico, iniciando em 1) da planilha antes da qual será inserida a planilha copiada. Este argumento é opcional e o comportamento padrão é inserir a planilha copiada na última posição.

### Exemplo:

##### Em Basic

O exemplo a seguir faz uma cópia da planilha "SheetX" e insere-a como a última planilha no documento atual. O nome da planilha 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 "SheetX" do arquivo "FilaA.ods" e cola a planilha na última posição do arquivo "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 planilhas entre documentos abertos, use o método CopySheet. Para copiar planilhas em documentos que estão fechados, use o método CopySheetFromFile.

## CopySheetFromFile

Copia uma planilha especificada de um documento Calc fechado e cola essa planilha antes de uma planilha existente ou ao final da lista de planilhas do arquivo referenciado por um objeto Document.

Se o arquivo não existe, um erro é lançado. Se o arquivo não é um arquivo Calc válido, uma planilha em branco é inserida. Se a planilha de origem não existir no arquivo de entrada, uma mensagem de erro é inserida no topo da planilha recentemente colada no arquivo.

### Sintaxe:

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

### Parâmetros:

filename: Identifica o arquivo a ser aberto. Deve seguir a notação definida em SF_FileSystem.FileNaming. O arquivo não pode estar protegido com senha.

sheetname: Nome da planilha a ser copiada, como uma string.

newname: Nome da planilha copiada a ser inserida no documento. O nome não pode estar sendo usado no documento.

beforesheet: O nome (string) ou índice (numérico, iniciando em 1) da planilha antes da qual será inserida a planilha copiada. Este argumento é opcional e o comportamento padrão é inserir a planilha copiada na última posição.

### Exemplo:

O exemplo a seguir copia "SheetX" do arquivo "myFile.ods" e cola a planilha no documento referenciado por "oDoc" com o nome "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órmula e formatos) para uma célula ou intervalo de destino. O método reproduz o comportamento da operação Copiar/Colar de um intervalo para uma célula única.

Retorna uma string representando o intervalo de células modificado. O tamanho da área modificada é determinado pelo tamanho 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: Intervalo de origem como uma string quando pertencer ao mesmo documento, ou como uma referência quando pertencer a outro documento Calc aberto.

destinationcell: Célula de destino onde o intervalo copiado de células será colado, como uma string. Se um intervalo for dado, somente a célula no canto superior esquerdo é considerada.

### Exemplo:

##### Em Basic

A seguir é dado um exemplo onde a origem e destino estão no mesmo arquivo:

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

O exemplo abaixo ilustra como copiar um intervalo de outro documento Calc aberto:

        Dim ui as Variant : ui = CreateScriptService("UI")
        Dim oDocSource As Object, oDocDestination As Object
        'Abre 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 ele 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 Copiar/Colar de um intervalo para uma célula única, use CopyToCell. Para simular um Copiar/Colar de um intervalo para um intervalo maior (com as mesmas células sendo replicadas várias vezes), use CopyToRange.

## CopyToRange

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

- Se a altura (ou a largura) da área de destino for maior que uma linha (ou coluna) então a altura (ou largura) da área de origem deve ser menor ou igual à altura (ou largura) da área de destino. Caso contrário, nada acontecerá.

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

O método retorna uma string representando 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: Intervalo de origem como uma string quando pertencer ao mesmo documento, ou como uma referência quando pertencer a outro documento Calc aberto.

destinationrange: Destino do intervalo de células copiadas, como uma string.

### Exemplo:

##### Em Basic

Copia dentro de um mesmo documento:

        oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
        ' Retorna uma string de intervalo: "$SheetY.$C$5:$J$14"

Copia de um arquivo 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 de gráfico mostrando os dados no intervalo de células especificado. O objeto de gráfico retornado pode ser posteriormente manipulado usando 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 usuário para o gráfico a ser criado. O nome deve ser único na mesma planilha.

nome_da_planilha: O nome da planilha onde o gráfico será inserido.

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

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

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

### Exemplo:

Os exemplos abaixo em Basic e Python criam um gráfico usando os dados contidos no intervalo "A1:B5" da planilha "Sheet1" e inserem o gráfico na planilha "Sheet2".

##### 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 do serviço Chart da biblioteca ScriptForge para aprender mais sobre como manipular objetos de gráfico. É possível modificar propriedades do gráfico como seu tipo, títulos dos eixos do gráfico e a posição do gráfico.

## CreatePivotTable

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

Um nome deve ser dado à tabela dinâmica. Se uma tabela dinâmica com o mesmo nome já existir na planilha, ela será substituída sem aviso prévio.

Este método retorna uma string contendo o intervalo onde a nova tabela dinâmica está localizada.

### 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: Nome definido pelo usuário para a nova tabela dinânmica.

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

célula de destino: A célula superior esquerda onde a nova tabela dinâmica será inserida. Se for especificado um intervalo, apenas a célula superior esquerda será considerada.

datafields: Pode ser uma única string ou uma matriz contendo strings que definem os nomes dos campos e as funções a serem aplicadas. Quando uma matriz é especificada, ela 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 dados em inglês. Quando todos os valores forem numéricos, a função Sum é a função padrão, caso contrário a função padrão é Count.

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

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

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

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

columntotals: Especifica se uma linha separada para os totais das colunas será adicionada à tabela dinâmica (Padrã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", "Estado", "Equipe", "2002", "2003", "2004"), _
            Array("Livros", "São Paulo", "João", 14788, 30222, 23490), _
            Array("Doces", "São Paulo", "João", 26388, 15641, 32849), _
            Array("Canetas", "São Paulo", "João", 16569, 32675, 25396), _
            Array("Livros", "São Paulo", "André", 21961, 21242, 29009), _
            Array("Doces", "São Paulo", "André", 26142, 22407, 32841))
        sTable = oDoc.SetArray("A1", vData)
        sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
            Array("2002", "2003;count", "2004;average"), _ ' Três campos de dados
            "Item", _ ' Um único campo de linha
            Array("State", "Team"), False) ' Dois campos de colunas

##### Em Python

        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Calc")
        vData = [["Item", "Estado", "Equipe", "2002", "2003", "2004"],
                 ["Livros", "São Paulo", "João", 14788, 30222, 23490],
                 ["Doces", "São Paulo", "João", 26388, 15641, 32849],
                 ["Canetas", "São Paulo", "João", 16569, 32675, 25396)],
                 ["Livros", "São Paulo", "André", 21961, 21242, 29009],
                 ["Doces", "São Paulo", "André", 26142, 22407, 32841]]
        sTable = doc.SetArray("A1", vData)
        sPivot = doc.CreatePivotTable("PT1", sTable, "H1",
                                      ["2002", "2003;count", "2004;average"],
                                      "Item",
                                      ["Estado", "Equipe"], False)

Para saber mais sobre Tabelas Dinâmicas no LibreOffice Calc, leia a página de ajuda Tabela dinâmica.

## DAvg, DCount, DMax, DMin and DSum

Aplique as funções Average, Count, Max, Min e Sum, respectivamente, a todas as células que contenham valores numéricos em um determinado intervalo, excluindo valores de linhas filtradas e ocultas e colunas ocultas, da mesma forma que para as funções da barra de status.

### 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 onde a função será aplicada, como uma string.

### Exemplo:

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

##### Em Basic

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

##### Em Python

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

Células no intervalo que contém texto são ignoradas por todas estas funções. Por exemplo, o método DCount não contará células com texto, apenas células com valores numéricos.

## DecorateFont

Defina propriedades simples e fáceis da fonte a ser usada em um intervalo de células.

As células afetadas podem ser identificadas por meio de uma fórmula de filtro e seu escopo.

Para aplicar decorações de fonte mais complexas, utilize as diversas 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 string, no qual as fontes das células devem ser reformatadas.

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

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

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

- B, U, I, S: Bold, Underline, Italic, Strikethrough.

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

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

            ' Modify the font size and apply bold and underline properties to the numeric cells.
            doc.DecorateFont("SheetX.A1:J30", fontsize := 15, decoration := "Bold,Underline", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

            # Modify the font size and apply bold and underline properties to the numeric cells.
            doc.DecorateFont('SheetX.A1:J30', fontsize = 15, decoration = 'Bold,Underline', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## DefineName

Define a new name in the worksheet, at global or sheet level. If the name exists already, it is overwritten without warning. After creation, the new name can be used in formulas. Returns True when successful.

Use a propriedade DefinedNames para examinar os intervalos nomeados existentes.

### Sintaxe:

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

### Parâmetros:

definedname: The name to be created or modified without warning. Note that homonyms may exist, but not in the same sheet and not at global level.

value: The new name as:

- a range reference as a string, often a single cell

- a scalar value as a number or a string

- a formula starting with the "=" sign

When Value is a range, the top-left cell is set as reference cell.

sheetname: The defined name scope is that of the specified sheet. The "~" shortcut is accepted.

### 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 arquivo PDF.

Este método retorna True se o arquivo de destino for salvo com sucesso.

Linhas ou colunas ocultas no intervalo não são exportadas para o arquivo de destino.

### Sintaxe:

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

### Parâmetros:

range: Um nome de planilha ou um intervalo a ser exportado, como uma string.

filename: Nome do arquivo a ser salvo. Deve ser expresso usando a notação definida em SF_FileSystem.FileNaming.

imagetype: Identifica o tipo do arquivo de destino. Valores possíveis são "jpeg", "pdf" (padrão) e "png".

overwrite: Se definido como True, o arquivo de destino pode ser sobrescrito (Padrão = False).

### Exemplo:

##### Em Basic

        ' Exporta a planilha toda como um arquivo PDF
        oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
        ' Exporta o intervalo como um arquivo PNG e sobrescreve o arquivo de destino, se existir
        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

Apply a given number format to a cell or a range of cells.

The impacted cells may be determined with a filter formula and its scope.

### Sintaxe:

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

### Parâmetros:

targetrange: The cell or the range as a string that should receive the format.

numberformat: The format to apply, as a string.

locale: A la-CO (language-COUNTRY) combination to indicate the used locale. The default locale is the output of the platform.FormatLocale property

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

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no intervalo.

### Exemplo:

##### Em Basic

            ' Format only the cells containing a numeric value.
            doc.FormatRange("SheetX.A1:J30", "0,00E+00", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### Em Python

            # Format only the cells containing a numeric value.
            doc.FormatRange('SheetX.A1:J30', '0,00E+00', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## Forms

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

- Um Array indexado em zero (ou uma tupla em Python) com os nomes de todos os formulários contidos em uma planilha especificada (se o argumento form não for informado)

- Uma instância do serviço SFDocuments.Form representando 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: Nome da planilha, como uma string, de onde o formulário será acessado.

form: Nome ou índice correspondente ao formulário armazenado na planilha especificada. Se este argumento não for fornecido, o método retornará uma lista com os nomes de todos os formulários disponíveis na planilha.

### Exemplo:

Nos exemplos a seguir a primeira linha obtém os nomes de todos os formulários armazenados em "Sheet1" e a segunda linha recupera o objeto Form referente ao formulário com o nome "Form_A" que está armazenado em "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 variando entre 1 e 1024 em sua letra correspondente (coluna 'A', 'B', ..., 'AMJ'). Se um dado número de coluna estiver fora do intervalo permitido, uma String de comprimento zero é retornada.

### Sintaxe:

svc.GetColumnName(columnnumber: int): str

### Parâmetros:

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

### Exemplo:

##### Em Basic

Apresenta uma caixa de mensagem com o nome da terceira coluna, que por padrão é "C".

        MsgBox oDoc.GetColumnName(3)

##### Em Python

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

O número máximo de colunas permitidas em uma planilha do Calc é 16384.

## GetFormula

Retorna a(s) fórmula(s) armazenada(s) em um intervalo de células como uma string única, ou como um vetor de strings com 1 ou 2 dimensões.

Os nomes das funções do Calc usadas nas fórmulas retornadas são expressas usando seus nomes 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: Intervalo de onde as fórmulas serão obtidas, como uma string.

### Exemplo:

##### Em Basic

O exemplo a seguir retorna um Array com dimensões 3 x 2 contendo as fórmulas no intervalo "A1:B3" (3 linhas e 2 colunas):

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

##### Em Python

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

## GetValue

Retorna os valores armazenados em um dado intervalo de células como um valor único, ou como um Array de 1 ou 2 dimensões. Todos os valores são do tipo Double ou String.

### Sintaxe:

svc.GetValue(range: str): any

### Parâmetros:

range: Intervalo de onde os valores serão obtidos, como uma string.

### Exemplo:

##### Em Basic

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

##### Em Python

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

Se uma célula contiver uma data, o número correspondente à data será retornado. Para converter valores numéricos para datas em scripts Basic, use a função interna do Basic CDate. Em scripts em Python use o método CDate do serviço Basic.

## ImportFromCSVFile

Importa o conteúdo de um arquivo de texto no formato CSV (comma separated values - valores separados por vírgulas) e insere os valores na célula de destino especificada.

Todos os conteúdos e formatos da área de destino são limpos antes de inserir os conteúdos do arquivo CSV. O tamanho da área modificada é definido unicamente pelos conteúdos do arquivo de entrada.

O método retorna uma string representando o intervalo de células modificado.

### Sintaxe:

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

### Parâmetros:

filename: Identifica o arquivo a ser aberto. Deve seguir a notação SF_FileSystem.FileNaming.

destinationcell: Célula de destino onde os dados importados serão inseridos, como uma String. Se este parâmetro especificar um intervalo, apenas a célula superior esquerda será considerada.

filteroptions: Argumentos para o filtro de importação CSV. O filtro padrão assume as seguintes premissas:

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

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

- O delimitador de Strings é o caractere aspas duplas (").

- Todas as linhas são incluídas.

- Strings entre aspas são formatadas como texto.

- Números especiais são detectados.

- Todas as colunas são consideradas como texto, exceto se forem reconhecidas como números válidos.

- A linguagem é Inglês/EUA, o que implica no uso do 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 filtro CSV consulte a página Opções do filtro CSV.

## ImportFromDatabase

Importa os conteúdos de uma tabela de banco de dados, consulta ou conjunto de resultados, ou seja, os resultados de um comando SQL SELECT, e insere os resultados na célula de destino.

Todos os conteúdos e formatos da área de destino são limpos antes de inserir os conteúdos importados. O tamanho da área modificada é definido unicamente pelos conteúdos da tabela ou consulta.

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

### Sintaxe:

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

### Parâmetros:

filename: Identifica o arquivo a ser aberto. Deve seguir a notação SF_FileSystem.FileNaming.

registrationname: Nome a ser usado para encontrar o banco de dados no registro de bancos de dados. Este argumento é ignorado se algum valor for especificado para filename.

destinationcell: Célula de destino onde os dados importados serão inseridos, como uma String. Se este parâmetro especificar um intervalo, apenas a célula superior esquerda será considerada.

sqlcommand: Uma tabela ou nome de consulta (sem usar aspas ou colchetes) ou uma declaração SQL SELECT na qual os nomes das tabelas e campos podem estar entre aspas ou colchetes para melhorar a legibilidade.

directsql: Se True, o comando SQL é enviado ao banco de dados diretamente sem análise prévia. O valor padrão é False. Este argumento é ignorado para tabelas. Para consultas, a opção aplicada é a definida quando 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

Esse método carrega todos os estilos pertencentes a uma ou mais famílias de estilos de um arquivo fechado para o documento real. O documento real deve ser um Calc ou um Writer.

São sempre importados juntos:

- ParagraphStyles e CharacterStyles

- NumberingStyles e ListStyles

Retorna True se os estilos foram importados com êxito.

### Sintaxe:

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

### Parâmetros:

Filename: o arquivo a partir do qual os estilos serão carregados na notação FileSystem. Presume-se que o arquivo seja do mesmo tipo de documento que o documento real.

Families: Uma das famílias de estilo presentes no documento real, como uma cadeia de caracteres que diferencia maiúsculas de minúsculas ou uma matriz dessas cadeias. Deixe esse argumento em branco para importar todas as famílias.

Overwrite: Quando True, os estilos reais podem ser substituídos. O padrão é 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

Insere uma nova planilha em branco antes de uma planilha existente ou ao final da lista de planilhas.

### Sintaxe:

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

### Parâmetros:

sheetname: Nome da nova planilha.

beforesheet: O nome (string) ou índice (numérico, iniciando em 1) da planilha antes da qual será inserida a nova planilha. Este argumento é opcional e o comportamento padrão é inserir a planilha na última posição.

### Exemplo:

O exemplo a seguir insere uma nova planilha vazia com o nome "SheetX" e coloca-a antes da planilha "SheetY":

##### Em Basic

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

##### Em Python

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

## Intersect

Retorna a cadeia de caracteres que representa a interseção entre os dois intervalos de entrada ou uma cadeia de caracteres de comprimento zero quando a interseçã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 a seguir cruza dois intervalos e retorna o intervalo comum entre ambos:

##### Em Basic

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

##### Em Python

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

## MoveRange

Move um intervalo de células de origem para um intervalo de destino. O método retorna uma string representando o intervalo modificado de células. A dimensão da área modificada é unicamente definida pelo tamanho da área de origem.

### Sintaxe:

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

### Parâmetros:

source: Intervalo de origem de células, como uma String.

destination: Célula de destino, como uma String. Se um intervalo for especificado, apenas a célula superior esquerda é considerada como o destino.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## MoveSheet

Move uma planilha existente e posiciona-a antes de uma planilha especificada ou ao final da lista de planilhas.

### Sintaxe:

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

### Parâmetros:

sheetname: Nome da planilha a ser movida. A planilha deve existir, caso contrário uma exceção é lançada.

beforesheet: O nome (string) ou índice (numérico, iniciando em 1) da planilha antes da qual a planilha original será posicionada. Este argumento é opcional e o comportamento padrão é mover a planilha para a última posição.

### Exemplo:

O exemplo abaixo move a planilha existente "SheetX" e posiciona-a antes da planilha "SheetY":

##### Em Basic

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

##### Em Python

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

## Offset

Retorna um novo intervalo (como uma String) deslocado por um certo número de linhas e colunas a partir de um dado intervalo.

Este método tem o mesmo comportamento que a função Calc Desloc.

### Sintaxe:

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

### Parâmetros:

reference: O intervalo, como uma String, que o método considerará como referência para aplicar o deslocamento.

rows: Número de linhas pelo qual o intervalo original será deslocado para cima (valor negativo) ou para baixo (valor positivo). Use 0 (padrão) para permanecer na mesma linha.

columns: Número de colunas pelo qual o intervalo original será deslocado para a esquerda (valor negativo) ou para a direita (valor positivo). Use 0 (padrão) para permanecer na mesma coluna.

height: Altura vertical para uma área que inicia na nova posição do intervalo. Este argumento pode ser omitido se nenhum redimensionamento vertical for necessário.

width: Largura horizontal para uma área que se inicia na nova posição do intervalo. Este argumento pode ser omitido se nenhum redimensionamento horizontal for necessário.

Os argumentos rows e columns não devem resultar em linhas ou colunas iniciais menores ou iguais a zero.

Os argumentos height e width não devem resultar em uma contagem nula ou negativa de linhas ou colunas.

### Exemplo:

##### Em Basic

        oDoc.Offset("A1", 2, 2)
        'SheetX.$C$3 (A1 é movida duas linhas e duas colunas para baixo)
        oDoc.Offset("A1", 2, 2, 5, 6)
        'SheetX.$C$3:$H$7 (A1 é deslocada em duas linhas e duas colunas com 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 usada para selecionar um intervalo no documento e retorna uma string contendo o intervalo selecionado.

Este método abre a mesma caixa de diálogo usada pelo LibreOffice quando o botão Encolher é pressionado. Por exemplo, a caixa de diálogo Ferramentas - Atingir meta tem um botão Encolher à direita do campo Célula de 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, como uma string.

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

singlecell: Quando True (padrão), permite apenas a seleção de uma única célula. Quando False permite a seleção de intervalo.

closeafterselect: Quando True (padrão), a caixa de diálogo é fechada imediatamente após a seleção ser feita. Quando False, o usuário pode alterar a seleção quantas vezes forem necessárias e então fechar a caixa de diálogo manualmente.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## Printf

Retorna a string de entrada após substituir seus caracteres de token por seus valores em um determinado intervalo.

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

Este método pode ser usado para extrair rapidamente partes específicas de um nome de intervalo, como o nome da planilha ou a primeira coluna e linha da célula, e usá-los para compor um novo endereço de intervalo.

### Sintaxe:

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

### Parâmetros:

inputstr: A string contendo os tokens que serão substituídos pelos valores correspondentes no range.

range: um nome de intervalo RangeName do qual os valores são extraídos. Se contiver nomes de planilhas, a planilha deve existir.

tokencharacter: Caractere utilizado para identificar os tokens. O caractere padrão de token é "%". Os seguintes tokens são aceitos:

- %S - o nome da planilha contendo o intervalo, incluindo aspas simples quando necessário.

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

- %C1 - o número da coluna da célula superior esquerda do intervalo.

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

- %C2 - o número da coluna da célula inferior direita do intervalo.

### Exemplo:

##### Em Basic

O exemplo abaixo extrai cada elemento do nome de intervalo RangeName definido em sRange e os utiliza 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 SetFormula para criar fórmulas sobre múltiplas células. Por exemplo, considere uma tabela com valores numéricos no intervalo "A1:E10" a partir da qual as fórmulas devem ser criadas para somar os valores em cada linha e colocar os resultados no intervalo "F1:F10":

        Dim sFormula as String, sRange as String
        sRange = "A1:E10"
        ' Observe o uso 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 planilha especificada para a impressora padrão ou para a impressora definida pelo método SetPrinter do serviço Document.

Retorna True se a impressão da planilha foi bem-sucedida.

### Sintaxe:

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

### Parâmetros:

sheetname: Planilha a ser impressa. Por padrão considera-se a planilha ativa.

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

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

### 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 for duplicada é feita com base em um subconjunto de colunas no intervalo.

Este método retorna uma string contendo o intervalo resultante.

A remoção de linhas duplicadas ocorre a partir da primeira linha no intervalo, movendo-se para baixo, o que significa que, se duas ou mais linhas forem duplicadas, apenas a primeira será mantida.

### Sintaxe:

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

### Parâmetros:

intervalo: O intervalo do qual as duplicatas serão removidas, como uma string.

colunas: Uma array contendo números de coluna indicando quais colunas serão consideradas para determinar se uma linha é duplicada ou não. Se este argumento for deixado em branco, apenas a primeira coluna será usada. Os itens nesta matriz devem estar no intervalo 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 entre strings diferenciam maiúsculas de minúsculas (padrão = False).

mode: especifica como tratar linhas duplicadas. Se mode = "CLEAR" então as linhas duplicadas são retiradas da planilha deixando as células em branco. Se mode = "COMPACT" as linhas duplicadas são retiradas e as linhas vazias são compactadas (padrão = "COMPACT").

### Exemplo:

##### Em Basic

        ' Exclui as linhas duplicadas onde os valores da coluna A são duplicados
        ' Note que todos os argumentos opcionais utilizam os valores padrão
        oDoc.RemoveDuplicates("A1:B10")
        ' Remove as linhas duplicadas considerando que a primeira linha é um cabeçalho
        ' As colunas A e B são usadas para determinar se uma linha é duplicada
        ' As células contendo valores duplicados são deixadas 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 do documento uma planilha existente.

### Sintaxe:

svc.RemoveSheet(sheetname: str): bool

### Parâmetros:

sheetname: Nome da planilha a ser removida.

### Exemplo:

##### Em Basic

        oDoc.RemoveSheet("SheetY")

##### Em Python

        myDoc.RemoveSheet("SheetY")

## RenameSheet

Renomeia a planilha especificada e retorna True se bem-sucedido.

### Sintaxe:

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

### Parâmetros:

sheetname: Nome da planilha a ser renomeada.

newname: Novo nome da planilha. O nome não pode existir previamente.

### Exemplo:

Este exemplo renomeia a planilha ativa para "SheetY":

##### Em Basic

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

##### Em Python

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

## SetArray

Armazena o valor dado iniciando em uma célula de destino especificada. A área atualizada se expande a partir da célula de destino ou a partir do canto superior esquerdo de um intervalo especificado para acomodar o tamanho do parâmetro de entrada value. Vetores são sempre expandidos verticalmente.

Este método retorna uma String representando a área modificada como um intervalo de células.

### Sintaxe:

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

### Parâmetros:

targetcell: Célula ou intervalo, como uma String, a partir da qual o valor especificado será armazenado.

value : Um escalar, um vetor ou um Array (em Python: listas ou tuplas de uma ou duas dimensões) com os novos valores a serem armazenados na célula de destino, ou a partir do canto superior esquerdo do intervalo se o parâmetro targetcell for um intervalo. Os novos valores devem ser Strings, valores numéricos ou datas. Outros tipos farão com que as células de destino correspondentes fiquem vazias.

### Exemplo:

##### Em Basic

O exemplo a seguir usa a função DimArray para criar um Array e armazená-lo 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 usa o método RangeInit do serviço ScriptForge Array para criar uma array com valores que são, em seguida, armazenados da célula "A1" para baixo.

        'Preenche 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 armazenar todos os conteúdos de um Array em uma planilha, use o método SetArray. Para armazenar os conteúdos de um Array somente dentro dos limites do intervalo de destino, use o método SetValue.

## SetCellStyle

Aplica o estilo de célula especificado para o intervalo de destino. Todo o intervalo é atualizado e o restante da planilha é deixada sem modificações. Se o estilo de célula não existir, um erro é lançado.

Este método retorna uma String representando 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: Intervalo ao qual o estilo será aplicado, como uma string.

style: Nome do estilo de célula a ser aplicado.

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

filterscope: Determina como a filterformula é expandida para o intervalo especificado. Este argumento é obrigatório se for especificada uma filterformula. São aceitos os seguintes valores:

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

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

- "COLUNA": A fórmula especificada no argumento filterformula é aplicada uma vez para cada coluna no 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 ter exemplos de como utilizar os argumentos filterformula e filterscope.

## SetFormula

Insere um dado (Array de) fórmula(s) em um intervalo especificado. O tamanho da área modificada é igual ao tamanho do intervalo.

Este método retorna uma String representando a área modificada como um intervalo de células.

### Sintaxe:

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

### Parâmetros:

targetrange: Intervalo ao qual as fórmulas serão inseridas, como uma String.

formula: Uma String, um vetor ou um Array de Strings com as novas fórmulas para cada célula no intervalo de destino.

Todo o intervalo é atualizado e o restante da planilha é deixada sem modificações.

Se a fórmula for uma única String, então esta fórmula única é colada ao longo de todo o intervalo com ajustes das referências relativas.

Se o tamanho do argumento formula for menor que o tamanho do intervalo targetrange, então o restante das células são deixadas em branco.

Se o tamanho do parâmetro formula for maior que o tamanho do intervalo targetrange, então as fórmulas serão apenas parcialmente copiadas até que o intervalo targetrange seja preenchido.

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

As funções do Calc usadas no argumento formula devem ser expressas usando seus nomes 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.

### Exemplo:

##### Em Basic

        oDoc.SetFormula("A1", "=A2")
        'Vetor horizontal, parcialmente vazio
        oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
        '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 especificado em um intervalo. O tamanho da área modificada é igual ao tamanho do intervalo de destino.

Este método retorna uma String representando a área modificada como um intervalo de células.

### Sintaxe:

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

### Parâmetros:

targetrange: Intervalo onde os valores serão armazenados, como uma string.

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

Todo o intervalo é atualizado e o restante da planilha é deixada sem modificações. Se o tamanho do parâmetro value for menor que o tamanho do intervalo targetrange, então as células restantes serão esvaziadas.

Se o tamanho do parâmetro value for maior que o tamanho do intervalo targetrange, então value será apenas parcialmente copiado até que o intervalo targetrange seja preenchido.

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

### Exemplo:

##### Em Basic

        oDoc.SetValue("A1", 2)
        'Abaixo o parâmetro Value é menor que o intervalo TargetRange (células restantes são esvaziadas)
        oDoc.SetValue("A1:F1", Array(1, 2, 3))
        'Abaixo os parâmetros 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 você quiser preencher uma linha única com valores você pode usar a função Offset. No exemplo abaixo considere que arrData é um Array de uma dimensão:

        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

Move 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 abranger a largura do intervalo especificado ou abranger todas as colunas na linha.

Este método retorna uma string que representa o novo local do intervalo inicial.

Se o intervalo alterado exceder as bordas da planilha, nada acontecerá.

### Sintaxe:

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

### Parâmetros:

intervalo: o intervalo acima do qual as linhas serão inseridas, como uma string.

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

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

### Exemplo:

##### Em Basic

        'Move o intervalo "A3:D3" uma linha para baixo; afeta apenas as colunas A a D
        oDoc.ShiftDown("A3:D3")
        ' A linha inserida abrange todas as colunas da planilha
        oDoc.ShiftDown("A3:D3", WholeRow := True)
        ' Move o intervalo "A3:D3" para baixo em cinco linhas
        oDoc.ShiftDown("A3:D3", Rows := 5)
        ' Move o intervalo "A3:D10" para baixo em duas linhas 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

Exclui as colunas mais à esquerda de um determinado intervalo e move 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 excluídas podem abranger a altura do intervalo especificado ou abranger todas as linhas na coluna.

Este método retorna uma string que representa a localização da parte restante do intervalo inicial. Se todas as células do intervalo original foram excluídas, retorna uma string vazia.

### Sintaxe:

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

### Parâmetros:

range: o intervalo do qual as linhas serão excluidas, como uma string.

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

columns: O número de colunas a serem excluídas do intervalo range especificado. O valor padrão é a largura do intervalo range original, que também é o valor máximo deste argumento.

### Exemplo:

##### Em Basic

        'Exclui o intervalo "B3:B6"; move todas as células da esquerda para a direita
        oDoc.ShiftLeft("B3:B6")
        'Exclui a primeira coluna no intervalo "A3:D6"
        oDoc.ShiftLeft("A3:D6", Columns := 1)
        'As colunas excluídas (A a D) abrangem todas as linhas da planilha
        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

Exclui as linhas mais em cima de um determinado intervalo e move para cima todas as células embaixo do intervalo afetado. A seleção atual não é afetada.

Dependendo do valor do argumento wholerow, as linhas excluídas podem abranger a largura do intervalo especificado ou abranger todas as colunas na linha.

Este método retorna uma string que representa a localização da parte restante do intervalo inicial. Se todas as células do intervalo original foram excluídas, retorna uma string vazia.

### Sintaxe:

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

### Parâmetros:

range: o intervalo do qual as linhas serão excluídas, como uma string.

wholerow: Se definido como False (padrão), a largura das linhas excluídas será igual à largura do intervalo range especificado. Caso contrário, a linha excluída abrangerá todas as colunas da planilha.

rows: O número de linhas a serem excluídas do intervalo range especificado. O valor padrão é a altura do intervalo range original, que também é o valor máximo deste argumento.

### Exemplo:

##### Em Basic

        'Exclui o intervalo "A3:D3"; move todas as células abaixo dele uma linha para cima
        oDoc.ShiftUp("A3:D3")
        'Exclui a primeira lnha no intervalo "A3:D6"
        oDoc.ShiftUp("A3:D6", Rows := 1)
        ' As linhas excluídas abrangem todas as colunas da planilha
        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

Move 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 abranger a altura do intervalo especificado ou abranger todas as linhas na coluna.

Este método retorna uma string que representa o novo local do intervalo inicial.

Se o intervalo alterado exceder as bordas da planilha, nada acontecerá.

### Sintaxe:

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

### Parâmetros:

range: o intervalo que terá colunas vazias inseridas à sua esquerda, como uma string.

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

columns: o número de colunas a inserir. O valor padrão é a largura do intervalo range original.

### Exemplo:

##### Em Basic

        ' Move o intervalo "A3:A6" para a direita em uma coluna; afeta apenas as linhas 3 a 6
        oDoc.ShiftRight("A3:A6")
        ' Move o intervalo "A3: A6" para a direita em cinco colunas
        oDoc.ShiftRight("A3:A6", Columns := 5)
        ' A coluna inserida abrange todas as linhas da planilha
        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

Ordena o intervalo dado com relação a qualquer número de colunas e linhas. A ordem pode variar por coluna/linha. Se o número de chaves de ordenação for maior que 3, então o intervalo é ordenado várias vezes, em grupos de 3 chaves, começando pela última chave. Retorna uma string representando o intervalo de células modificado. O tamanho da área modificada é completamente 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: Intervalo a ser ordenado, como uma String.

sortkeys: Um escalar (se for apenas 1 coluna/linha) ou um array de números de coluna/linha iniciando em 1.

sortorder: Um escalar ou um Array de Strings contendo os valores "ASC" (ascendente) ou "DESC" (descendente). Cada item deste parâmetro é pareado com o item correspondente em sortkeys. Se o Array sortorder for menor que sortkeys, o restante das chaves serão ordenadas de maneira ascendente.

destinationcell: Célula de destino para o intervalo ordenado de células, como uma String. Se um intervalo for dado, apenas o canto superior esquerdo será considerado. Por padrão, o intervalo de origem é sobrescrito.

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

casesensitive: Apenas para comparação de strings. Padrão = 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

        'Ordena o intervalo baseado nas colunas A (acendente) e C (descendente)
        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 em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.

Tópicos relacionados

Serviço SFDocuments.Chart

Serviço SFDocuments.Document

Serviço ScriptForge.UI

♥ Doe para nosso projeto! ♥