adding more comments to the graph stumper

Author: jlarsby

stumpers/rcmaniac25/assets/GraphView.qml

@@ -26,14 +26,20 @@ Container {
     layout: DockLayout {
     }
 
+    // A custom control for presenting custom data, see
+    // data/graph.dat and GraphControl.cpp for further detail.
     GraphControl {
         id: graph
         graphDataSource: "data/graph.dat"
+        
+        // The preferred width and height has to be set in the current implementation.
         preferredWidth: 1280 - graphContainer.leftPadding * 2
         preferredHeight: 768 - graphContainer.leftPadding * 2
     }    
 
     onTouch: {
+        // When the user release the finger on the Graph a new data set
+        // is loaded.
         if (event.isUp()) {
             if (graph.graphDataSource == "data/graph3.dat") {
                 graph.graphDataSource = "data/graph.dat"

stumpers/rcmaniac25/assets/main.qml

@@ -22,6 +22,7 @@ Page {
         layout: DockLayout {
         }
 
+        // This is the custom component containing the Graph (see GraphView.qml)
         GraphView {
         }
     }

stumpers/rcmaniac25/src/GraphControl.cpp

@@ -27,45 +27,33 @@
 using namespace bb;
 using namespace bb::cascades;
 
-/*
- * Colors:
- * light column    0F233C
- * dark column     0D1F35
- * divider lines   35475B
- * label bkg       050C14
- * graph lines     63E2D9 (thickness 3-4 px)
- *
- */
-
 GraphControl::GraphControl(Container *parent) :
         CustomControl(parent)
 {
     Container *content = new Container();
-    //content->setBackground(Color(Color::Red));
 
     // The content Container will be set to lay out children using a dock layout (to center everything on screen).
     content->setLayout(new DockLayout());
 
-    Container *xAxis = Container::create().vertical(VerticalAlignment::Bottom).horizontal(HorizontalAlignment::Fill).background(Color::fromARGB(0xff2F4C6E)).preferredHeight(5);
-    Container *yAxis = Container::create().vertical(VerticalAlignment::Fill).horizontal(HorizontalAlignment::Left).background(Color::fromARGB(0xff2F4C6E)).preferredWidth(5);
-
+    // Decoration grid only, needs adjusting to data for a more realistic implementation
+    Container *xAxis = Container::create().vertical(VerticalAlignment::Bottom).horizontal(
+            HorizontalAlignment::Fill).background(Color::fromARGB(0xff2F4C6E)).preferredHeight(5);
+    Container *yAxis = Container::create().vertical(VerticalAlignment::Fill).horizontal(
+            HorizontalAlignment::Left).background(Color::fromARGB(0xff2F4C6E)).preferredWidth(5);
     content->add(xAxis);
     content->add(yAxis);
 
-    // Decoration grid only, needs adjusting to data for a more realistic implementation
-    for(int x = 200; x < 1280; x += 200) {
-        content->add(Container::create().vertical(VerticalAlignment::Fill).background(Color::fromARGB(0xff2F4C6E)).preferredWidth(3).translate(x, 0));
+    for (int x = 200; x < 1280; x += 200) {
+        content->add(
+                Container::create().vertical(VerticalAlignment::Fill).background(
+                        Color::fromARGB(0xff2F4C6E)).preferredWidth(3).translate(x, 0));
     }
-    for(int y = 200; y < 768; y += 200) {
-        content->add(Container::create().horizontal(HorizontalAlignment::Fill).background(Color::fromARGB(0xff2F4C6E)).preferredHeight(3).translate(0, y));
+    for (int y = 200; y < 768; y += 200) {
+        content->add(
+                Container::create().horizontal(HorizontalAlignment::Fill).background(
+                        Color::fromARGB(0xff2F4C6E)).preferredHeight(3).translate(0, y));
     }
 
-    /*
-    mDebugLabel1 = Label::create().translate(30, 30).text("1");
-    mDebugLabel2 = Label::create().translate(30, 130).text("2");
-    content->add(mDebugLabel1);
-    content->add(mDebugLabel2);
-     */
     mIsCreated = false;
     connect(this, SIGNAL(creationCompleted ()), this, SLOT(onCreationCompleted ()));
 
@@ -84,6 +72,7 @@ void GraphControl::drawLine(QPoint point)
     uint width = mDrawArea->preferredWidth();
     uint height = mDrawArea->preferredHeight();
 
+    // Normalize the point to the max and min in x/y direction.
     QPoint currentPoint(((point.x() - mMinPoint.x()) * mXNormalization),
             ((point.y() - mMinPoint.y()) * mYNormalization));
 
@@ -97,7 +86,7 @@ void GraphControl::drawLine(QPoint point)
 
             if (mPreviousPoint.x() != -1 && mPreviousPoint.y() != -1
                     && mPreviousPoint != currentPoint) {
-                // A straight line
+                // Draw a straight line from the previous point
                 // y = k * x + m
                 // k = (y1-y2) / (x1 - x2)
                 // m = y1 - k * x1
@@ -108,6 +97,7 @@ void GraphControl::drawLine(QPoint point)
 
                 for (int lineX = mPreviousPoint.x(); lineX < currentPoint.x(); lineX++) {
 
+                    // Draw each point as a 4x4 square.
                     for (int i = 0; i < brushSize; i++) {
                         int brushX = lineX + i;
                         int xOffset = brushX * 4;
@@ -121,6 +111,7 @@ void GraphControl::drawLine(QPoint point)
 
                             if ((offset + 3) < arraySize) {
 
+                                // Set the fill color in the buffer at the drawing position calculated above.
                                 mBuffer[(offset)] = (0x63 * ALPHA) >> 8;
                                 mBuffer[(offset + 1)] = (0xE2 * ALPHA) >> 8;
                                 mBuffer[(offset + 2)] = (0xD9 * ALPHA) >> 8;
@@ -138,6 +129,7 @@ void GraphControl::drawLine(QPoint point)
 
 void GraphControl::generatePixels(uint width, uint height, unsigned char* buf)
 {
+    // Clear the buffer.
     for (uint y = 0; y < height; ++y) {
         for (uint x = 0; x < width; ++x) {
             buf[0] = (0xFF * 0x00) >> 8;
@@ -151,23 +143,26 @@ void GraphControl::generatePixels(uint width, uint height, unsigned char* buf)
 
 void GraphControl::setUpDrawArea(uint width, uint height)
 {
+    // Find and destroy the old ImageView used to display the Graph
     Container *content = qobject_cast<Container*>(this->root());
 
     if (content) {
-        // Remove the current recipe once we return to the ListView
         if (mDrawArea && content->remove(mDrawArea)) {
             delete mDrawArea;
         }
     }
 
+    // Create a new Image view and set up a buffer to draw to of the corresponding size
     mDrawArea = new ImageView();
     mDrawArea->setPreferredSize(width, height);
 
     if (!mBuffer) {
         mBuffer = (unsigned char*) malloc((width + 1) * height * 4);
     }
 
+    // Clear the buffer.
     generatePixels(width, height, mBuffer);
+
     content->add(mDrawArea);
 
 }
@@ -179,18 +174,17 @@ void GraphControl::drawGraph()
 
     mXNormalization = ((float) width) / (mMaxPoint.x() - mMinPoint.x());
     mYNormalization = ((float) height) / (mMaxPoint.y() - mMinPoint.y());
-
-    //mDebugLabel1->setText(QString::number( mXNormalization));
-    //mDebugLabel2->setText(QString::number( mYNormalization));
-
     setUpDrawArea(width, height);
 
     if (!mValues.isEmpty()) {
         for (int i = 0; i < mValues.size(); ++i) {
+
+            // Draws a line to the the Point in mValues.at(i) in mBuffer.
             drawLine(mValues.at(i));
         }
 
         if (mBuffer) {
+            // Create a new Image from the buffer and display it in the draw area
             Image img(
                     bb::ImageData::fromPixels(mBuffer, bb::PixelFormat::RGBA_Premultiplied, width,
                             height, width * 4));
@@ -201,7 +195,7 @@ void GraphControl::drawGraph()
 
 bool GraphControl::readGraphDataSource()
 {
-    // Now read the data from the file and plot the lines.
+    // Now read the data from the file.
     QString appFolder(QDir::homePath());
     appFolder.chop(4);
     QString dataFileName = appFolder + "app/native/assets/" + mGraphDataSource;
@@ -249,8 +243,6 @@ bool GraphControl::readGraphDataSource()
             }
             dataFile.close();
 
-
-
             return true;
         }
     } else {
@@ -263,6 +255,8 @@ void GraphControl::onCreationCompleted()
 {
     mIsCreated = true;
 
+    // To ensure all properties being set, the reading of data and drawing is
+    //delayed on the first creation of the Control.
     if (!mGraphDataSource.isEmpty()) {
         if (readGraphDataSource()) {
             drawGraph();

stumpers/rcmaniac25/src/GraphControl.h

@@ -33,29 +33,33 @@ namespace bb
 /**
  * GraphControl Description:
  * 
+ * This is a custom control that will present data contained in a file
+ * as a graph.
  */
 class GraphControl: public bb::cascades::CustomControl
 {
 Q_OBJECT
 
     /**
-     *
+     * The path to the data source to be used, needs to be a two column comma separated text file.
      */
-Q_PROPERTY(QString graphDataSource READ graphDataSource WRITE setGraphDataSource NOTIFY graphDataSourceChanged)
+    Q_PROPERTY(QString graphDataSource READ graphDataSource WRITE setGraphDataSource NOTIFY graphDataSourceChanged)
 
 public:
     GraphControl(Container *parent = 0);
     ~GraphControl();
 
     /**
+     * Sets the data source path for the Graph.
      *
-     *
-     * @param graphDataSource
+     * @param graphDataSource the path to the data source.
      */
     void setGraphDataSource(QString graphDataSource);
 
     /**
-     * @return
+     * Returns the current data source path.
+     *
+     * @return A string containing the path to the data source.
      */
     QString graphDataSource();
 
@@ -66,29 +70,30 @@ private slots:
     void onCreationCompleted();
 
 private:
+    // Functions for setting up and drawing to a pixel buffer that will
+    // visualize the graph data in an ImageView.
     void setUpDrawArea(uint width, uint height);
     void generatePixels(uint width, uint height, unsigned char* buf);
     void drawLine(QPoint currentPoint);
     void drawGraph();
     bool readGraphDataSource();
 
-    // State variables
-    int mNbrOfChars;
-
+    // Custom control components.
     ImageView *mDrawArea;
     unsigned char *mBuffer;
     QString mGraphDataSource;
+
+    // State variable
     bool mIsCreated;
-    QPoint mPreviousPoint;
 
+    // Variables used to draw lines in the pixelbuffer presented in mDrawArea
     QPoint mMaxPoint;
     QPoint mMinPoint;
     QList<QPoint> mValues;
     float mXNormalization;
     float mYNormalization;
+    QPoint mPreviousPoint;
 
-    Label *mDebugLabel1;
-    Label *mDebugLabel2;
 };
 
 #endif // ifndef _GraphControl_H_

stumpers/rcmaniac25/src/Graphs.cpp

@@ -34,6 +34,7 @@ Graphs::Graphs(bb::cascades::Application *app) :
 
     // create root object for the UI
     AbstractPane *root = qml->createRootObject<AbstractPane>();
+
     // set created root object as a scene
     app->setScene(root);
 }

stumpers/rcmaniac25/src/Graphs.hpp

@@ -26,11 +26,6 @@ namespace bb
     }
 }
 
-/*!
- * @brief Application pane object
- *
- *Use this object to create and init app UI, to create context objects, to register the new meta types etc.
- */
 class Graphs: public QObject
 {
 Q_OBJECT