Rename wrapper/core variables to document.

Rename AXRCore to AXRDocument and rename its files from AXRInitializer.*
to AXRDocument.*

Update some related documentation.

This work is part of #169.

src/TEST/AXRTestProducer.cpp

@@ -42,16 +42,16 @@
  ********************************************************************/
 
 #include "AXRDebugging.h"
-#include "AXRInitializer.h"
+#include "AXRDocument.h"
 #include "AXRTestProducer.h"
 #include "AXRTestRunner.h"
 
 using namespace AXR;
 
 // Constructor with name and the queue to use
-AXRTestProducer::AXRTestProducer(AXRTestRunner * wrapper, std::vector<QUrl> test, unsigned * totalTests, unsigned * totalPassed, HSSContainer::p status)
+AXRTestProducer::AXRTestProducer(AXRTestRunner *runner, std::vector<QUrl> test, unsigned * totalTests, unsigned * totalPassed, HSSContainer::p status)
 {
-    this->wrapper = wrapper;
+    this->runner = runner;
     this->test = test;
     this->totalPassed = totalPassed;
     this->totalTests = totalTests;
@@ -76,16 +76,16 @@ void AXRTestProducer::operator () ()
     AXRString expectedRep;
 
     //load the XML
-    AXRCore *core = AXRCore::getInstance();
+    AXRDocument *document = AXRDocument::getInstance();
 
-    testLoaded = core->loadXMLFile(this->test[0]);
+    testLoaded = document->loadXMLFile(this->test[0]);
 
     if (testLoaded)
     {
-        AXRController::p controller = core->getController();
+        AXRController::p controller = document->getController();
         HSSContainer::p root = controller->getRoot();
-        core->getRender()->windowWidth = 400.;
-        core->getRender()->windowHeight = 400.;
+        document->getRender()->windowWidth = 400.;
+        document->getRender()->windowHeight = 400.;
         root->recursiveReadDefinitionObjects();
         root->recursiveLayout();
         testRep = root->toString();
@@ -99,7 +99,7 @@ void AXRTestProducer::operator () ()
     //load the "expected" file
     if (testLoaded)
     {
-        AXRBuffer::p expectedFile = core->getFile(test[1]);
+        AXRBuffer::p expectedFile = document->getFile(test[1]);
         if (!expectedFile->isValid())
         {
             std_log("could not load file with expected results");
@@ -125,7 +125,7 @@ void AXRTestProducer::operator () ()
         this->statusMutex.lock();
         this->status->setContentText(AXRString("Passed %1 out of %2").arg(*this->totalPassed).arg(*this->totalTests));
         this->statusMutex.unlock();
-        core->setNeedsDisplay(true);
+        document->setNeedsDisplay(true);
     }
     else
     {

src/TEST/AXRTestProducer.h

@@ -56,7 +56,7 @@ namespace AXR
     class AXR_API AXRTestProducer : public QRunnable
     {
     private:
-        AXRTestRunner * wrapper;
+        AXRTestRunner *runner;
         std::vector<QUrl> test; // the filename of the test
         unsigned * totalTests;
         unsigned * totalPassed;
@@ -66,7 +66,7 @@ namespace AXR
         static QMutex statusMutex;
 
     public:
-        AXRTestProducer(AXRTestRunner *testRunner, std::vector<QUrl> test, unsigned * totalTests, unsigned * totalPassed, HSSContainer::p status);
+        AXRTestProducer(AXRTestRunner *runner, std::vector<QUrl> test, unsigned * totalTests, unsigned * totalPassed, HSSContainer::p status);
         void operator () ();
         void run();
     };

src/TEST/AXRTestRunner.cpp

@@ -46,7 +46,7 @@
 #include <QFile>
 #include <QUrl>
 #include "AXRDebugging.h"
-#include "AXRInitializer.h"
+#include "AXRDocument.h"
 #include "AXRTestThread.h"
 #include "AXRTestRunner.h"
 #include "AXRWarning.h"
@@ -77,8 +77,8 @@ AXRString AXRTestRunner::getPathToTestsFile()
 void AXRTestRunner::executeLayoutTests(HSSObservableProperty passnull, void*data)
 {
     HSSContainer::p status;
-    AXRCore* core = AXRCore::getInstance();
-    HSSContainer::p root = core->getController()->getRoot();
+    AXRDocument* document = AXRDocument::getInstance();
+    HSSContainer::p root = document->getController()->getRoot();
     std::deque<HSSParserNode::p> arguments = *(std::deque<HSSParserNode::p>*)data;
 
     for (std::deque<HSSParserNode::p>::iterator it = arguments.begin(); it != arguments.end(); ++it)

src/TEST/AXRTestRunner.h

@@ -41,8 +41,8 @@
  *
  ********************************************************************/
 
-#ifndef AXRWRAPPER_H
-#define AXRWRAPPER_H
+#ifndef AXRTESTRUNNER_H
+#define AXRTESTRUNNER_H
 
 #include <QMap>
 #include <QMutex>
@@ -56,22 +56,11 @@
 
 namespace AXR
 {
-    /**
-     *  @brief This is the abstract superclass from with all OS-specific wrappers
-     *  should inherit from.
-     */
     class AXR_API AXRTestRunner
     {
     public:
-        /**
-         *  Creates a new instance of the wrapper. It will obtain the singleton instance of
-         *  the AXRCore and initialize it.
-         */
         AXRTestRunner();
 
-        /**
-         *  Destructs the wrapper
-         */
         virtual ~AXRTestRunner();
 
         virtual AXRString getPathToTestsFile();

src/TEST/AXRTestThread.cpp

@@ -42,17 +42,17 @@
  ********************************************************************/
 
 #include "AXRDebugging.h"
-#include "AXRInitializer.h"
+#include "AXRDocument.h"
 #include "AXRTestProducer.h"
 #include "AXRTestRunner.h"
 #include "AXRTestThread.h"
 #include "HSSContainer.h"
 
 using namespace AXR;
 
-AXRTestThread::AXRTestThread(AXRTestRunner * wrapper, QUrl url, HSSContainer::p status)
+AXRTestThread::AXRTestThread(AXRTestRunner *runner, QUrl url, HSSContainer::p status)
 {
-    this->wrapper = wrapper;
+    this->runner = runner;
     this->url = url;
     this->totalPassed = 0;
     this->totalTests = 0;
@@ -69,16 +69,16 @@ void AXRTestThread::operator () ()
     try
     {
         //load the XML file
-        AXRCore* core = AXRCore::getInstance();
-        XMLParser::p parser = core->getParserXML();
+        AXRDocument* document = AXRDocument::getInstance();
+        XMLParser::p parser = document->getParserXML();
         HSSContainer::p status = this->status;
-        AXRBuffer::p testsFile = core->getFile(this->url);
+        AXRBuffer::p testsFile = document->getFile(this->url);
         bool loadingSuccess = parser->loadFile(testsFile);
         if (loadingSuccess)
         {
             //find all the tests that need to be executed
             std::vector<std::vector<QUrl> > tests;
-            AXRController::p controller = core->getController();
+            AXRController::p controller = document->getController();
             HSSContainer::p root = controller->getRoot();
             const std::vector<HSSDisplayObject::p> & children = root->getChildren(true);
 
@@ -102,7 +102,7 @@ void AXRTestThread::operator () ()
 
             for (std::vector<std::vector<QUrl> >::iterator it2 = tests.begin(); it2 != tests.end(); ++it2)
             {
-                AXRTestProducer prdcr(this->wrapper, *it2, &this->totalTests, &this->totalPassed, status);
+                AXRTestProducer prdcr(this->runner, *it2, &this->totalTests, &this->totalPassed, status);
                 producers.start(&prdcr);
                 QThread::yieldCurrentThread();
             }

src/TEST/AXRTestThread.h

@@ -55,14 +55,14 @@ namespace AXR
     class AXR_API AXRTestThread : public QThread
     {
     private:
-        AXRTestRunner *wrapper;
+        AXRTestRunner *runner;
         QUrl url;
         unsigned totalTests;
         unsigned totalPassed;
         HSSContainer::p status;
 
     public:
-        AXRTestThread(AXRTestRunner *testRunner, QUrl url, HSSContainer::p status);
+        AXRTestThread(AXRTestRunner *runner, QUrl url, HSSContainer::p status);
         void operator () ();
         void run();
     };

src/cocoa/AXRView.h

@@ -45,7 +45,7 @@
 
 namespace AXR
 {
-    class AXRCore;
+    class AXRDocument;
 }
 
 /**
@@ -55,13 +55,13 @@ namespace AXR
 @interface AXRView : NSView
 {
 @private
-    AXR::AXRCore *document;
+    AXR::AXRDocument *document;
 }
 
 /**
  * The AXR document being rendered by the view.
  */
-@property(assign) AXR::AXRCore* document;
+@property(assign) AXR::AXRDocument* document;
 
 /**
  *  @return YES. This is for optimizing the drawing.

src/cocoa/AXRView.mm

@@ -45,7 +45,7 @@
 #import <QPixmap>
 #import "AXRController.h"
 #import "AXRDebugging.h"
-#import "AXRInitializer.h"
+#import "AXRDocument.h"
 #import "AXRView.h"
 #import "HSSContainer.h"
 #import "HSSEvent.h"

src/core/AXRGlobal.h

@@ -41,6 +41,106 @@
  *
  ********************************************************************/
 
+/**
+ *  @mainpage AXR Prototype Documentation Overview
+ *
+ *  Welcome to the documentation of the AXR prototype! It was automatically generated from the
+ *  JavaDoc-style comment blocks that are in the header (.h) files, with a tool called Doxygen.
+ *
+ *  The goal of this document is to provide an overview of how the code is structured, how the
+ *  different classes relate to each other and, in general terms, how text files containing
+ *  source code is transformed into pixels on screen at the end.
+ *
+ *  Most of the code is C++, which was chosen because of wide interoperability and existence of
+ *  libraries and resources, as well as the native speed and fine grained control when flipping
+ *  bits a rendering engine needs.
+ *
+ *  We manage the code via GitHub, as well as the issues for bugs and stuff like that. If you'd
+ *  like to contribute, you should create a GitHub account if you don't have one already and
+ *  then click the "Fork" button on https://github.com/AXR/Prototype. You then need to download,
+ *  or "clone" the repository to your computer (install git if you don't have it already).
+ *  Execute the following commands in the command line:
+ *
+ *  cd path/to/directory
+ *  git clone https://github.com/yourusername/Prototype.git
+ *
+ *  @section folders Diving into the folder structure
+ *
+ *  Let's have a look at what's inside the repository folder:
+ *
+ *  - src/core: this is the core library of the rendering engine
+ *  - src/app: prototype application used to test AXE's functionality
+ *  - tests: this is a bunch of XML and HSS files that were used when developing the library
+ *
+ *  In Xcode you can use Interface Builder and make a custom view to be of the AXRView class
+ *  and interact with it directly.
+ *
+ *  Now let's focus on the core. In it we find the AXR.h file that contains the AXRDocument class,
+ *  which encapsulates the library, and the following folders:
+ *
+ *  - axr: Here we find the guts of the library which is not related to one specific language
+ *  but manage stuff across the rendering engine.
+ *  - hss: In here we find the HSS parser, the parser nodes and all the object types.
+ *  - xml: In here we find the XML parser
+ *
+ *  @section parsing Parsing the content and getting up and runnig
+ *
+ *  So you will probably be wondering, where do we start? This of course depends on how you
+ *  are embedding it, but in a general sense, you will create an \a AXRDocument instance
+ *  and then tell it to load a file by pathname. When the path is to a XML file, it gets the
+ *  file and sets it on the core, then calls the run() method on it. If it is to an HSS file,
+ *  it will create a dummy XML file on the fly, which contains only one element called "root".
+ *
+ *  So now let's jump to AXRDocument.cpp, and have a look at the run() method. It gives the XML
+ *  file to the XML parser. We currently use Qt, and the file XMLParser.cpp parses the
+ *  elements and adds them on axr/AXRController.cpp using enterElement(), addAttribute(),
+ *  appendContentText() and exitElement().
+ *
+ *  When it finds an XML instruction it will parse it and if it is a link to a HSS stylesheet
+ *  it calls loadSheetsAdd() on the controller to take note. Which brings us back to
+ *  AXRDocument::run(), where we now pass all the stylesheets that were found to the HSS parser.
+ *
+ *  Similarly to how the XMl parser does, the hss/parsing/HSSParser.cpp calls rulesAdd(),
+ *  parserTreeAdd(), and objectTreeAdd() on the controller, and then we loop over the found
+ *  rules and recursively match them to the content tree. On each of the matched elements,
+ *  setNeedsRereadRules(true) is called, so that before the next (and first) time we draw, the
+ *  properties from the rules are passed into each "definition object setter" (those which look
+ *  like setD<propertynamehere>()), where they will be stored according to the value type that
+ *  is passed.
+ *
+ *  @section drawing Drawing on screen
+ *
+ *  Currently for drawing we are using Qt.
+ *
+ *  When the OS asks for drawing, it is the duty of the client app to tell the core to draw in a given
+ *  rectangle (the current implementation still always redraws the whole screen, though), which will then
+ *  get get to the AXRRender class. This one will check if the window size has changed, and if so change
+ *  the width and height of the root object. It will then tell the root element to recursively read the
+ *  "definition objects", which are the HSSParserNodes that hold the values (inside property definitions,
+ *  which in turn are inside the rules that are associated with the elements) into the instance
+ *  variables that hold the actual calculated values that will determine how and where the stuff is rendered.
+ *
+ *  Next, it tells it to recursively layout, which is a process in which display objects arrange the things
+ *  that are inside, such as text in the case of HSSTextBlock elements or other display objects in the case of
+ *  HSSContainer.
+ *
+ *  Then it will regenerate all the surfaces as needed and finally it will tell it to draw, also as a
+ *  recursive operation, and finally composites all the individual surfaces of the objects into the final
+ *  surface which is retrieved by the client and blitted onto the screen in an OS and toolkit-dependent manner.
+ *
+ *  In the process of drawing, each object type which draws (display objects) implements and handles
+ *  all the properties inside to calculate the visual rendering, each generating bitmap surfaces for the
+ *  background, borders, etc, and finally compositing it all together.
+ *
+ *  This is all done in a pretty straightforward an naïve way, and should receive quite a lot of facelifting
+ *  and perfomance improvements in the near future.
+ *
+ *  @section diagram Diagram of the structure of the library
+ *
+ *  In the following diagram you can see a graphical representation of how the AXR core library is structured:
+ *  @image html library-structure.jpg
+ */
+
 #ifndef AXRGLOBAL_H
 #define AXRGLOBAL_H
 

src/core/axr/AXRController.cpp

@@ -43,7 +43,7 @@
 
 #include "AXRController.h"
 #include "AXRDebugging.h"
-#include "AXRInitializer.h"
+#include "AXRDocument.h"
 #include "AXRWarning.h"
 #include "HSSDisplayObject.h"
 #include "HSSFlag.h"
@@ -53,8 +53,8 @@
 
 using namespace AXR;
 
-AXRController::AXRController(AXRCore *core)
-: core(core)
+AXRController::AXRController(AXRDocument *document)
+: document_(document)
 {
     axr_log(AXR_DEBUG_CH_GENERAL | AXR_DEBUG_CH_GENERAL_SPECIFIC, "AXRController: creating controller");
     this->currentContext = std::stack<HSSContainer::p > ();
@@ -70,9 +70,9 @@ AXRController::~AXRController()
     this->parserTree.clear();
 }
 
-AXRCore* AXRController::document() const
+AXRDocument* AXRController::document() const
 {
-    return core;
+    return document_;
 }
 
 void AXRController::matchRulesToContentTree()
@@ -691,7 +691,7 @@ HSSContainer::p & AXRController::getRoot()
 void AXRController::setRoot(HSSContainer::p newRoot)
 {
     this->root = newRoot;
-    HSSParser::p hssparser = this->core->getParserHSS();
+    HSSParser::p hssparser = this->document()->getParserHSS();
     if (hssparser->currentObjectContextSize() == 0)
     {
         hssparser->currentObjectContextAdd(newRoot);