Doxygen Documentation

Polyhedron/demo/Polyhedron/Mainpage.md

@@ -19,12 +19,189 @@ A plugin usually defines an object that inherits from Scene_item or uses some of
 Creating a simple Plugin
 ============
 A basic plugin will inherit from Polyhedron_demo_plugin_interface. It can also inherits from the Polyhedron_demo_plugin_helper instead, for a more detailed model of plugin.
-Its name must be of the form Polyhedron_demo_xxxx_yyyy_plugin. The next steps will assume the plugin's name is Polyhedron_demo_example_plugin
+Its name must be of the form Polyhedron_demo_xxxx_yyyy_plugin. 
 In the CMakeList.txt file, in the section Plugins, add the following lines :
-  polyhedron_demo_plugin(example_plugin Polyhedron_demo_example_plugin)
-  target_link_libraries(example_plugin scene_polyhedron_item)
-It can get a reference to the Scene through the Scene_interface type, and to the MainWindow through the basic QMainWindow type. 
+
+    polyhedron_demo_plugin(xxxx_yyyy_plugin Polyhedron_demo_xxxx_yyyy_plugin)
+    target_link_libraries(xxxx_yyyy_plugin scene_polyhedron_item) 
+  
+  [init]: @ref Polyhedron_demo_plugin_helper#init(QMainWindow *, Scene_interface *)
+  The class must contain the following lines :
+    Q_OBJECT
+    Q_INTERFACES(Polyhedron_demo_plugin_interface)
+    Q_PLUGIN_METADATA(IID "com.geometryfactory.PolyhedronDemo.PluginInterface/1.0")
+In the function [init], get a reference to the Scene  and to the MainWindow. Then, create and link the actions of the plugin.
+Create a list of QActions containing the actions of the plugin.
 If the plugin implements a new Scene_item, please notice that a Scene_itam have a number of functions that will need a reference to the Viewer through the Viewer_interface type.
 
+A plugin must always contain
+~~~~~~~~~~~~~{.cpp}
+#include "Polyhedron_demo_xxxx_yyyy_plugin.moc"
+~~~~~~~~~~~~~
+
+List of useful classes :
+========================
+- MainWindow
+- Viewer_interface
+- Scene_interface
+- Scene_item
+- Polyhedron_demo_plugin_helper
+- Polyhedron_demo_plugin_interface
+
+
 Example : 
-============
+============
+The following code will create a plugin that adds an action to the MainWindow. This action is called "Draw Triangle" and adds a triangle to the scene.
+
+
+~~~~~~~~~~~~~{.cpp}
+#include <QApplication>
+#include <QMainWindow>
+#include <QAction>
+
+#include "Scene_item.h"
+#include "Viewer_interface.h"
+class Q_DECL_EXPORT Scene_triangle_item : public Scene_item
+{
+
+    Q_OBJECT
+public :
+    Scene_triangle_item()
+        :  Scene_item(1,1)
+    {
+
+        vertices.resize(0);
+        changed();
+
+    }
+    ~Scene_triangle_item()
+    {
+    }
+    bool isFinite() const { return true; }
+    bool isEmpty() const { return true; }
+    Bbox bbox() const { return Bbox(); }
+
+    Scene_triangle_item* clone() const {
+        return 0;
+    }
+
+    // Indicate if rendering mode is supported
+    bool supportsRenderingMode(RenderingMode m) const {
+        return (m == Flat);
+    }
+
+    QString toolTip() const {
+    }
+
+    void draw(Viewer_interface* viewer) const
+    {
+        if(!are_buffers_filled)
+            initialize_buffers(viewer);
+        vaos[0]->bind();
+        program = getShaderProgram(PROGRAM_WITH_LIGHT);
+        attrib_buffers(viewer, PROGRAM_WITH_LIGHT);
+        program->bind();
+        program->setAttributeValue("colors", this->color());
+        viewer->glDrawArrays(GL_TRIANGLES, 0, static_cast<GLsizei>(vertices.size()/3));
+        vaos[0]->release();
+        program->release();
+
+    }
+
+    void changed()
+    {
+        compute_elements();
+        are_buffers_filled = false;
+    }
+
+private:
+
+    std::vector<float> vertices;
+    mutable QOpenGLShaderProgram *program;
+    using Scene_item::initialize_buffers;
+    void initialize_buffers(Viewer_interface *viewer)const
+    {
+
+        //vao containing the data for the lines
+        {
+            program = getShaderProgram(PROGRAM_WITH_LIGHT, viewer);
+            program->bind();
+
+            vaos[0]->bind();
+            buffers[0].bind();
+            buffers[0].allocate(vertices.data(),
+                                static_cast<GLsizei>(vertices.size()*sizeof(float)));
+            program->enableAttributeArray("vertex");
+            program->setAttributeBuffer("vertex",GL_FLOAT,0,3);
+            buffers[0].release();
+
+            vaos[0]->release();
+            program->release();
+
+        }
+        are_buffers_filled = true;
+    }
+
+    void compute_elements()
+    {
+        vertices.resize(9);
+        vertices[0] = 0.0; vertices[1] = 0.0; vertices[2] = 0.0;
+        vertices[3] = 0.5; vertices[4] = 1.0; vertices[5] = 0.0;
+        vertices[6] = 1.0; vertices[7] = 0.0; vertices[8] = 0.0;
+    }
+
+}; //end of class Scene_triangle_item
+
+#include "Polyhedron_demo_plugin_helper.h"
+class Polyhedron_demo_example_plugin :
+        public QObject,
+        public Polyhedron_demo_plugin_helper
+{
+    //Configures CMake to use MOC correctly
+    Q_OBJECT
+    Q_INTERFACES(Polyhedron_demo_plugin_interface)
+    Q_PLUGIN_METADATA(IID "com.geometryfactory.PolyhedronDemo.PluginInterface/1.0")
+
+
+public :
+    // To silent a warning -Woverloaded-virtual
+    // See http://stackoverflow.com/questions/9995421/gcc-woverloaded-virtual-warnings
+    using Polyhedron_demo_plugin_helper::init;
+
+    void init(QMainWindow* mainWindow,
+              Scene_interface* scene_interface) {
+      //get the references
+      this->scene = scene_interface;
+      this->mw = mainWindow;
+      //creates and link the actions
+      actionDrawTriangle= new QAction("Draw Triangle", mw);
+      if(actionDrawTriangle) {
+        connect(actionDrawTriangle, SIGNAL(triggered()),
+                this, SLOT(draw_triangle()));
+      }
+    }
+
+    bool applicable(QAction*) const
+    {
+        return true;
+    }
+    QList<QAction*> actions() const {
+      return QList<QAction*>() << actionDrawTriangle;
+    }
+
+  public Q_SLOTS:
+
+  void draw_triangle() {
+    triangle = new Scene_triangle_item();
+    scene->addItem(triangle);
+  }
+
+private:
+  Scene_item* triangle;
+  QAction* actionDrawTriangle;
+
+}; //end of class Polyhedron_demo_example_plugin
+
+#include "Polyhedron_demo_example_plugin.moc"
+
+~~~~~~~~~~~~~

