
Getting Started with KD Chart 2
===============================

    The following is a step-by-step tutorial on how to get a basic
    diagram set up and displayed.
    
    KD Chart 2 was designed to fit into the Qt Interview framework
    for Model/View programming, and thus it is intented to be used
    with a QAbstractItemModel implementation providing the data to it.
    
    To reduce some of the complexity involved with that, KD Chart
    (like Qt itself) provides a convenience wrapper:
    The KDChart::Widget class can be used for straightforward
    charting use cases, especially if the data to be charted is not
    already provided by an Interview model.
    
    After some general remarks applicable to both ways of using
    KD Chart 2, the second section below describes the Widget class
    and how to use it, while the following third section of this
    guide explains the concept and basic steps of working with the
    full KD Chart 2 API.


General Information
-------------------

    All classes in the KD Chart 2 API are in the "KDChart" namespace,
    to allow short and clear class names, while still avoiding name
    clashes.
    Unless you prefer to use the "KDChart::" prefix on all class
    names in your code, you can add the following line at the top of
    your implementation files, to make all names in the "KDChart"
    namespace available in that file:
    
    using namespace KDChart;
    
    Like Qt, KD Chart provides STL-style forwarding headers, allowing
    you to omit the ".h" suffix when including headers.
    To bring the bar diagram header into your implementation flie, you
    could therefore write:
    
    #include <KDChartBarDiagram>
    
    or 
    
    #include <KDChartBarDiagram.h>
    
    Note that the file names of header and implementation files all
    have the "KDChart" prefix in the name. The defintion of
    KDChart::BarDiagram is thus in the file KDChartBarDiagram.h.
    
    
    Also note that KD Chart does not require any extra installation
    steps, you just build it from sources, as you would build any
    other Qt library.
    
    In the following we assume that $KDCHARTDIR is set to your
    KD Chart's main directory, i.e., the top directory, that is
    created, when you unpack the KD Chart distribution archive, thus
    building the library is done like this:
    
    cd $KDCHARTDIR
    qmake kdchart.pro
    make
    
    Once you have built the library, you can link your own application
    to it by adding the following lines to your .pro files:
    
    KDCHARTDIR = $$(KDCHARTDIR)
    isEmpty( KDCHARTDIR ) {
      error( "You need to set the KDCHARTDIR environment variable to point to a KD Chart installation" )
    }
    KDCHARTDIR = "$$KDCHARTDIR"
    INCLUDEPATH+= $$KDCHARTDIR/include
    DEPENDPATH += $$KDCHARTDIR/include
    LIBS      += -L$$KDCHARTDIR/lib -lkdchart
    
    ( The first one of these lines copies the value of the environment
      variable KDCHARTDIR into a qmake variable of the same name,
      and it puts " around it, which is why the "$$(..)" syntax is
      used in that line only. )


KDChart::Widget
---------------

    To use the KDChart::Widget class, you first would include the
    appropriate header file, and bring the "KDChart" namespace in:
    
    #include <KDChartWidget>
    using namespace KDChart;
    
    Add the widget to your layout just like any other QWidget:
    
        QHBoxLayout* chartLayout = new QHBoxLayout( chartFrame );
        widget = new Widget( chartFrame );
        chartLayout->addWidget( widget );
    
    The Widget can be used in one of several built-in chart type modes.
    To set it to line diagram mode, write:
    
        widget->setType( Widget::Line );
    
    For displaying one dimensional data, such as a collection of
    measurement datasets, each in a list or vector, you can use the
    following method to add the data to the charting widget:
    
        QVector< double > data;
        data << 1.1 << 2.2 << 3.3 << 4.4;
        const QString title = "First set of data";
        setDataset( column,  data,  title );
    
    If the data to plot is twodimensional (x and y values) you can use
    the setDataset() version that takes a vector of pairs of doubles,
    but otherwise works the same way.
    
    KDChart::Widget also contains methods for adding legends, headers
    or footers, and axes to the chart. To add a legend, just write:
    
        Legend* l = new Legend();
        addLegend( l );
    
    Note that the chart takes ownership of elements such as legends,
    so you must not delete them.  However, you can get the ownership
    back via the respective take function, like takeLegend( Legend* ).
    
    For more details, please refer to the KDChart::Widget API
    documentation, and look at the example code in the examples/Widget
    subdirectory of your KD Chart distribution package.


