XCharts/Documentation~/en/tutorial01.md

---
title: Introductory tutorial: Get started with XCharts 3.0 in 5 minutes
sidebar_position: 11
slug: /tutorial01
---

# Tutorial: Get started with XCharts 3.0 in 5 minutes

> Note: This tutorial is for XCharts 3.x version only

## What do I need to know before using XCharts

- Have used Unity, know the basic operation of Unity.
- Understand UGUI and can use UGUI.
- Understand MonoBehavior script usage in Unity, know how to hang scripts, manipulate scripts with code.

## Get and import XCharts

XCharts can be imported into a project in any of the following ways:

- Source XCharts directly into the project

    After downloading the XCharts source code, copy the XCharts directory directly to the Assets directory of the Unity project.

- Import XCharts through `Assets/Import Package`

    After downloading the.unitypackage file for XCharts, open Unity and go to the menu bar Assets--> Import Package--> Select.unitypackage import to start using XCharts.

- Import XCharts through the Package Manager

    For Unity 2018.3 and later, XCharts can be imported through the Package Manager. After opening the Package Manager, run the `Add package form git URL...`, input XCharts dead simple URL: ` https://github.com/XCharts-Team/XCharts.git use XCharts after ` wait a moment.

    You can also add the package directly to the manifest.json file: Open the manifest.json file in the Packages directory and add it under dependencies:

    ``` json
    "com.monitor1394.xcharts" : "https://github.com/XCharts-Team/XCharts.git",
    ```

    To update XCharts, remove com.monitor1394.xcharts from the manifest.json file under lock (some versions of Unity may be packages-lock.json) and re-download and compile.

