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

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

O serviço Calc centra-se em:

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

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

• Copiar e importar grandes quantidades de dados

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

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

Chamada de serviço

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

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

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

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

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:

• Within a specific Calc instance, sheets and ranges are given as strings such as "Sheet1" and "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 LibreOfficeDev 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.

AlignRange

Alinhar horizontalmente ou verticalmente um intervalo de células.

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

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

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

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

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

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

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

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

BorderRange

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

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

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

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

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

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

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

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

• H, V: linhas internas horizontais e verticais.

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

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

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

Charts

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

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

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

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: O intervalo a ser apagado, na forma de uma cadeia de caracteres.

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

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

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

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

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

    ' 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

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

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

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.

ColorizeRange

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

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

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

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

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

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

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

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

CompactLeft

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DecorateFont

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

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

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

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

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

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

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

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

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

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

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

DefineName

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

Utilize a propriedade DefinedNames para examinar os intervalos nomeados existentes.

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

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

value: O novo nome é:

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

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

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

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

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

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

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

ExportRangeToFile

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

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

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

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)
  

FormatRange

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

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

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

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

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

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

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

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

Forms

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

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

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

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 LibreOfficeDev 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: 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.

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

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

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

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.

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

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

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

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

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.

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

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

SortRange

Sort the given range on any number of columns/rows. The sorting order may vary by column/row. If the number of sort keys is > 3 then the range is sorted several times, by groups of 3 keys, starting from the last key. It returns a string representing the modified range of cells. The size of the modified area is fully determined by the size of the source area.

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

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

sortkeys: A scalar (if 1 column/row) or an array of column/row numbers starting from 1.

sortorder: A scalar or an array of strings containing the values "ASC" (ascending), "DESC" (descending). Each item is paired with the corresponding item in sortkeys. If the sortorder array is shorter than sortkeys, the remaining keys are sorted in ascending order.

destinationcell: The destination cell of the sorted range of cells, as a string. If a range is given, only its top-left cell is considered. By default the source Range is overwritten.

containsheader: When True, the first row/column is not sorted.

casesensitive: Only for string comparisons. Default = False

sortcolumns: When True, the columns are sorted from left to right. Default = False: rows are sorted from top to bottom.

    'Sort range based on columns A (ascending) and C (descending)
    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.