# The &kchart; Handbook

&Jonathan.Drews; &Jonathan.Drews.mail;
Raphael Langerhorst raphael.langerhorst@kdemail.net
&FDLNotice;
2005-04-30
1.4

&kchart; is an application for visualizing numerical data. It has many different chart types available like bar graphs, line plots, pie charts, ring charts and more.

&kchart; is a &koffice; component and is very well integrated with &kspread; to allow visualization of spreadsheet data. But it is also possible to use &kchart; as a standalone application or integrate it in other &koffice; components.

KDE kdeutils Kchart chart graph plot

## Introduction

&kchart; is a tool for visualizing numerical data. It can be used as a standalone application with a simple &dataeditor;. But as a &koffice; component it offers very flexible integration. &kspread; uses the &kchart; component for charts and diagrams. &kspread; can be seen as a very powerful data provider for &kchart; input.

But embedding is not limited to &kspread;. A &kchart; chart can be embedded in many of the &koffice; components like &kword;, &kpresenter; or &kivio;.

To start with we will look at the user interface of &kchart; and how it can be used as a standalone application. When we are familiar with &kchart; we will investigate the charting capabilities it offers together with &kspread;.

## The User Interface

### Main Application Interface

We will take a look at a simple example to get to know &kchart;. Along the way we will also discuss the user interface at length so you will learn about many details of the component.

When you start &kchart; as a standalone application you get the usual startup dialog where you can choose between different templates or load existing chart documents.

KChart Startup Dialog

You can choose between various ways to startup &kchart;. At the top of the dialog you see three option pages. The first is for creating a new chart from various templates, the second for opening an existing chart with a file dialog and the last page lets you choose between recently opened charts.

For now we will start with the default template. Select the Create Document page, then select Charts in the left area and finally select Bar chart in the main template area. Normally this template should already be selected when you launch &kchart;.

If you decide to start &kchart; with a selected template as defult you can also select this option at the bottom of the dialog.

Now click on the OK button to start with a bar chart.

KChart User Interface

As you can see, there is already some example data present. &kchart; offers the default toolbar for creating a new chart, saving, loading and printing the chart. The second toolbar offers icons for editing the data, configuring the chart or using a configuration wizard. You can also switch between different chart types with the rest of the icons. Note that some of these chart types also have subtypes.

The menu offers all standard entries, including shortcut and toolbar configuration and page layout for printing.

Note that data editing is not available if you use &kchart; from within &kspread; because all data is provided by the spreadsheet. As a standalone application the &dataeditor; is an important part of the application.

### Chart Wizard

The wizard is actually a very useful part of &kchart; for quickly setting up some basic options like chart type and chart labelling in a few easy steps.

You can run the wizard at any time, it will always preserve your data and other configuration. Also, you can change every single configuration you do with the wizard later as well, without losing anything. In fact the wizard is just a way to set some basic and important options in one go.

To start the wizard simply click on the icon in the toolbar.

#### Step 1 - Choosing the Chart Type

Wizard Step 1 - Chart Type

The first step in the wizard is to actually choose the primary type of the chart. This selection has the most important impact on how your data will be presented. Thus it should be chosen well. You can change the type of the chart with the icons in the toolbar without losing any data or configuration later on. In fact it is even considered normal to test all the various chart types to find the best fitting.

In this example we choose the line type. Depending on the chosen chart type different options are available in the following steps.

After chosing the type you can get to the next step with the Next button. You can also choose Finish at any step if you are already comfortable with the setup done so far.

#### Step 2 - Choosing the Subtype

Wizard Step 2 - Chart Sub Type

In case the chosen chart type has various sub types you can choose it in the second step. If the chart type has no sub types, this step will be skipped automatically.

If you deside to change the sub type later, you can do this in the appropriate configuration dialog which will be shown later.

You can simply leave the default selection and go to the next step. Of course you can chose any desired sub type if you want.

#### Step 3 - Labels and Legend, Fonts

Wizard Step 3 - Labels and Legend

In the third step you can set the text for the chart title, the axes and the legend. You can also configure the desired font in detail for each of these.

#### Step 4 - Axes

Wizard Step 4 - Axes

The last step of the wizard lets you set various options for the axes and other options, depending on the chart type.