Polyhedron/demo/Polyhedron/Polyhedron_demo_example_plugin.cpp

@@ -1 +1,148 @@
- 
+#include <QApplication>
+#include <QMainWindow>
+#include <QAction>
+
+#include "Scene_item.h"
+#include "Viewer_interface.h"
+class Q_DECL_EXPORT Scene_triangle_item : public Scene_item
+{
+
+    Q_OBJECT
+public :
+    Scene_triangle_item()
+        :  Scene_item(1,1)
+    {
+
+        vertices.resize(0);
+        changed();
+
+    }
+    ~Scene_triangle_item()
+    {
+    }
+    bool isFinite() const { return true; }
+    bool isEmpty() const { return true; }
+    Bbox bbox() const { return Bbox(); }
+
+    Scene_triangle_item* clone() const {
+        return 0;
+    }
+
+    // Indicate if rendering mode is supported
+    bool supportsRenderingMode(RenderingMode m) const {
+        return (m == Flat);
+    }
+
+    QString toolTip() const {
+    }
+
+    void draw(Viewer_interface* viewer) const
+    {
+        if(!are_buffers_filled)
+            initialize_buffers(viewer);
+        vaos[0]->bind();
+        program = getShaderProgram(PROGRAM_WITH_LIGHT);
+        attrib_buffers(viewer, PROGRAM_WITH_LIGHT);
+        program->bind();
+        program->setAttributeValue("colors", this->color());
+        viewer->glDrawArrays(GL_TRIANGLES, 0, static_cast<GLsizei>(vertices.size()/3));
+        vaos[0]->release();
+        program->release();
+
+    }
+
+    void changed()
+    {
+        compute_elements();
+        are_buffers_filled = false;
+    }
+
+private:
+
+    std::vector<float> vertices;
+    mutable QOpenGLShaderProgram *program;
+    using Scene_item::initialize_buffers;
+    void initialize_buffers(Viewer_interface *viewer)const
+    {
+
+        //vao containing the data for the lines
+        {
+            program = getShaderProgram(PROGRAM_WITH_LIGHT, viewer);
+            program->bind();
+
+            vaos[0]->bind();
+            buffers[0].bind();
+            buffers[0].allocate(vertices.data(),
+                                static_cast<GLsizei>(vertices.size()*sizeof(float)));
+            program->enableAttributeArray("vertex");
+            program->setAttributeBuffer("vertex",GL_FLOAT,0,3);
+            buffers[0].release();
+
+            vaos[0]->release();
+            program->release();
+
+        }
+        are_buffers_filled = true;
+    }
+
+    void compute_elements()
+    {
+        vertices.resize(9);
+        vertices[0] = 0.0; vertices[1] = 0.0; vertices[2] = 0.0;
+        vertices[3] = 0.5; vertices[4] = 1.0; vertices[5] = 0.0;
+        vertices[6] = 1.0; vertices[7] = 0.0; vertices[8] = 0.0;
+    }
+
+}; //end of class Scene_triangle_item
+
+#include "Polyhedron_demo_plugin_helper.h"
+class Polyhedron_demo_example_plugin :
+        public QObject,
+        public Polyhedron_demo_plugin_helper
+{
+    //Configures CMake to use MOC correctly
+    Q_OBJECT
+    Q_INTERFACES(Polyhedron_demo_plugin_interface)
+    Q_PLUGIN_METADATA(IID "com.geometryfactory.PolyhedronDemo.PluginInterface/1.0")
+
+
+public :
+    // To silent a warning -Woverloaded-virtual
+    // See http://stackoverflow.com/questions/9995421/gcc-woverloaded-virtual-warnings
+    using Polyhedron_demo_plugin_helper::init;
+
+    void init(QMainWindow* mainWindow,
+              Scene_interface* scene_interface) {
+      //get the references
+      this->scene = scene_interface;
+      this->mw = mainWindow;
+      //creates and link the actions
+      actionDrawTriangle= new QAction("Draw Triangle", mw);
+      if(actionDrawTriangle) {
+        connect(actionDrawTriangle, SIGNAL(triggered()),
+                this, SLOT(draw_triangle()));
+      }
+    }
+
+    bool applicable(QAction*) const
+    {
+        return true;
+    }
+    QList<QAction*> actions() const {
+      return QList<QAction*>() << actionDrawTriangle;
+    }
+
+  public Q_SLOTS:
+
+  void draw_triangle() {
+    triangle = new Scene_triangle_item();
+    scene->addItem(triangle);
+  }
+
+private:
+  Scene_item* triangle;
+  QAction* actionDrawTriangle;
+
+}; //end of class Polyhedron_demo_example_plugin
+
+#include "Polyhedron_demo_example_plugin.moc"

