Tartalom

# SFDocuments.Chart service

The Chart service provides a set of properties and methods to handle charts in Calc documents. With this service it is possible to:

- Access chart objects in Calc documents and manipulate their properties.

- Create and insert new charts into a Calc document.

- Export charts as image files.

## Diagramnevek

Charts may have two different names:

- An internal name given by LibreOffice as soon as the chart object is created (usually "Object 1", "Object 2" and so on).

- A user-defined name, which can be defined by right-clicking the chart and choosing Name in the context menu.

The Chart service primarily uses the user-defined name to access a chart object. If it does not exist, than the internal name is used.

## A szolgáltatás igénybevétele

Before using the Chart service the ScriptForge library needs to be loaded or imported:

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService

The Chart service is instantiated from a Calc service instance either using the Charts or CreateChart methods.

##### A Basic nyelvben

The example below creates a Chart service instance from an existing chart in the current Calc document:

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

The following example instantiate the Chart service by creating a new chart object based on the data contained in the range "Sheet1.A1:C10".

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

Read the CreateChart method description to learn more about its arguments.

##### A Python nyelvben

The examples above can be written in Python as follows:

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

## Tulajdonságok

Név | Írásvédett | Típus | Leírás
--- | --- | --- | ---
ChartType | Nem | String | Specifies the chart type as a string that can assume one of the following values: "Pie", "Bar", "Donut", "Column", "Area", "Line", "XY", "Bubble", "Net".
Deep | Nem | Boolean | When True indicates that the chart is three-dimensional and each series is arranged in the z-direction. When False series are arranged considering only two dimensions.
Dim3D | Nem | Boolean or String | Specifies if the chart is displayed with 3D elements. If the value is a string, it must be either "Bar", "Cylinder", "Cone" or "Pyramid". If the boolean True value is specified, then the chart is displayed using 3D bars.
Exploded | Nem | Numeric | Specifies how much pie segments are offset from the chart center as a percentage of the radius. Applicable to pie and donut charts only.
Filled | Nem | Boolean | When True, specifies a filled net chart. Applicable to net charts only.
Legend | Nem | Boolean | Specifies whether or not the chart has a legend.
Percent | Nem | Boolean | When True, chart series are stacked and each category sums up to 100%. Applicable to Area, Bar, Bubble, Column and Net charts.
Stacked | Nem | Boolean | When True, chart series are stacked. Applicable to Area, Bar, Bubble, Column and Net charts.
Title | Nem | String | Specifies the main title of the chart.
XTitle | Nem | String | Specifies the title of the X axis.
YTitle | Nem | String | Specifies the title of the Y axis.
XChartObj | Igen | UNO objektum | Returns the object representing the chart, which is an instance of the ScChartObj class.
XDiagram | Igen | UNO objektum | Returns the com.sun.star.chart.XDiagram object representing the diagram of the chart.
XShape | Igen | UNO objektum | Returns the com.sun.star.drawing.XShape object representing the shape of the chart.
XTableChart | Igen | UNO objektum | Returns the com.sun.star.table.XTableChart object representing the data being displayed in the chart.

## Creating a chart

Consider the following data in the range "A1:B6" of a sheet named "Report".

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

The examples below in Basic and Python show how to create a line chart from this data with legends.

##### A Basic nyelvben

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

##### A Python nyelvben

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

A diagramot nem kell ugyanazon a lapon létrehozni, ahol az adatok találhatók. Létrehozható az aktuális fájl bármely meglévő lapján, ha a CreateChart módszer második argumentumában megadjuk a lap nevét.

## Metódusok

List of Methods in the Chart Service
ExportToFile | Resize

## ExportToFile

Saves the chart as an image file in a specified location. Returns True if the image file could be successfully created.

### Szintaxis:

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

### Paraméterek:

filename: Identifies the path and file name where the image will be saved. It must follow the notation defined in SF_FileSystem.FileNaming.

imagetype: The name of the image type to be created. The following values are accepted: "gif", "jpeg", "png" (default), "svg" and "tiff".

overwrite: Specifies if the destination file can be overwritten (Default = False).

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

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

## Resize

Changes the position of the chart in the current sheet and modifies its width and height. Returns True if resizing was successful.

### Szintaxis:

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

### Paraméterek:

xpos, ypos: Specify the new X and Y positions of the chart. If any of these values are omitted or if negative values are provided, the corresponding positions are left unchanged.

width: Specify the new width of the chart. If this argument is omitted or if a negative value is provided, the chart width is left unchanged.

height: Specify the new height of the chart. If this argument is omitted or if a negative value is provided, the chart height is left unchanged.

All arguments are provided as integer values that correspond to 1/100 of a millimeter.

### Példa:

##### A Basic nyelvben

          ' Changes only X and Y position
          oChart.Rezise(1000, 3000)
          ' Changes only the chart width and height
          oChart.Resize(, , 25000, 12500)
          ' Keyword arguments are supported
          oChart.Resize(Width := 25000, Height := 12500)

##### A Python nyelvben

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

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.

Kapcsolódó témakörök

SFDocuments.Calc service