SFDocuments.Chart service

Conteúdo

# Serviço SFDocuments.Chart

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

- Aceda aos objetos do gráfico em documentos do Calc e altere as suas propriedades.

- Criar e inserir novos gráficos num documento do Calc.

- Exportar gráficos como ficheiros de imagem.

## Nomes dos gráficos

Os gráficos podem ter dois nomes diferentes:

- Um internal name atribuído por LibreOffice assim que o objeto gráfico é criado (normalmente «Objeto 1», «Objeto 2» e assim por diante).

- Um user-defined name, que pode ser definido clicando com o botão direito do rato no gráfico e selecionando Name no menu de contexto.

O serviço Chart utiliza principalmente o nome definido pelo utilizador para aceder a um objeto gráfico. Se este não existir, é utilizado o nome interno.

## Chamada de serviço

Antes de utilizar o serviço Chart, é 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 Chart é instanciado a partir de uma instância do serviço Calc, utilizando 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 atual do Calc:

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

O exemplo seguinte instanciar o serviço Chart, criando 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 os seus argumentos.

##### Em Python

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

        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 leitura | Tipo | Descrição
--- | --- | --- | ---
ChartType | Não | String | Especifica o tipo de gráfico como uma cadeia de caracteres que pode assumir um dos seguintes valores: «Pie», «Barra», «Donut», «Coluna», «Área», «Linha», «XY», «Bolha», «Rede»
Deep | Não | Boolean | Quando True indica que o gráfico é tridimensional e que cada série está disposta na direção z. Quando as séries False são organizadas tendo em conta apenas duas dimensões.
Dim3D | Não | Boolean or String | Especifica se o gráfico é apresentado com elementos 3D. Se o valor for uma cadeia de caracteres, deve ser «Barra», «Cilindro», «Cone» ou «Pirâmide» Se for especificado o valor booleano True, o gráfico é apresentado com barras 3D.
Exploded | Não | Numeric | Especifica o deslocamento dos segmentos do gráfico circular em relação ao centro do gráfico, expresso em percentagem do raio. Aplicável apenas a gráficos circulares e em anel.
Filled | Não | Boolean | Quando 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 tem ou não uma legenda.
Percent | Não | Boolean | Quando True, as séries do gráfico são empilhadas e cada categoria totaliza 100%. Aplicável a gráficos de área, de barras, de bolhas, de colunas e de rede.
Stacked | Não | Boolean | Quando True, as séries do gráfico são apresentadas sobrepostas. Aplicável a gráficos de área, de barras, de bolhas, de colunas e de 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 | Devolve o objeto que representa o gráfico, que é uma instância da classe ScChartObj.
XDiagram | Sim | Objeto UNO | Devolve o objeto com.sun.star.chart.XDiagram que representa o diagrama do gráfico.
XShape | Sim | Objeto UNO | Devolve o objeto com.sun.star.drawing.XShape que representa a forma do gráfico.
XTableChart | Sim | Objeto UNO | Devolve o objeto com.sun.star.table.XTableChart que representa os dados apresentados no gráfico.

## Criar um gráfico

Considere os seguintes dados no intervalo «A1:B6» de uma folha intitulada «Relatório».

| 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 linhas a partir destes dados, com legendas.

##### 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 de ser criado na mesma folha onde os dados se encontram. Pode ser criado em qualquer folha existente no ficheiro atual, indicando o nome da folha no segundo argumento do método CreateChart.

## Métodos

Lista de métodos do Serviço de Gráficos
ExportToFile | Resize

## ExportToFile

Guarda o gráfico como um ficheiro de imagem num local especificado. Devolve True se o ficheiro de imagem tiver sido criado com sucesso.

### Sintaxe:

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

### Parâmetros:

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

imagetype: O nome do tipo de imagem a ser criada. São aceites os seguintes valores: "gif", "jpeg", "png" (padrão), "svg" e "tiff".

overwrite: Especifica se o ficheiro de destino pode ser substituído (Predefiniçã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

Altera a posição do gráfico na folha atual e modifica a sua largura e altura. Devolve True se o redimensionamento tiver sido bem-sucedido.

### Sintaxe:

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

### Parâmetros:

xpos, ypos: Especifique as novas posições X e Y do gráfico. Se algum destes valores for omitido ou se forem fornecidos valores negativos, as posições correspondentes permanecem inalteradas.

width: Especifique a nova largura do gráfico. Se este argumento for omitido ou se for fornecido um valor negativo, a largura do gráfico permanece inalterada.

height: Especifique a nova altura do gráfico. Se este argumento for omitido ou se for fornecido um valor negativo, a altura do gráfico permanece inalterada.

Todos os argumentos são fornecidos como valores inteiros que correspondem a 1/100 de milímetro.

### Exemplo:

##### Em Basic

          ' Altera apenas as posições X e Y
          oChart.Rezise(1000, 3000)
          ' Altera apenas a largura e a altura do gráfico
          oChart.Resize(, , 25000, 12500)
          ' São suportados argumentos de palavra-chave
          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 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.

Tópicos relacionados

Serviço SFDocuments.Calc

Necessitamos da sua ajuda!