Serviço SFDocuments.Calc

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

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

O serviço Calc centra-se em:

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

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

• Copiar e importar grandes quantidades de dados

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

Chamada de serviço

Antes de utilizar o serviço Calc, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

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

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

    Set oDoc = CreateScriptService("Calc")
  

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

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

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

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

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

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

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

Também é possível invocar o serviço Calc utilizando o documento referenciado por ThisComponent. Isto é especialmente útil ao executar uma macro a partir do IDE do Basic.

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

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

    Set oDoc = oDoc.Dispose()
  

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

    myDoc = CreateScriptService("Calc")
  

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

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

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

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

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

Definições

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

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

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

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

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

    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)
  

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

SheetName

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

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

RangeName

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

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

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

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

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

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

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

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

Propriedades

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

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

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

Métodos

A1Style

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

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

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

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

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

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

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

    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
  

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

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

Activate

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

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

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

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

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

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

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

Charts

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

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

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

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

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

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

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

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

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

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

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

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

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

ClearAll

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

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

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

range: The range to be cleared, as a string.

filterformula: A Calc formula that shall be applied to the given range to determine which cells will be affected. The specified formula must return True or False. If this argument is not specified, then all cells in the range are affected.

filterscope: Determines how filterformula is expanded to the given range. This argument is mandatory if a filterformula is specified. The following values are accepted:

• "CELL": The formula specified in the filterformula argument is expanded once for each cell in range.

• "ROW": The formula specified in the filterformula argument is expanded once for each row in range.

• "COLUMN": The formula specified in the filterformula argument is expanded once for each column in range.

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

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

ClearFormats

Clears the formats and styles in the given range.

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

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

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

      oDoc.ClearFormats("SheetX.*")
  

    myDoc.ClearFormats("SheetX.*")
  

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

ClearValues

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

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

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

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

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

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

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

CompactLeft

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

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

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

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

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

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

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

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

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

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

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

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

CompactUp

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

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

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

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

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

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

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

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

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

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

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

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

CopySheet

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

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

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

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

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

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

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

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

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

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

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

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

CopySheetFromFile

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

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

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

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

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

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

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

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

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

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

CopyToCell

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

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

O intervalo de origem pode pertencer a outro documento aberto.

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

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

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

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

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

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

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

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

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

CopyToRange

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

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

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

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

O intervalo de origem pode pertencer a outro documento aberto.

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

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

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

Copiar dentro do mesmo documento:

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

Copiar de um ficheiro para outro:

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

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

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

CreateChart

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

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

chartname: The user-defined name of the chart to be created. The name must be unique in the same sheet.

sheetname: The name of the sheet where the chart will be placed.

range: The range to be used as the data source for the chart. The range may refer to any sheet of the Calc document.

columnheader: When True, the topmost row of the range is used as labels for the category axis or the legend (Default = False).

rowheader: When True, the leftmost column of the range is used as labels for the category axis or the legend. (Default = False).

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

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

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

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

CreatePivotTable

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

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

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

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

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

sourcerange: The range containing the raw data, as a string. It is assumed that the first row contains the field names that are used by the pivot table.

targetcell: The top-left cell where the new pivot table will be placed. If a range is specified, only its top-left cell is considered.

datafields: It can be either a single string or an array containing strings that define field names and functions to be applied. When an array is specified, it must follow the syntax Array("FieldName[;Function]", ...).

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

rowfields: A single string or an array with the field names that will be used as the pivot table rows.

columnfields: A single string or an array with the field names that will be used as the pivot table columns.

filterbutton: Determines whether a filter button will be displayed above the pivot table (Default = True).

rowtotals: Specifies if a separate column for row totals will be added to the pivot table (Default = True).

columntotals Specifies if a separate row for column totals will be added to the pivot table (Default = True)

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

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

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

DAvg, DCount, DMax, DMin and DSum

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

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

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

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

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

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

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

ExportRangeToFile

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

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

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

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

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

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

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

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

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

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

Forms

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

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

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

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

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

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

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

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

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

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

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

GetColumnName

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

svc.GetColumnName(columnnumber: int): str

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

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

    MsgBox oDoc.GetColumnName(3)
  

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

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

GetFormula

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

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

svc.GetFormula(range: str): any

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

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

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

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

GetValue

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

svc.GetValue(range: str): any

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

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

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

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

ImportFromCSVFile

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

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

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

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

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

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

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

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

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

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

• Todas as linhas estão incluídas.

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

• São detetados números especiais.

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

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

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

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

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

ImportFromDatabase

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

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

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

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

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

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

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

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

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

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

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

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

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

InsertSheet

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

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

sheetname: O nome da nova folha.

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

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

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

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

Intersect

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

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

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

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

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

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

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

MoveRange

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

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

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

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

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

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

MoveSheet

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

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

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

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

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

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

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

Offset

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

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

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

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

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

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

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

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

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

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

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

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

OpenRangeSelector

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

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

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

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

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

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

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

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

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

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

Printf

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PrintOut

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

Retorna True se a folha tiver sido impressa com sucesso.

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

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

pages: As páginas a imprimir, indicadas como uma sequência de caracteres, tal como na interface do utilizador. Exemplo: "1-4;10;15-18". O valor predefinido é todas as páginas.

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

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

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

RemoveDuplicates

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

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

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

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

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

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

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

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

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

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

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

RemoveSheet

Remove uma folha existente do documento.

svc.RemoveSheet(sheetname: str): bool

sheetname: O nome da folha a remover.

    oDoc.RemoveSheet("SheetY")
  

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

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

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

sheetname: O nome da folha a renomear.

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

Este exemplo renomeia a folha ativa para «SheetY»:

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

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

SetArray

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

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

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

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

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

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

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

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

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

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

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

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

SetCellStyle

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

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

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

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

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

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

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

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

SetFormula

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

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

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

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

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

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

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

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

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

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

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

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

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

SetValue

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

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

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

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

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

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

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

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

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

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

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

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

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

ShiftDown

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

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

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

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

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

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

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

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

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

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

ShiftLeft

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

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

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

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

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

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

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

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

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

ShiftUp

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

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

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

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

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

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

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

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

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

ShiftRight

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

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

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

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

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

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

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

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

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

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

SortRange

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

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

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

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

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

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

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

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

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

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

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

Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.