Polyhedron/demo/Polyhedron/Polyhedron_demo_plugin_interface.h

@@ -22,7 +22,7 @@ public:
   }
 
   //! Checks the current state of the `Scene` or `MainWindow` and decides
-  //! if the plugin can function, given that state.  It's actions are
+  //! if the plugin can function, given that state.  Its actions are
   //! visible in contextmenus, if this returns true, not visible
   //! otherwise.  
   //!

Polyhedron/demo/Polyhedron/Scene.h

@@ -46,7 +46,8 @@ public:
   //!Adds item to the items list, gives it an ID and
   //!updates the bounding box if needed.
   int addItem(Scene_item* item);
-  //!Sets item as the item at index and calls item->changed().
+  //!Sets item as the item at index and calls @ref Scene_item#changed().
+
   //!If emit_item_about_to_be_destroyed is set to true, emits
   //!an itemAboutToBeDestroyed signal.
   Scene_item* replaceItem(int index, Scene_item* item, bool emit_item_about_to_be_destroyed = false);
@@ -152,15 +153,15 @@ public:
 public Q_SLOTS:
   /*! This is an overloaded function.
    * Notifies the scene that the sender item was modified.
-   * Called by the items. Calls item->changed();
+   * Called by the items. Calls @ref Scene_item#changed().
    * This function is called by the items.*/
   void itemChanged();
   /*! Notifies the scene that the item at index i was modified.
-   * Called by the items. Calls item->changed();
+   * Called by the items. Calls @ref Scene_item#changed().
    * This function is called by the items.*/
   void itemChanged(int i); 
   /*! Notifies the scene that the item was modified.
-   *  Calls item->changed();
+   *  Calls @ref Scene_item#changed().
    * This function is called by the items.*/
   void itemChanged(Scene_item*);
   //! Sets the selected item to the target index.

Polyhedron/demo/Polyhedron/doxygen_config

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = /home/mgimeno/Bureau
+OUTPUT_DIRECTORY       = 
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -98,7 +98,7 @@ OUTPUT_LANGUAGE        = English
 # documentation (similar to Javadoc). Set to NO to disable this.
 # The default value is: YES.
 
-BRIEF_MEMBER_DESC      = YES
+BRIEF_MEMBER_DESC      = NO
 
 # If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief
 # description of a member or function before the detailed description
@@ -765,7 +765,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = /home/mgimeno/cgal-gsoc/Polyhedron/demo/Polyhedron/CGAL_demo/ /home/mgimeno/cgal-gsoc/Polyhedron/demo/Polyhedron/
+INPUT                  = ./CGAL_demo/ ./
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1571,7 +1571,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of