NOTE:  THIS DOCUMENT IS VERY MUCH OUT OF DATE.
       I WILL REWRITE IT WHEN I GET TIME.





                         Design of KChart 2.0
                         ====================


This file describes the overall design of KChart version 2.  It is
intended for people who want to start to develop KChart, and need an
introduction to the structure of the code.  For a more detailed
description of the classes, see the API-docs generated from doxygen.


1. KOffice 1.x architecture
---------------------------

Before we start to describe the design of KChart 2.x, we should
recapitulate how KOffice 1.x was designed and also KChart 1.x.  We
will then emphasize differences between this and the new design for
those who have seen the old code.

KOffice 1.x was generally built on KParts, the general KDE embedding
technology.  Each KOffice 1.x application (component) consist of the
application itself, which is really not much more than a frame, and an
embeddable KPart.  The KPart implements the real functionality of the
application, and can also be embedded into other non-KOffice
applications, like Konqueror.

When one document embeds another, e.g. a chart in a spreadsheet, and
the user wants to edit the embedded document, the KPart for that
embedded document gets enabled inside the application of the embedding
document.  This makes the whole GUI change, and it also changes back when
the embedded component is no longer active.  So, when KSpread embeds a
chart and the user double clicks the chart to edit it, the KSpread GUI
changes to the KChart one.


1.1 Internals of KChart 1.x
- - - - - - - - - - - - - -

KChart 1.x is built as a GUI for the embeddable chart component
KDChart from Klarälvdalens Datakonsult AB. This is a commercial
component that was graciously released under a GPL license and made
available for KOffice to use.  KDChart is built in the subdirectory
kchart/kdchart, and is really the component that provides the real
functionality for KChart.  One example of how deep the dependency of
KDChart goes is the fact that the file format for KChart 1.x is the
builtin file format for KDChart, just enhanced with very few extra XML
tags. 

KDChart is represented by mainly two classes:

 - KDChart:
       the class representing the chart itself. This is the class that
       actually draws the chart on the widget. 

 - KDChartParams
       a class that holds all parameters for the KDChart, like legend,
       fonts, colors, background image, etc, etc

In addition there is also he class KDChartTableData, which holds the
numerical and string data that is presented in the chart.  

When support for the OpenDocument format was implemented,
KDChartParams was extended by the class KChartParams.  This class was
supposed to hold all the missing parts of the ODF that was not
supported by KDChart directly, but this idea was never fully
implemented.

So, to conclude, the main classes of KChart 1.x was:

 - KChartPart : public KoDocument (via KoChart in koffice/interfaces)
       The class that held the chart document itself as represented by
       the KDChart classes above.  This class provided embedding into
       other KOffice 1.x classes as well as other KDE
       applications.  There was support for both read/write editing of
       the chart and also a read-only variation for only show.

 - KChartView : public KoView
       The class that implemented the GUI and held all the KActions.
       This was the important part of the KChart application.


2. KOffice 2.x architecture
---------------------------

The architecture of KOffice 2.x is totally different.  The most
important change is that KParts are no longer used  for embedding
documents into other documents.  Instead, embedding is done with so
called Flake Shapes, as defined and implemented by the Flake library
in koffice/libs/flake.  

A Flake Shape (from now on 'shape') can be as simple as a line or
circle, or as complex as a full spreadsheet or a chart. Each shape can
be manipulated by so called Tools, either generic tools like the
transform tool or specialized tools that only apply to one or a few
different shapes.  Examples of very specialized tools are the tools
that handle insertion and manipulation of musical notes in the Music
Score Shape.  We will not go into more details about Flake here, but
instead ask the eager developer to read the Flake API docs.


1.1 KOffice 2.x and KChart
- - - - - - - - - - - - - 

From the above, we realize that the main part of KChart for KOffice
2.x has to be a Chart Flake Shape.  This shape will contain all
necessary classes to represent the chart and the data to be shown in
the chart.  In addition, we have to provide some Flake Tools that will
aid the user in the manipulation of the chart shape.

But even if KOffice embedding is no longer done by KParts, we still
need to provide a KChart KPart.  Without it, Konqueror will not be
able to show a .odc (OpenDocument Chart) file, and neither will any
other KDE application.

We will also have to provide a main KChart application whose only
purpose will be to embed the chart shape and host the tools to
manipulate it. This application will contain a KChartView that
inherits KoView.