You can either choose Finish to accept the options for your chart, go Back and change various things or simply dismiss all options from the wizard by choosing Cancel.

If you choose Finish all your choices in the wizard will be integrated in the chart and you can continue to enter some data and do some fine tuning of various options.

Remember that the chart configuration dialog has many more options available, we will discuss these later.

### The &dataeditor;

The &dataeditor; can be reached by selecting Edit Edit Data... from the menu or by clicking on the icon in the toolbar.

&dataeditor; in standalone mode

The &dataeditor; can be used to set all values. You can also define the number of rows and columns.

Depending on the chart type rows and columns have different representations. Each row can generally be considered to be one data series or data set while each column represents the values of all data sets at a certain location.

The name of a data set can be changed by clicking on the row header (left of the first column with values). The name of a column can be changed by clicking on the column header (above the first row).

The number of rows and columns can be adjusted to fit the needs. Since version 1.4 the restriction to 16 rows and 16 columns has been eliminated.

### Chart Configuration

&kchart; offers many configuration options for the chart. These are available in standalone mode and when embedded in &kspread;

Depending on the chart type you have selected, the available options are slightly different. Let's choose the line chart type by clicking on the icon in the toolbar.

To get to the chart configuration dialog, select Edit Chart Configure Chart... from the menu or click on the icon in the toolbar.

#### Row and Column Swapping

Configuration page 1 - row/column swapping

The first configuration page can be used to swap the interpretation of rows and columns. By default one row is considered to be a data set and each column holds the individual values of the data series. Here you can choose to have a each column hold one data set. Note that the values are not really swapped but only their interpretation.

#### Chart Subtype

Configuration page 2 - Chart Subtype

The second page can be used to select the desired sub type of a chart. The available sub types depend on the chart type, in this case the line chart. Some chart types have no sub type at all in which case this configuration page is not shown. You also get a preview for each subtype.

Remember that the chart type can be chosen from the toolbar while the subtype can be set through this configuration dialog.

#### Title and Footer

Configuration page 3 - Title and Footer

On the third page you can set the title, the subtitle and the footer of the chart, each with individual font settings.

#### Legend

Configuration page 4 - Legend

The legend configuration page lets you set all aspects of the legend. The legend contains the names for all data sets with the respective colors, this is important to identify the data on the chart.

The General box holds the title of the legend, which is displayed at the top of the legend box. The Position box can be used to place the legend at various locations on the chart. Use the central button to hide the legend.

The Font box can be used to set different fonts for the legend title and the individual entries. Additionally you can set different colors in the Color box.

#### Axes

Configuration page 5 - Axes

The Axes page holds configuration for the chart axes. This page highly depends on the chart type chosen. For the line chart you can set linear or logarithmic scales, turn the grid on and off and the line marker puts a square at every data value.

#### Colors

Configuration page 6 - Colors

On the colors page you can choose the colors for the individual data sets. You can also set colors for some general chart parts like axes line color and grid color.

#### Font

Configuration page 7 - Font

The font page can be used to configure various fonts like titles, axes labels and so on. Some of these fonts can be set on other pages as well, but on the font page you have them all in one place.

#### Background

Configuration page 8 - Background

On the background page you will find various options for tweaking the background settings of the chart. You can either choose different background colors or even a background picture.

#### More...

This short overview of the configuration options gave you an introduction to the configuration possibilities of your chart, it is by no means complete. Different chart types have additional specialised configuration pages and you are welcome to look around, try different chart types and look at the configuration possibilities. Use the tooltips and read the What's This? help. To use the What's This? help simply click on the question mark on the window decoration and then click on the area of the configuration page you want get more information on.

## &kchart; as a standalone Application

The previous chapter described the user interface, various configuration options, data editing and the wizard in detail.

This chapter gives real-life examples on how to use &kchart; in various situations as a standalone application. The purpose is to give you some understanding of the way &kchart; works and how various parts relate to each other.

### Presenting Sales Figures

#### Warming up

This first example which might often be encountered in real life is presenting sales figures, or in this particular case profit.

Imagine you own a company that has three main categories of business: sales, support and training. And you would like to present the profit of these categories over some years. Making a graphical statistics is certainly a good idea. &kchart; can help you here.

#### Getting started

Run &kchart; and select the blank template.