KD Chart and Interview
----------------------

    A prerequisite for using KD Chart's full API is that the data to
    be charted is provided by you through a class implementing the
    QAbstractItemModel interface.
    The following example assumes that such a model be present and
    filled with data.
    
    Before looking at code lines, let us present you a few top level
    classes of the KD Chart 2 API:
    
    The "chart" is the central widget acting as a container for all
                of the charting elements, including the diagrams
                themselves, its class is called KDChart::Chart.
    
                A "chart" can hold several coordinate planes (as of
                yet cartesian and polar coordinates are supported)
                each of which can hold several diagrams.
    
    The "coordinate plane" (often just called the "plane")
                represents the entity that is responsible for mapping
                the values into positions on the widget.
                The plane is also showing the (sub-)grid lines.
                There can be several planes per chart.
    
    The "diagram" is the actual plot, the bars, lines etc representing
                the data.
                There can be several diagrams per coordinate plane.
    
    
    Now you can build a chart!  As in the Widget-using case, you need
    to include the appropriate headers, and bring in the "KDChart"
    namespace:
    
    #include <KDChartChart>
    #include <KDChartLineDiagram>
    using namespace KDChart;
    
    Add the widget to your layout just like any other QWidget:
    
        QHBoxLayout* chartLayout = new QHBoxLayout( chartFrame );
        m_chart = new Chart();
        chartLayout->addWidget( m_chart );
    
    In this example, you only create a single line diagram,
    and use the default cartesian coordinate plane, which is already
    contained in an empty Chart.
    
        // Create a bar diagram and associate the data model with it
        m_lines = new LineDiagram();
        m_lines->setModel( &m_model );
    
        // Replace the default diagram of the default coordinate
        // plane with your newly created one.
        // Note that the plane takes ownership of the diagram,
        // so you are not allowed to delete it.
        m_chart->coordinatePlane()->replaceDiagram( m_lines );
    
    Adding elements such as axes or legends is straightforward as well:
    
        CartesianAxis *yAxis = new CartesianAxis ( m_lines );
        yAxis->setPosition ( KDChart::CartesianAxis::Left );
    
        // the diagram takes ownership of the Axis
        m_bars->addAxis( yAxis );
    
        legend = new Legend( m_lines, m_chart );
        m_chart->addLegend( legend );
    
    You can adjust and fine-tune various aspects of the diagrams,
    planes, legends, etc.
    
    Much like Qt itself, KD Chart uses a value-based approach to these
    attributes. In the case of diagrams, most aspects can be adjusted
    at three different levels of granularity.
    The QPen that is used for drawing datasets (lines, bars, etc) can
    be set either for one datapoint within a dataset, for a dataset or
    for the whole diagram, see file KDChartAbstractDiagram.h:
    
        void setPen( const QModelIndex& index, const QPen& pen );
        void setPen( int dataset, const QPen& pen );
        void setPen( const QPen& pen );
    
    To use a dark gray color for all lines in your example chart,
    you would write:
    
        QPen pen;
        pen.setColor( Qt::darkGray );
        pen.setWidth( 1 );
        m_lines->setPen( pen );
    
    Attributes that form logical groupings are combined into
    collection classes, such as GridAttributes, DataValueAttributes,
    TextAttributes, etc.
    This makes it possible to keep sets of such properties around and
    swap them in one step, based on program state.
    
    However, you might often want to adjust just one or a few of the
    default settings, rather than specifying a complete new set.
    
    Thus in most cases, using the copy constructor of the settings
    class might be appropriate, so to use a special font for drawing
    a legend, for example, you would just write:
    
        TextAttributes ta( legend->textAttributes() );
        ta.setFont( myfont );
        legend->setTextAttributes( ta );
    
    For more detailed information, please refer to the API
    documentation of the Chart, AbstractDiagram,
    AbstractCartesianDiagram, AbstractCoordinatePlane, Legend,
    CartesianAxis etc classes, and the example code in the examples
    subdirectory of your KD Chart distribution package.


Further Information
-------------------

    A more in-depth introduction to the API can be found in the file
    
        doc/KDChart-2.0-API-Introduction.
    
    To browse the API Reference Documentation  start with this file:
    
        doc/refman/index.html

