Data Elements

We will use a C++ class called Element to provide storage and access for data elements.

(Extracts from element.h.)

    private:

        double m_value;
        QColor m_valueColor;
        int m_valuePattern;
        QString m_label;
        QColor m_labelColor;
        double m_propoints[2 * MAX_PROPOINTS];

Each element has a value. Each value is displayed graphically with a particular color and fill pattern. Values may have a label associated with them; the label is drawn using the label color and for each type of chart has a (relative) position stored in the m_propoints array.

    #include <qcolor.h>
    #include <qnamespace.h>
    #include <qstring.h>
    #include <qvaluevector.h>

Although the Element class is a purely internal data class, it #includes four Qt classes. Qt is often perceived as a purely GUI toolkit, but it provides many non-GUI classes to support most aspects of application programming. We use qcolor.h so that we can hold the paint color and text color in the Element class. The use of qnamespace.h is slightly obscure. Most Qt classes are derived from the Qt superclass which contains various enumerations. The Element class does not derive from Qt, so we need to include qnamespace.h to have access to the Qt enum names. An alternative approach would have been to have made Element a Qt subclass. We include qstring.h to make use of Qt's Unicode strings. As a convenience we will typedef a vector container for Elements, which is why we pull in the qvaluevector.h header.

    typedef QValueVector<Element> ElementVector;

Qt provides a number of containers, some value based like QValueVector, and others pointer based. (See Collection Classes.) Here we've just typedefed one container type; we will keep each data set of elements in one ElementVector.

    const double EPSILON = 0.0000001; // Must be > INVALID.

