Sumário
Índice 🔎︎

# Serviço SFDocuments.Chart

O serviço Chart fornece um conjunto de propriedades e métodos para manipular gráficos em documentos Calc. Com este serviço é possível:

- Acessar objetos de gráficos em documentos Calc e manipular suas propriedades.

- Criar e inserir novos gráficos em um documento Calc.

- Exportar gráficos como arquivos de imagem.

## Nomes dos gráficos

Gráficos podem ter dois nomes distintos:

- Um nome interno dado pelo LibreOffice assim que o objeto de gráfico é criado (geralmente "Object 1", "Object 2" e assim por diante).

- Um nome definido pelo usuário, que pode ser atribuído ao clicar com o botão direito no gráfico e escolhendo a opção Nome no menu de contexto.

O serviço Chart usa primeiro o nome definido pelo usuário para acessar objetos de gráfico. Se esse nome não existir, então o nome interno é usado.

## Invocação do serviço

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

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

O serviço Chart é instanciado a partir de uma instância do serviço Calc usando os métodos Charts ou CreateChart.

##### Em Basic

O exemplo abaixo cria uma instância do serviço Chart a partir de um gráfico existente no documento Calc atual:

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Dim oDoc as Object, oChart as Object
        Set oDoc = CreateScriptService("Calc")
        Set oChart = oDoc.Charts("Sheet1", "Object 1")

O exemplo a seguir cria uma instância do serviço Chart ao criar um novo objeto de gráfico com base nos dados contidos no intervalo "Sheet1.A1:C10".

        Dim oDoc as Object, oChart as Object
        Set oDoc = CreateScriptService("Calc")
        Set oChart = oDoc.CreateChart("My Chart", "Sheet1", "Sheet1.A1:C10")

Leia a descrição do método CreateChart para saber mais sobre seus argumentos.

##### Em Python

Os exemplos acima podem ser escritos em Python da seguinte maneira:

        from scriptforge import CreateScriptService
        doc = CreateScriptService("Calc")
        chart = doc.Charts("Sheet1", "Object 1")

        doc = CreateScriptService("Calc")
        chart = doc.CreateChart("My Chart", "Sheet1", "Sheet1.A1:C10")

## Propriedades

Nome | Somente de leitura | Tipo | Descrição
--- | --- | --- | ---
ChartType | Não | String | Especifica o tipo do gráfico como uma string que pode assumir um dos valores a seguir: "Pie", "Bar", "Donut", "Column", "Area", "Line", "XY", "Bubble", "Net" (usar valores em inglês).
Deep | Não | Boolean | Quando for True indica que o gráfico possui três dimensões e cada intervalo de dados é organizado na direção do eixo Z. Quando for False os intervalos de dados são organizados considerando apenas duas dimensões.
Dim3D | Não | Boolean or String | Especifica se o gráfico será mostrado com elementos 3D. Se o argumento for uma string, deve ser um dos seguintes valores: "Bar", "Cylinder", "Cone" or "Pyramid" (em inglês). Se o valor booleano True for especificado, então o gráfico é mostrado usando barras 3D.
Exploded | Não | Numeric | Especifica quanto os segmentos do gráfico de pizza estão deslocados do centro do gráfico como uma porcentagem do raio. Aplicável apenas a gráficos de pizza ou rosca.
Filled | Não | Boolean | Quando for igual a True, especifica um gráfico de rede preenchido. Aplicável apenas a gráficos de rede.
Legend | Não | Boolean | Especifica se o gráfico possui ou não legenda.
Percent | Não | Boolean | Quando for igual a True, os intervalos de dados do gráfico são empilhados e cada categoria soma a 100%. Aplicável aos gráficos de Área, Barras, Bolhas, Colunas e Rede.
Stacked | Não | Boolean | Quando for igual a True, os intervalos de dados são empilhados. Aplicável aos gráficos de Área, Barras, Bolhas, Colunas e Rede.
Title | Não | String | Especifica o título principal do gráfico.
XTitle | Não | String | Especifica o título do eixo X.
YTitle | Não | String | Especifica o título do eixo Y.
XChartObj | Sim | Objeto UNO | Retorna o objeto representando o gráfico, o qual é uma instância da classe ScChartObj.
XDiagram | Sim | Objeto UNO | Retorna o objeto com.sun.star.chart.XDiagram que representa o diagrama do gráfico.
XShape | Sim | Objeto UNO | Retorna o objeto com.sun.star.drawing.XShape que representa o formato do gráfico.
XTableChart | Sim | Objeto UNO | Retorna o objeto com.sun.star.table.XTableChart que representa os dados apresentados pelo gráfico.