- Recommended daemon into XCharts (not required)

    [XCharts Daemon](https://github.com/XCharts-Team/XCharts-Daemon) can ensure update compilation is normal, when the local open TextMeshPro or NewInputSystem would be very useful. After importing Xchart-daemon into a project, when updating XCharts, the Daemon will automatically refresh asmdef according to the status of local TMP, etc., to ensure normal compilation and facilitate the execution of automated processes such as CI-CD.

## Add a simple chart

Right-click in `Hierarchy` view or menu bar `GameObject` drop down and select `XCharts->LineChart`, can quickly create a default line chart out:

![linechart1](img/tutorial01_linechart1.png)

## Add multiple Seire

In the Inspector view, locate LineChart's panel, and with the `Add Serie` button, you can add a second Line line:

![op_addserie](img/tutorial01_addserie.png)
![linechart2](img/tutorial01_linechart2.png)

## Add other components

The default chart does not have a `Legend`, and a `Legend` Component can be added via the `Add Component` button:

![op_addcomponent](img/tutorial01_addcomponent.png)

## Add Serie components

Serie comes with only a few common components, and others are added as needed. For example, if you need to fill a line chart area with color, you can add a separate `AreaStyle` component to Serie:

![op_addseriecomponent](img/tutorial01_addseriecomponent.png)
![linechart3](img/tutorial01_linechart3.png)

## Add the SerieData component

If you need to personalize the configuration of each data item, you can add a Component to each SerieData separately. For example, we give the second data of the line chart a separate display `Label`:

![op_addseriedatacomponent](img/tutorial01_addseriedatacomponent.png)
![linechart4](img/tutorial01_linechart4.png)

## More components and configuration parameters

XCharts has been iteratively optimized and now has dozens of main and sub-components, each with a few to dozens of configurable parameters to support a variety of flexible and complex functions.

Using XCharts for the first time, you can add various charts in the `Inspector` view, add or adjust the components in the chart, and the `Game` view gives real-time feedback on the effects of adjustments to familiarize yourself with the use of various components. Detailed parameter descriptions of each component can be found in the [XCharts Configuration](Configuration.md).

## How to adjust parameters quickly

XCharts is configuration and data driven. Want what effect, only need to adjust the configuration parameters under the corresponding component can be, do not need to change the nodes under the `Hierarchy` view, because those nodes are generated by the `XCharts` internal according to the configuration and data, even if changed will be restored in the refresh.

How to quickly locate the component corresponding to the effect you want to change requires a certain understanding of the component. For example, if we want to show an arrow at the end of the X-axis, how do we position it? First, position the X-axis to `XAxis0`; Second, locate the axis to `AxisLine`; Finally, check to see if there are any parameters in the AxisLine component that can achieve this effect, and check [XCharts configuration](Configuration.md) for uncertain parameters.

`XCharts` provides a full range of parameter configuration from the global` Theme `, series` Serie `, and single data item `SerieData`. The priority in descending order is: `SerieData` -> `Serie` -> `Theme`. Take the color of `ItemStyle` for example:

1. If the `ItemStyle` of `SerieData` has a color value other than `0000`, this color value is preferred.
2. If the ItemStyle of `Serie` is configured with a color value other than `0000`, this color value takes precedence.
3. Otherwise, the Color value is taken from the Color Palette of the Theme.

Usually, `0000` indicates the theme default color, and 0 or null indicates the theme default.

## Add line charts with code

Attach the `LineChart` script to the gameObject:

```csharp
var chart = gameObject.GetComponent<LineChart>();
if (chart == null)
{
    chart = gameObject.AddComponent<LineChart>();
    chart.Init();
}
```

Resize:

```csharp
chart.SetSize(580, 300);//代码动态设置尺寸，或直接操作chart.rectTransform，或直接在Inspector上改
```

Set the title:

```csharp
var title = chart.EnsureChartComponent<Title>();
title.text = "Simple Line";
```

Set whether prompt boxes and legends are displayed:

```csharp
var tooltip = chart.EnsureChartComponent<Tooltip>();
tooltip.show = true;

var legend = chart.EnsureChartComponent<Legend>();
legend.show = false;
```

Set axes:

```csharp
var xAxis = chart.EnsureChartComponent<XAxis>();
xAxis.splitNumber = 10;
xAxis.boundaryGap = true;
xAxis.type =  Axis.AxisType.Category;

var yAxis = chart.EnsureChartComponent<YAxis>();
yAxis.type =  Axis.AxisType.Value;
```

Clear default data and add `Line` type `Serie` for receiving data:

```csharp
chart.RemoveData();
chart.AddSerie<Line>("line");
```

Add 10 data:

```csharp
for (int i = 0; i < 10; i++)
{
    chart.AddXAxisData("x" + i);
    chart.AddData(0, Random.Range(10, 20));
}
```

So a simple line chart comes out:

![tutorial01_linechart_simple](img/tutorial01_linechart_simple.png)

If there are multiple series in a Chart, the data of Axis only needs to be added once, rather than repeated in multiple cycles. Remember: the number of data in Axis should be the same as the number in Serie.

See `Examples`: `Example13_LineSimple.cs` for the complete code

You can also use code to control more parameters, there are more Examples under `Examples`, all the configurable parameters seen in the `Inspector` can be set by code. All parameters in [XCharts configuration](Configuration.md) can be controlled by code.

In addition, unless customized, it is recommended to call the `public` interface provided under `Chart`, especially in the data-related operations section. These interfaces do some associated processing inside, such as refreshing charts. Common interfaces are:

1. `Chart.ClearData()` : Clear chart data (without removing Series)
2. `Chart.RemoveData()` : Clear chart data (will remove all Serie)
3. `chart.AddSerie()` : AddSerie
4. `chart.AddXAxisData()` : Add X-axis data
5. `chart.AddData()` : Adds Serie data
6. `chart.UpdateData()` : Updates Serie data
7. `chart.UpdateXAxisData()` : Updates the X-axis data
8. `chart.UpdateDataName()` : Updates the Serie data name

XCharts has an automatic refresh mechanism inside, but it only triggers under certain conditions. If you call the interface of the internal component, encounter the component did not refresh, and indeed can not find the reason, you can use the following two interfaces to force refresh:

1. `chart.RefreshAllComponent()` : refresh chart component, to initialize all of the components, often is not recommended.
2. `chart.RefreshChart()` : refreshes the chart drawing, only the drawing part is refreshed, and the component text, position, etc., is not refreshed.
3. Individual components can also refresh only themselves by `SetAllDirty()`.

## Use TextMeshPro

XCharts supports TextMeshPro, but it is disabled by default and needs to be switched manually. It can be turned on and off in the following ways:

![textmeshpro1](img/tutorial01_textmeshpro.png)

After opening, you need to set the global font used by TextMeshPro, or you can set it separately in the Theme:

![textmeshpro-font](img/tutorial01_textmeshpro_font.png)

It is recommended to plan whether to use TextMeshPro at the beginning of the project and set the font. When switching TMP with many existing charts, some charts may not refresh automatically. You can manually click the `Rebuild Chart Object` button to rebuild the chart, which can be initialized normally.

When updating XCharts for TMP projects, you may encounter problems with missing TMP references and failing to compile. These problems can be solved in one of two ways:

1. Find `XCharts.Runtime.asmdef` and `XCharts.Editor.asmdef` and manually add references to `TextMeshPro`
2. Remove the `dUI_TextMeshPro` macro for Scripting Define Symbols in PlayerSetting

Version `3.8.0` after adding daemon[XCharts - Daemon](https://github.com/XCharts-Team/XCharts-Daemon), will be XCharts-Daemon import project, When updating XCharts, the daemon automatically refreshes the asmdef based on the locally enabled TMP to ensure proper compilation.

## Change chart parameters with code

All parameters seen on Inspector can be modified with code, the key is to identify whether the parameters you want to change are on the component, on the Serie, or on the specific data item SerieData.

### Change the parameters on the main component

You need to obtain the component first, and then modify the parameters in it:

```csharp
var title = chart.EnsureChartComponent<Title>();
title.text = "Simple LineChart";
title.subText = "normal line";

var xAxis = chart.EnsureChartComponent<XAxis>();
xAxis.splitNumber = 10;
xAxis.boundaryGap = true;
xAxis.type = Axis.AxisType.Category;
```

> Note: When the earlier version does not have the EnsureChartComponent() interface, GetOrAddChartComponent() is used.

### Change Serie parameters

For newly added Serie:

```csharp
var serie = chart.AddSerie<Pie>();
serie.center[0] = 0.5f;
serie.center[1] = 0.5f;
serie.radius[0] = 80;
serie.radius[1] = 90;
serie.animation.dataChangeEnable = true;
serie.roundCap = true;
```

For existing Serie:

```csharp
var serie = chart.GetSerie<Pie>();
serie.center[0] = 0.5f;
serie.center[1] = 0.5f;
serie.radius[0] = 80;
serie.radius[1] = 90;
serie.animation.dataChangeEnable = true;
serie.roundCap = true;
```

Add additional components to Serie:

```csharp
serie.EnsureComponent<AreaStyle>();

var label = serie1.EnsureComponent<LabelStyle>();
label.offset = new Vector3(0,20,0);
```

### Change the parameter on the data item SerieData

```csharp
var serieData = chart.AddData(0, 20);
//var serieData = serie.GetSerieData(0); //从已有数据中获取
serieData.radius = 10;

var itemStyle = serieData.EnsureComponent<ItemStyle>(); //给数据项添加ItemStyle组件
itemStyle.color = Color.blue;

```