Starting with a blank chart

Hit the OK button to get started. &kchart; will present to you a completely empty document. That's good, we just need to enter some data and do some basic configuration to get a nice chart.

A blank chart

#### Getting the numbers in

The first step, and probably the most important, is to get the actual data into the chart. This can easily be done with the &dataeditor;. As usual you can get to the data editor by clicking on the icon in the toolbar.

You will notice that no data is present. Also note that the number of data rows and columns is set to a minimum, which is 1.

Now, just enter the data you see in the next screenshot. Note that you can increase the number of rows and columns with the spin boxes in the lower left corner. The names of the rows and columns themselves can be changed by clicking on them.

The Data

Simply click the OK button when you are done. This will present to you a simple bar chart.

Simple chart without fine tuning

Read on to do some fine tuning!

#### Fine Tuning

We will now do some fine tuning and put a title on the chart. And, we will add a nice 3D effect to the bars as well.

Start up the configuration dialog by clicking on the icon in the toolbar.

##### Title

Options - Title

Let's start with labeling. Go to the Header/Footer page and enter the text like in the above screenshot.

##### X-Axis Font Settings

The next step is to make the font of the x axis a bit bigger. You can do this on the Font page.

Options - Fonts

Choose the X-Axis item and click on the Font... button. Choose a somewhat larger font like in the following screenshot.

Options - X-Axis Font

Note that the font is set to Relative. This means that the font is automatically scaled according to the overall chart size. This is quite usefull and most of the time what the average user expects.

##### Giving it a 3D Look

The final configuration page is 3D Parameters. You might need to click on the right arrow at the top to get to it if the width of the dialog too small.

Options - 3D Parameters

To get a 3D effect for the chart, simply activate 3D bar.

That's all what we need for a reasonable looking chart. Note that much of this configuration could also have been achieved with the wizard. It's basically a matter of taste what you use. Experienced users will likely use the full option dialog we used in this example.

Simply accept the options by clicking on the OK button.

#### Final output

The final chart will look like the next screenshot.

Final Chart

You might want to enlarge the application window to see the chart in full size. Note how the fonts get larger in relation to the chart size.

There are certainly aspects to improve further for your personal taste. For example try to make the title font even bigger. Just experiment further, this way you will get to know a lot of the &kchart; application.

Finally you can save the application from the File menu and quit with File Quit

#### Exporting to Graphic Formats: SVG, PNG, JPG, Krita, Karbon14, Gimp and more

For further processing, the chart can also be exported as a graphics file. Many formats are available. Using either PNG, SVG, JPG or Krita will likely produce the best result.

To export your current chart simply choose File Export... from the menu and select the desired file format from the filter box.

## Using &kchart; in &kspread;

In addition to standalone operation, &kchart; is designed to use with &kspread;. This chapter describes how to create and manipulate charts from within &kspread;.

Remember that &kchart; embedding into &kspread; is a very commonly used and well implemented feature, the examples in this chapter should just get you started.

As soon as you have created a chart in &kspread; you can take full advantage of all the &kchart; features by double clicking on the chart area. This is necessary to get to all advanced configuration options. Keep in mind that the data editor is not available when &kchart; is embedded into &kspread;. This is obvious since &kspread; servers, from the &kchart;'s point of view, as a powerful data provider.

Swapping x and y is of particular interest when working with &kspread;. You can swap interpretation of x and y axis in &kchart; in the Data Format settings which can be accessed through the Edit menu or the context menu when right clicking on the chart itself. As noted above you need to be inside the &kchart; component in order to access these settings, which can be done by double clicking the embedded chart in your spreadsheet.

### Plotting with &kchart;

To plot with &kchart;, when it is embedded in &kspread;, do the following:

Picture of toolbars dialog

- Highlight the second row of numbers.

- Next click on the Chart button to create the chart.

- Select the options you want from the chart Wizard. The chart Wizard will pop up after you insert the chart.

The whole data could also be created using two columns instead of two rows. If using columns you might want to switch x and y axis in the &kchart; configuration as described above.

To make a bar chart for individual items, put the numbers in a column, as shown below.

Picture of toolbars dialog

The orientation of the numbers determines how the plot will be made.

- A row of numbers defines the ordinates for a single plot.

