
---=== KD Chart 2.0 Beta 1 API Introduction ===---

KD Chart 2.0 and Qt 4:
---------------------

Version 2.0 of KD Chart fully supports and builds on the technologies
introduced with Qt 4. The charting engine makes use of the Arthur and
Scribe painting and text rendering frameworks to achieve high quality
visual results. KD Chart 2.0 integrates with the Interview framework
for model/view separation and, much like Qt 4 itself, provides a
convenience Widget class for those cases where that is too complex.
The overall API strives for maximum consistency with the concepts
and API style found in Qt 4.

Of course, this means breaking source compatibility in several places,
but like Trolltech, we have made a conscious decision that it would be
better to clean up the API now, than to carry it with us into the next
generation of KD Chart. Wherever possible, compatibility methods and
classes have been, or will be, provided.

Notice to Beta users: While the API should be roughly
complete and is not expected to change fundamentally until the
release, not all of it is actually implemented yet.

Overview:
---------

The core of KD Chart's 2.0 API is the KDChart::Chart class. It encapsulates the
canvas onto which the individual components of a chart are painted, manages them and
provides access to them. There can be more than one KDChart::Diagram on a
KDChart::Chart, how they are laid out is determined by which axes, if any,
they share. (More on axes management further down.)

KDChart::Diagram subclasses for the various types of charts are provided, such as
KDChart::PieDiagram, and users can subclass KDChart::AbstractDiagram (or one of
the other Diagram classes starting with Abstract, which are designed to be base
classes) themselves to implement custom chart types. A typical use of a 
simple BarDiagram looks like this:

using namespace KDChart;

BarDiagram *bars = new BarDiagram;
bars->setModel( &m_model );
bars->setType( BarDiagram::Stacked );
bars->setDataSubduedColors(); // not bar specific
QPen pen;
pen.setColor( Qt::darkGray );
pen.setWidth( 1 );
bars->setPen( pen );
chart->coordinatePlane()->replaceDiagram( bars );

You could also use this way, to prevent your compiler from complaining
about instance bars not being free'ed:

BarDiagram *bars =
    static_cast<BarDiagram *>(myChart->replaceDiagram( new BarDiagram ));
( now call the setter methods ... )

Each diagram has an associated CoordinatePlane (cartesian, by default),
which is responsible for the translation of data values into pixel 
positions. It thus defines the scale of the diagram, and all axes that
are associated with it. This makes implementing diagram subclasses 
(types) much easier, since the drawing code can leave all of the 
coordinate calculation work to the coordinate plane. 

Each coordinate plane can have more than one diagram associated with
it, which means that those diagrams will share the scale provided by 
the plan. A chart, in turn, can have more than one coordinate plane.
This makes it possible to have multiple diagrams (a line and a bar
chart, for example) either using the same or different scales drawn
next to, or on top of each other in the same chart. Whether they are
drawn next to each other, or over each other, is determined by 
whether one of the coordinate planes is the reference plane of
the other. To share an axis among two planes (and thus diagrams)
they can simply be added to both diagrams. The Chart layouting
engine will take care of adjusting positions accordingly.

(see src/KDChartAbstractCoordinatePlane.h and
 examples/SharedAbscissa/mainwindow.cpp)

Apart from diagrams, a chart can have a number of optional components
such as Legends, Headers/Footers or custom KDChart::Area subclasses that
implement user-defined elements. The API for manipulating these is
similar for all of them.

Adding an additional header, for example, looks like this:

HeaderFooter * additionalHeader = new HeaderFooter;
additionalHeader->setPosition( NorthWest );
chart->addHeaderFooter( additionalHeader  );

See below for details on how ownership of these components is handled.

(see src/{KDChartChart.h|KDChartLegend.h|KDChartHeaderFooter.h)


Qt 4 Interview Support:
-----------------------

KD Chart 2.0 now follows the Interview model/view paradigm introduced
by Qt 4:

Any KDChart::AbstractDiagram subclass (since that is derived from
QAbstractItemView) can display data coming from any QAbstractItemModel.
That means that in order to use your data with KD Chart diagrams, you
will need to either use one of Qt's builtin models to manage your data,
or provide the QAbstractItemModel interface on top of your already 
existing data storage by implementing your own model, that talks to 
that underlying storage.

KDChart::Widget is a convenience class that provides a simpler, but
less flexible way of displaying data in a chart. It stores the data it
displays itself, and thus does not need a QAbstractItemModel. For many
basic charting needs, it should suffice, but it is, for example, not
meant to handle very large amounts of data or be able to make use of
user-supplied chart types.

KDChart::Widget is provided in order to allow getting started easily
without having to master the complexities of the new Interview
framework in Qt 4. We would still advise to use KDChart::Chart so that
you can make use of all the benefits that Interview brings you once
you have mastered it.

To understand the relationship between KDChart::View and
KDChart::Widget better, compare, for example, KDChart::View and
KDChart::Widget to QListView and QListWidget in Qt 4, and you will
clearly notice the parallels.


Attribute sets:
---------------

The various components of a chart such as legends or axes have
attribute sets associated with them that define the way they are laid
out and painted. For example, both the chart itself and all areas have
a set of KDChart::BackgroundAttributes, which govern whether there
should be a background pixmap, or a solid background color. Other
attribute sets include FrameAttributes or GridAttributes. The default
attributes provide reasonable, unintrusive defaults, such as no
visible background and no visible frame.

These attribute sets are passed by value, they are intended to be used
much like Qt's QPen or QBrush. For example:

KDChart::TextAttributes ta( chart->legend()->textAttributes() );
ta.setPen( Qt::red );
ta.setFont( QFont( "Helvetica" ) );
chart->legend()->setTextAttributes( ta );

All attribute sets can be set per cell, per column or per model, and
only be queried per cell. Access at the cell level only ensures that
the proper fallback hierarchy can be observed. If there is a value set
at cell level, it will be used, otherwise the dataset (column) level
is checked. If nothing was set at dataset level, the model wide
setting is used, and if there is none either, the default values will
be applied. All of this happens automatically, so that the code using
these values only has to ask the cell for its attributes, and will get
the correct values. This avoids duplicating the fallback logic all
over the library and the application, and avoids much (expensive)
error handling.

When using attributes sets, you need to be aware of this fallback
hierarchy, because e.g. per-cell changes will hide per-column changes.

(see files /src/KDChart*Attributes.h)


Memory Management:
-----------------

As a general rule, everything in a KDChart::Chat is owned by the
chart.  Manipulation of the built-in components of a chart, such as a
legend, happens through mutable pointers provided by the view, but
those components can also be replaced. For example:

// set the built-in (default) legend visible
view->legend()->setPosition( North );

// replace the default legend with a custom one, the view will
// take ownership of the allocated memory and free the old legend
KDChart::Legend *myLegend = view->replaceLegend( new Legend );

Similarly, inserting new components into the view chart up their
ownership.

// add an additional legend, chart takes ownership
chart->addLegend( Legend );

Removing a component does not de-allocate it. If you "take" a 
component from a chart or diagram, you are responsible for freeing
it as appropriate.

(see files /src/{KDChartChart.h, KDChartLegend.h})

Notice how this pointer-based access to the components of a chart is
different from the value-based usage of the attribute classes; the
latter can be copied around freely, and are meant to be transient
in your code; they will be copied internally as necessary. The reason
for the difference, of course, is polymorphism.