So, to summarize we will provide:

 - ChartShape : public KoShape
       the class that implements the Chart Flake Shape.  This will
       make the chart embeddable into any KOffice application.  In
       addition to the shape, there will also be a number of Flake
       Tools to manipulate the chart.

 - KChartPart : public KoDocument
       a KPart that lets KChart be embedded into other KDE
       applications.  This KPart will embed a ChartShape and let the
       user change its size and manipulate it in other ways.

 - KChartView : public KoView
       A standard KOffice view, containing toolbars and all the
       actions that are needed to save and load the document and do
       all the other tasks that the user should be able to do.  This
       basically defines the KChart application.


2.2 Internals of KChart 2.x
- - - - - - - - - - - - - -

KChart 2 will have to answer to more demands than KChart 1.  The
biggest differences is full support for OpenDocument and the Flake
embedding technology.  We will also reduce the dependency of the
KDChart library, and use it more as a pure View in the Qt/KDE sense
than the central class which also stores the data and reads/writes it
from/to files.

So here are the main classes for KChart 2:

 - ChartShape : public KoShape, public KoChart::ChartInterface

       This is the central class that holds all the chart data and
       configuration.  It contains all the configuration for the chart
       as well as a pointer to a KDChart and a QAbstractItemModel
       based data class (most likely a QStandardItemModel).

       In connection to the shape, there are a number of tools.  So
       far, there is the ChartTypeTool (to be renamed into
       ChartStandardTool), and the ChartLegendTool.  Soon there will
       be at least a ChartDataSeriesTool to configure everything
       regarding data series.

       This class will also have a Kross interface that will expose
       the chart to Kross scripts and a DBUS adaptor that will let the
       chart be manipulated through DBUS.

 - KChartPart : public KoDocument

       A KPart that will let Konqueror and other browsers embed and
       preview charts.  This class also will embed a ChartShape
       directly.

 - KChartView : public KoView

       The view that implements the main GUI of the KChart
       application.

Boudewijn Rempt summed it all up this way:

 - "Look at KWord: It's a KPart that contains a view and a document.
    The document contains the shape and the shape draws itself on the
    view and also contains the data."

I will meditate on that, and will surely understand it myself some
day.  :-)


3. Some Notes About the Work Towards KChart 2.0
-----------------------------------------------

The most important class is the  ChartShape.  This class will be
responsible for holding the whole chart and perform the following
duties:

 - Giving a full API to the chart
 - Reading/writing ODF files
 - Controlling the KDChart classes so that KDChart can be used to show
   the chart visually.

Most of these tasks will be performed via subclasses and helper
classes.  The main classes should be implemented first, and the full
class structure will evolve during the work.

There is lots of code in KChart 1.x that can be reused.  However, we
should provide new classes for KChart 2.x and steal code from the
KChart 1.x classes when needed, not try to convert the KChart 1.x
classes to KChart 2.  This way we will not have to deal with all the
cruft that has collected during the previous years.

Most of the KChart 1.x classes will be moved to a new directory,
kchart/attic, where code can be copied from it to implement features
like ODF reading/writing and similar low-level things..

Much of kchart 1.x is useless, e.g. the old configuration dialogs.
These features will instead be implemented using Flake Tools, and qt
designer .ui files will be mandatory.


3.1 Recommended reading
- - - - - - - - - - - -

The following documents are recommended reading for KChart hackers.
Especially the first 4 are important.

 * ODF Essentials
   A very nice book that describes the ideas behind OpenDocument, and
   important parts of the standard.  It can be downloaded from
   http://books.evc-cit.info/ 

 * Introduction to the Flake library
   http://api.kde.org/koffice-api/koffice-apidocs/libs/flake/html/index.html
   http://wiki.koffice.org/index.php?title=Flake

 * KDChart Programmers Manual
   trunk/koffice/kchart/kdchart/doc/kdchart.pdf

 * Loading and Saving OpenDocument in KOffice
   http://wiki.koffice.org/index.php?title=KOffice_and_ODF

 * The full OpenDocument 1.1 standard
   http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office#odf11

 * The proposed changes for OpenDocument 1.2
  http://www.oasis-open.org/committees/download.php/24327/ODF-Metadata-Proposal.pdf