- A column of numbers defines the heights for each bar, in a bar graph. It also determines the size of the slices in a pie chart.

## Command Reference

### The main &kchart; window

#### The File Menu

&Ctrl;N File New

  Creates a new document

&Ctrl;O File Open...

  Opens a document

File Open Recent

  Opens a recently saved document

&Ctrl;S File Save

  Saves the document to the current file. If the chart has not yet been saved the file dialog is shown.

File Save As

  Saves the document, the file dialog is used.

File Reload

  Reloads the document.

File Import...

  Opens a document with any supported format. The document does not become the imported file.

File Export...

  Saves a document to any supported format. The document does not become the exported file. You can also choose among many image formats like PNG, SVG, Krita, Gimp or JPG.

File Import Data...

  Imports CSV values from a file, much like the CSV import in KSpread. Note that you can specify various options and different separators (not just commas).

File Create Template From Document...

  Create a &kchart; template based on this document.

&Ctrl;P File Print

  Prints the document

  Make sure the proper print system is selected in the Print system currently used: section. This option can be seen after clicking on the Expand button.

File Print preview

  Displays a preview of what the printed document will look like.

File Document Information...

  Opens a dialog box where you can enter information about your chart.

  This document information will be displayed in the &konqueror; file browser as a tooltip. The tooltips are pop-ups that show the contents of a file when you move your mouse over the file icon.

File Mail...

  Sends the chart as an email attachment.

&Ctrl;W File Close

  Closes the current chart.

&Ctrl;Q File Quit

  Quits &kchart;

#### The Edit Menu

Edit Edit Data...

  Table for entering the data.

Edit Configure...

  Dialogs for configuring the chart.

##### The Configure Tabs

Data Format

  Swap row and colums (x/y flipping).

Colors

  Select graph colors, grid colors and title colors here.

Font

  Select font style and size here. The series colors can be selected here also. The series refer to the individual graphs. Each graphed set of data is a series.

Background

  Select the background color for your graph.

  The picture backgrounds do not work at this time.

Legend

  Change the location of the legend box. The color of the legend box can be changed also. The legend box contains the color key to the graph series.

Axes

  The axes can be turned on or off here.

  Not all the features work here.

3D Parameters

  The perspective for the 3d bar graphs can be set here.

Chart Subtype

  Changes the arrangement of bar graphs.

Header/Footer

  Enter the titles you want for your graph here.

#### The Settings Menu

Settings Toolbars

  Show/Hide various Toolbars.

Settings Configure Shortcuts...

  Configure key shortcuts for &kchart;.

Settings Configure Toolbars...

  Configure the &kchart; toolbars.

#### Configuring Shortcuts

The Settings Configure Shortcuts... allows you to specify shortcuts.

Below is an example of how to configure a shortcut for opening the chart wizard.

Picture of shortcut dialog

- Click on the Custom button.

- Next click on the Primary Shortcut button.

- Do `&Alt;&Ctrl;W` and the dialog should disappear. The shortcut is now entered.

Pressing the keys `&Alt;&Ctrl;W` now opens the Wizard.

#### Configuring Toolbars

The Settings Configure Toolbars... is used to add additional buttons to the toolbars.

Picture of toolbars dialog

- To add a button to the File toolbar,

  Picture of toolbars dialog

  make sure File <KOfficeShell> is displayed in the top combo box.

- Click on one of the items in the left hand pane. This item will now have a blue background showing that it has been selected.

- Next click on the Right arrow button to place it in the right pane.

- Click on `Apply` and then click on `OK`

The new Item should be in the toolbar.

#### The Help Menu

&help.menu.documentation;

## Credits and License

&kchart;

Program copyright 1998-2005 the KChart Team

Original Authors:

- &Matthias.Kalle.Dalheimer; &Matthias.Kalle.Dalheimer.mail;

- Torben Weis weis@kde.org

Contributors:

- Laurent Montel lmontel@mandrakesoft.com

- Karl-Heinz Zimmer khz@kde.org

- Inge Wallin inge@lysator.liu.se

Documentation copyright 2002 &Jonathan.Drews; &Jonathan.Drews.mail;

Documentation copyright 2005 Raphael Langerhorst raphael.langerhorst@kdemail.net

&underFDL; &underGPL;
&documentation.index;