Elements may only have positive values. Because we hold values as doubles we cannot readily compare them with zero. Instead we specify a value, EPSILON, which is close to zero, and consider any value greater than EPSILON to be positive and valid.

    class Element
    {
    public:
        enum { INVALID = -1 };
        enum { NO_PROPORTION = -1 };
        enum { MAX_PROPOINTS = 3 }; // One proportional point per chart type

We define three public enums for Elements. INVALID is used by the isValid() function. It is useful because we are going to use a fixed size vector of Elements, and can mark unused Elements by giving them INVALID values. The NO_PROPORTION enum is used to signify that the user has not positioned the Element's label; any positive proportion value is taken to be the text element's position proportional to the canvas's size.

If we stored each label's actual x and y position, then every time the user resized the main window (and therefore the canvas), the text would retain its original (now incorrect) position. So instead of storing absolute (x, y) positions we store proportional positions, i.e. x/width and y/height. We can then multiply these positions by the current width and height respectively when we come to draw the text and the text will be positioned correctly regardless of any resizing. For example, if a label has an x position of 300 and the canvas is 400 pixels wide, the proportional x value is 300/400 = 0.75.

The MAX_PROPOINTS enum is problematic. We need to store the x and y proportions for the text label for every chart type. And we have chosen to store these proportions in a fixed-size array. Because of this we must specify the maximum number of proportion pairs needed. This value must be changed if we change the number of chart types, which means that the Element class is strongly coupled to the number of chart types provided by the ChartForm class. In a larger application we might have used a vector to store these points and dynamically resized it depending on how many chart types are available.

        Element( double value = INVALID, QColor valueColor = Qt::gray,
                 int valuePattern = Qt::SolidPattern,
                 const QString& label = QString::null,
                 QColor labelColor = Qt::black ) {
            init( value, valueColor, valuePattern, label, labelColor );
            for ( int i = 0; i < MAX_PROPOINTS * 2; ++i )
                m_propoints[i] = NO_PROPORTION;
        }

The constructor provides default values for all members of the Element class. New elements always have label text with no position. We use an init() function because we also provide a set() function which works like the constructor apart from leaving the proportional positions alone.

        bool isValid() const { return m_value > EPSILON; }

Since we are storing Elements in a fixed size vector we need to be able to check whether a particular element is valid (i.e. should be used in calculations and displayed) or not. This is easily achieved with the isValid() function.

(Extracts from element.cpp.)

    double Element::proX( int index ) const
    {
        Q_ASSERT(index >= 0 && index < MAX_PROPOINTS);
        return m_propoints[2 * index];
    }

Getters and setters are provided for all the members of Element. The proX() and proY() getters and the setProX() and setProY() setters take an index which identifies the type of chart the proportional position applies to. This means that the user can have labels positioned separately for the same data set for a vertical bar chart, a horizontal bar chart and for a pie chart. Note also that we use the Q_ASSERT macro to provide pre-condition tests on the chart type index; (see Debugging).

Reading and Writing Data Elements

    QTextStream &operator<<( QTextStream&, const Element& );
    QTextStream &operator>>( QTextStream&, Element& );

    #include "element.h"

    #include <qstringlist.h>
    #include <qtextstream.h>

    const char FIELD_SEP = ':';
    const char PROPOINT_SEP = ';';
    const char XY_SEP = ',';

20:#ff0000:14:#000000:0.767033,0.412946;0,0.75;0,0:Red :with colons:!
70:#00ffff:2:#ffff00:0.450549,0.198661;0.198516,0.125954;0,0.198473:Cyan
35:#0000ff:8:#555500:0.10989,0.299107;0.397032,0.562977;0,0.396947:Blue
55:#ffff00:1:#000080:0.0989011,0.625;0.595547,0.312977;0,0.59542:Yellow
80:#ff00ff:1:#000000:0.518681,0.694196;0.794063,0;0,0.793893:Magenta or Violet

    QTextStream &operator<<( QTextStream &s, const Element &element )
    {
        s << element.value() << FIELD_SEP
          << element.valueColor().name() << FIELD_SEP
          << element.valuePattern() << FIELD_SEP
          << element.labelColor().name() << FIELD_SEP;

        for ( int i = 0; i < Element::MAX_PROPOINTS; ++i ) {
            s << element.proX( i ) << XY_SEP << element.proY( i );
            s << ( i == Element::MAX_PROPOINTS - 1 ? FIELD_SEP : PROPOINT_SEP );
        }

        s << element.label() << '\n';

        return s;
    }

    QTextStream &operator>>( QTextStream &s, Element &element )
    {
        QString data = s.readLine();
        element.setValue( Element::INVALID );

        int errors = 0;
        bool ok;

        QStringList fields = QStringList::split( FIELD_SEP, data );
        if ( fields.count() >= 4 ) {
            double value = fields[0].toDouble( &ok );
            if ( !ok )
                errors++;
            QColor valueColor = QColor( fields[1] );
            if ( !valueColor.isValid() )
                errors++;
            int valuePattern = fields[2].toInt( &ok );
            if ( !ok )
                errors++;
            QColor labelColor = QColor( fields[3] );
            if ( !labelColor.isValid() )
                errors++;
            QStringList propoints = QStringList::split( PROPOINT_SEP, fields[4] );
            QString label = data.section( FIELD_SEP, 5 );

            if ( !errors ) {
                element.set( value, valueColor, valuePattern, label, labelColor );
                int i = 0;
                for ( QStringList::iterator point = propoints.begin();
                    i < Element::MAX_PROPOINTS && point != propoints.end();
                    ++i, ++point ) {
                    errors = 0;
                    QStringList xy = QStringList::split( XY_SEP, *point );
                    double x = xy[0].toDouble( &ok );
                    if ( !ok || x <= 0.0 || x >= 1.0 )
                        errors++;
                    double y = xy[1].toDouble( &ok );
                    if ( !ok || y <= 0.0 || y >= 1.0 )
                        errors++;
                    if ( errors )
                        x = y = Element::NO_PROPORTION;
                    element.setProX( i, x );
                    element.setProY( i, y );
                }
            }
        }

        return s;
    }