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.

Serviço SFDocuments.Calc