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.

The SFDocuments.Calc service is a subclass of the SFDocuments.Document service. All methods and properties defined for the Document service can also be accessed using a Calc service instance.

The Calc service is focused on:

note

This help page describes methods and properties that are applicable only to Calc documents.


Invocação do serviço

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 usando 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.

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

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.

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 em um intervalo (padrão = planilha ativa). Aspas em volta do nome da planilha e o caractere $ são permitidos, porém ignorados.

tip

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

Return type

Descrição

CurrentSelection

Não

Nenhum

String ou array de strings

The single selected range as a string or the list of selected ranges as an array.

FirstCell

Yes

SheetName or RangeName as String

String

Returns the first used cell in a given range or sheet.

FirstColumn

Yes

SheetName or RangeName as String

Long

Returns the leftmost column number in a given range or sheet.

FirstRow

Yes

SheetName or RangeName as String

Long

Returns the topmost row number in a given range or sheet.

Height

Sim

RangeName como uma String

Long

The number of rows (>= 1) in the given range.

LastCell

Sim

SheetName or RangeName as String

String

Returns the last used cell in a given range or sheet.

LastColumn

Sim

SheetName or RangeName as String

Long

The last used column in a given range or sheet.

LastRow

Sim

SheetName or RangeName as String

Long

The last used row in a given range or sheet.

Range

Sim

RangeName como uma String

Object

A range reference that can be used as argument of methods like CopyToRange.

Region

Sim

RangeName como uma String

String

Returns the address of the smallest area that contains the specified range so that the area is surrounded by empty cells or sheet edges. This is equivalent to applying the shortcut to the given range.

Sheet

Sim

SheetName como uma String

Object

A sheet reference that can be used as argument of methods like CopySheet.

Sheets

Sim

Nenhum

Array de strings

The list with the names of all existing sheets.

Width

Sim

RangeName como uma String

Long

The number of columns (>= 1) in the given range.

XCellRange

Sim

RangeName como uma String

Object

A com.sun.star.Table.XCellRange UNO object.

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

A com.sun.star.sheet.XSpreadsheet UNO object.


tip

Visit LibreOffice API Documentation's website to learn more about XCellRange, XSheetCellCursor and XSpreadsheet UNO objects.


Métodos

Lista de Métodos no Serviço Calc

A1Style
Activate
Charts
ClearAll
ClearFormats
ClearValues
CopySheet
CopySheetFromFile
CopyToCell
CopyToRange
CreateChart
DAvg
DCount
DMax

DMin
DSum
Forms
GetColumnName
GetFormula
GetValue
ImportFromCSVFile
ImportFromDatabase
InsertSheet
MoveRange
MoveSheet
Offset
OpenRangeSelector

PrintOut
Printf
RemoveSheet
RenameSheet
SetArray
SetValue
SetCellStyle
SetFormula
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
  
tip

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

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.


Charts

Returns either the list with the names of all chart objects in a given sheet or a single Chart service instance.

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.

tip

Use the Navigator sidebar to check the names assigned to charts under the OLE objects category.


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.

Sintaxe:

svc.ClearAll(range: str)

Parâmetros:

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

Exemplo:

Em Basic

      oDoc.ClearAll("SheetX.A1:F10")
  
Em Python

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

ClearFormats

Limpa os formatos e estilos de um dado intervalo.

Sintaxe:

svc.ClearFormats(range: str)

Parâmetros:

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

Exemplo:

Em Basic

      oDoc.ClearFormats("SheetX.*")
  
Em Python

    myDoc.ClearFormats("SheetX.*")
  

ClearValues

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

Sintaxe:

svc.ClearValues(range: str)

Parâmetros:

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

Exemplo:

Em Basic

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

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

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

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

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.

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:

chartname: O nome definido pelo usuário que será atribuído ao gráfico a ser criado. O nome deve ser único na mesma planilha.

sheetname: Nome da planilha onde o gráfico será inserido.

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

columnheader: Quando for True, a linha mais ao topo do intervalo será usada para obter os rótulos do eixo de categoria ou legenda (Padrão = False).

rowheader: Quando for True, a coluna mais à esquerda do intervalo será usada para obter os rótulos para o eixo de categoria ou da 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"
  
tip

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.


DAvg, DCount, DMax, DMin and DSum

Aplica as funções MÉDIA, CONT, MÁXIMO, MÍNIMO e SOMA, respectivamente, para todas as células contendo valores numéricos em um intervalo especificado.

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

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.


Forms

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

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: Número da coluna como um valor inteiro no intervalo 1 ... 1024.

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

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


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.

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

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:

Exemplo:

Em Basic

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

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

Para saber mais sobre as opções do Filtro CSV, leia a página Wiki Filter Options.


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

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

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

Opens a non-modal dialog that can be used to select a range in the document and returns a string containing the selected range.

note

This method opens the same dialog that is used by LibreOffice when the Shrink button is pressed. For example, the Tools - Goal Seek dialog has a Shrink button to the right of the Formula cell field.


This method does not change the current selection.

Sintaxe:

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

Parâmetros:

title: The title of the dialog, as a string.

selection: An optional range that is initially selected when the dialog is displayed.

singlecell: When True (default) only single-cell selection is allowed. When False range selection is allowed.

closeafterselect: When True (default) the dialog is closed immediately after the selection is made. When False the user can change the selection as many times as needed and then manually close the dialog.

Exemplo:

Em Basic

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

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

Printf

Returns the input string after substituting its token characters by their values in a given range.

This method does not change the current selection.

tip

This method can be used to quickly extract specific parts of a range name, such as the sheet name or first cell column and row, and use them to compose a new range address.


Sintaxe:

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

Parâmetros:

inputstr: The string containing the tokens that will be replaced by the corresponding values in range.

