From 795cf24649f11ddbcddf689a2ef374a6de3e4ca7 Mon Sep 17 00:00:00 2001 From: Maxime Gimeno Date: Mon, 7 Sep 2015 15:44:29 +0200 Subject: [PATCH] Doxygen Documentation --- Polyhedron/demo/Polyhedron/Mainpage.md | 187 +++++++++++++++++- .../Polyhedron_demo_example_plugin.cpp | 149 +++++++++++++- .../Polyhedron_demo_plugin_interface.h | 2 +- Polyhedron/demo/Polyhedron/Scene.h | 9 +- Polyhedron/demo/Polyhedron/doxygen_config | 8 +- 5 files changed, 340 insertions(+), 15 deletions(-) diff --git a/Polyhedron/demo/Polyhedron/Mainpage.md b/Polyhedron/demo/Polyhedron/Mainpage.md index 807ecf87cac..bad715b44c9 100644 --- a/Polyhedron/demo/Polyhedron/Mainpage.md +++ b/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 : -============ \ No newline at end of file +============ +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 +#include +#include + +#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(vertices.size()/3)); + vaos[0]->release(); + program->release(); + + } + + void changed() + { + compute_elements(); + are_buffers_filled = false; + } + +private: + + std::vector 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(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 actions() const { + return QList() << 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" + +~~~~~~~~~~~~~ \ No newline at end of file diff --git a/Polyhedron/demo/Polyhedron/Polyhedron_demo_example_plugin.cpp b/Polyhedron/demo/Polyhedron/Polyhedron_demo_example_plugin.cpp index 8d1c8b69c3f..9b3a0ae9625 100644 --- a/Polyhedron/demo/Polyhedron/Polyhedron_demo_example_plugin.cpp +++ b/Polyhedron/demo/Polyhedron/Polyhedron_demo_example_plugin.cpp @@ -1 +1,148 @@ - +#include +#include +#include + +#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(vertices.size()/3)); + vaos[0]->release(); + program->release(); + + } + + void changed() + { + compute_elements(); + are_buffers_filled = false; + } + +private: + + std::vector 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(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 actions() const { + return QList() << 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" diff --git a/Polyhedron/demo/Polyhedron/Polyhedron_demo_plugin_interface.h b/Polyhedron/demo/Polyhedron/Polyhedron_demo_plugin_interface.h index 409b8c49d73..0ee2096f6d2 100644 --- a/Polyhedron/demo/Polyhedron/Polyhedron_demo_plugin_interface.h +++ b/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. //! diff --git a/Polyhedron/demo/Polyhedron/Scene.h b/Polyhedron/demo/Polyhedron/Scene.h index 446cf88b342..76ec5bd598e 100644 --- a/Polyhedron/demo/Polyhedron/Scene.h +++ b/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. diff --git a/Polyhedron/demo/Polyhedron/doxygen_config b/Polyhedron/demo/Polyhedron/doxygen_config index 991ec17e6e3..ceea50a76e4 100644 --- a/Polyhedron/demo/Polyhedron/doxygen_config +++ b/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