## Criando um gráfico

Considere os dados a seguir no intervalo "A1:B6" da planilha chamada "Report".

| A | B
--- | --- | ---
1 | Sample A | Sample B
2 | 36 | 40
3 | 39 | 43
4 | 45 | 40
5 | 52 | 48

Os exemplos abaixo em Basic e Python mostram como criar um gráfico de linha com legendas a partir desses dados.

##### Em Basic

        oDoc = CreateScriptService("Calc")
        oChart = oDoc.CreateChart("Samples", "Report", "Report.A1:B6")
        oChart.ChartType = "Line"
        oChart.Legend = True
        oChart.Resize(1000, 1000, 25000, 15000)

##### Em Python

        doc = CreateScriptService("Calc")
        chart = doc.CreateChart("Samples", "Report", "Report.A1:B6")
        chart.ChartType = "Line"
        chart.Legend = True
        chart.Resize(1000, 1000, 25000, 15000)

O gráfico não precisa ser criado na mesma planilha onde os dados estão localizados. Ele pode ser criado em qualquer planilha existente no arquivo atual ao especificar o nome da planilha no segundo argumento do método CreateChart.

## Métodos

Lista de Métodos no Serviço Chart
ExportToFile | Resize

## ExportToFile

Salva o gráfico como um arquivo de imagem em uma localização especificada. Retorna True se o arquivo de imagem foi criado com sucesso.

### Sintaxe:

chart.ExportToFile(filename: str, imagetype: str = "png", overwrite: bool = False): bool

### Parâmetros:

filename: Identifica o caminho e nome do arquivo onde a imagem será salva. Deve seguir a notação definida em SF_FileSystem.FileNaming.

imagetype: Nome do tipo de imagem a ser criado. Os seguintes valores são aceitos: "gif", "jpeg", "png" (padrão), "svg" e "tiff".

overwrite: Especifica se o arquivo de destino pode ser sobrescrito (Padrão = False).

### Exemplo:

##### Em Basic

          oChart.ExportToFile("C:\Temp\myChart.svg", ImageType := "svg", Overwrite := True)

##### Em Python

          chart.ExportToFile(r"C:\Temp\myChart.svg", imagetype="svg", overwrite=True)

## Resize

Muda a posição do gráfico na planilha atual e modifica sua largura e altura. Retorna True se o redimensionamento foi bem-sucedido.

### Sintaxe:

chart.Resize([xpos: int], [ypos: int], [width: int], [height: int]): bool

### Parâmetros:

xpos, ypos: Especifica as novas posições X e Y do gráfico. Se algum desses valores for omitido ou se valores negativos forem dados, as posições correspondentes permanecerão inalteradas.

width: Especifica a nova largura do gráfico. Se este argumento for omitido ou se um valor negativo for dado, a largura do gráfico permanecerá inalterada.

height: Especifica a nova altura do gráfico. Se este argumento for omitido ou se um valor negativo for dado, a altura do gráfico permanecerá inalterada.

Todos os argumentos devem ser fornecidos como valores inteiros que correspondem a 1/100 de um milímetro.

### Exemplo:

##### Em Basic

          ' Muda apenas as posições X e Y
          oChart.Rezise(1000, 3000)
          ' Muda apenas a largura e a altura do gráfico
          oChart.Resize(, , 25000, 12500)
          ' Argumentos de palavra-chave são suportados
          oChart.Resize(Width := 25000, Height := 12500)

##### Em Python

          chart.Rezise(1000, 3000)
          chart.Resize(-1, -1, 20000, 20000)
          chart.Resize(width=25000, height=12500)

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.

Tópicos relacionados

Serviço SFDocuments.Calc