range: A RangeName from which values will be extracted. If it contains a sheet name, the sheet must exist.

tokencharacter: Character used to identify tokens. By default "%" is the token character. The following tokens are accepted:

Exemplo:

Em Basic

The example below extracts each element of the RangeName defined in sRange and uses them to compose a message.


    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)
  

The Printf method can be combined with SetFormula to create formulas over multiple cells. For instance, consider a table with numeric values in the range "A1:E10" from which formulas are to be created to sum the values in each row and place the results in the range "F1:F10":


    Dim sFormula as String, sRange as String
    sRange = "A1:E10"
    ' Note the use of the "$" character
    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

This method sends the contents of the given sheet to the default printer or to the printer defined by the SetPrinter method of the Document service.

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: The number of copies. Default is 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'):
        # ...
  

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 um Array com valores que serão armazenados a partir da célula "A1" no sentido 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)))
  
tip

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.


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)
  

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): str

Parâmetros:

targetrange: Intervalo ao qual o estilo será aplicado, como uma string.

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

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

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.

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

ShiftDown

Moves a given range of cells downwards by inserting empty rows. The current selection is not affected.

Depending on the value of the wholerows argument the inserted rows can either span the width of the specified range or span all columns in the row.

This method returns a string representing the new location of the initial range.

note

If the shifted range exceeds the sheet edges, then nothing happens.


Sintaxe:

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

Parâmetros:

range: The range above which rows will be inserted, as a string.

wholerow: If set to False (default), then the width of the inserted rows will be the same as the width of the specified range. Otherwise, the inserted row will span all columns in the sheet.

rows: The number of rows to be inserted. The default value is the height of the original range. The number of rows must be a positive number.

Exemplo:

Em Basic

    ' Moves the range "A3:D3" down by one row; affects only columns A to D
    oDoc.ShiftDown("A3:D3")
    ' The inserted row spans all columns in the sheet
    oDoc.ShiftDown("A3:D3", WholeRow := True)
    ' Moves the range "A3:D3" down by five rows
    oDoc.ShiftDown("A3:D3", Rows := 5)
    ' Moves the range "A3:D10" down by two rows and shows the new location of the original range
    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

Deletes the leftmost columns of a given range and moves to the left all cells to the right of the affected range. The current selection is not affected.

Depending on the value of the wholecolumns argument the deleted columns can either span the height of the specified range or span all rows in the column.

This method returns a string representing the location of the remaining portion of the initial range. If all cells in the original range have been deleted, then an empty string is returned.

Sintaxe:

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

Parâmetros:

range: The range from which cells will be deleted, as a string.

wholecolumn: If set to False (default), then the height of the deleted columns will be the same as the height of the specified range. Otherwise, the deleted columns will span all rows in the sheet.

columns: The number of columns to be deleted from the specified range. The default value is the width of the original range, which is also the maximum value of this argument.

Exemplo:

Em Basic

    ' Deletes the range "B3:B6"; moves left all cells to the right
    oDoc.ShiftLeft("B3:B6")
    ' Deletes the first column in the range "A3:D6"
    oDoc.ShiftLeft("A3:D6", Columns := 1)
    ' The deleted columns (A to D) spans all rows in the sheet
    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

Deletes the topmost rows of a given range and moves upwards all cells below the affected range. The current selection is not affected.

Depending on the value of the wholerows argument the deleted rows can either span the width of the specified range or span all columns in the row.

This method returns a string representing the location of the remaining portion of the initial range. If all cells in the original range have been deleted, then an empty string is returned.

Sintaxe:

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

Parâmetros:

range: The range from which cells will be deleted, as a string.

wholerow: If set to False (default), then the width of the deleted rows will be the same as the width of the specified range. Otherwise, the deleted row will span all columns in the sheet.

rows: The number of rows to be deleted from the specified range. The default value is the height of the original range, which is also the maximum value of this argument.

Exemplo:

Em Basic

    ' Deletes the range "A3:D3"; moves all cells below it by one row up
    oDoc.ShiftUp("A3:D3")
    ' Deletes the first row in the range "A3:D6"
    oDoc.ShiftUp("A3:D6", Rows := 1)
    ' The deleted rows spans all columns in the sheet
    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

Moves a given range of cells to the right by inserting empty columns. The current selection is not affected.

Depending on the value of the wholecolumns argument the inserted columns can either span the height of the specified range or span all rows in the column.

This method returns a string representing the new location of the initial range.

note

If the shifted range exceeds the sheet edges, then nothing happens.


Sintaxe:

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

Parâmetros:

range: The range which will have empty columns inserted to its left, as a string.

wholecolumn: If set to False (default), then the height of the inserted columns will be the same as the height of the specified range. Otherwise, the inserted columns will span all rows in the sheet.

columns: The number of columns to be inserted. The default value is the width of the original range.

Exemplo:

Em Basic

    ' Moves the range "A3:A6" right by one column; affects only rows 3 to 6
    oDoc.ShiftRight("A3:A6")
    ' Moves the range "A3:A6" right by five columns
    oDoc.ShiftRight("A3:A6", Columns := 5)
    ' The inserted column spans all rows in the sheet
    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 baseado em até 3 colunas/linhas. A ordem da ordenação pode variar para cada coluna. Retorna uma String representando o intervalo de células modificadas. O tamanho da área modificada é unicamente 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 contendo os identificadores de linhas/colunas iniciando em 1. A quantidade máxima de chaves de ordenação é 3.

sortorder: Um escalar ou um Array de Strings contendo os valores "ASC" (ascendente), "DESC" (descendente) or "" (que usa o valor padrão ascendente). 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: Se True, as colunas são ordenadas da esquerda para a direita. Padrão = False (linhas são ordenadas de baixo para cima).

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

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.