Update of the API and of the doc

Polyhedron/demo/Polyhedron/MainWindow.h

@@ -70,6 +70,7 @@ public:
   CGAL::Three::Scene_item* load_item(QFileInfo fileinfo, CGAL::Three::Polyhedron_demo_io_plugin_interface*);
 
 public Q_SLOTS:
+  //!Creates a new group and adds it to the scene.
   void make_new_group();
   void updateViewerBBox();
   void open(QString);

Polyhedron/demo/Polyhedron/Scene.cpp

@@ -51,8 +51,8 @@ Scene::addItem(CGAL::Three::Scene_item* item)
 {
     CGAL::Three::Scene_group_item* group =
             qobject_cast<CGAL::Three::Scene_group_item*>(item);
-  if(group)
+    if(group)
-    m_group_entries.prepend(group);
+        m_group_entries.prepend(group);
     Bbox bbox_before = bbox();
     m_entries.push_back(item);
     connect(item, SIGNAL(itemChanged()),

Polyhedron/demo/Polyhedron/Scene.h

@@ -173,10 +173,7 @@ public Q_SLOTS:
   void itemChanged(CGAL::Three::Scene_item*);
   //!Removes item from all the groups of the scene.
   void remove_item_from_groups(CGAL::Three::Scene_item* item);
-  /*! Called by the action "add new group". Adds a new group to the Scene. If items were selected at the
+
-   * moment this function is called, they are added to the group.
-   * If all the selected items were in the same group, the new group
-   * is added as a sub-group of this group.*/
   void add_group(Scene_group_item* group);
   //!Re-organizes the sceneView.
   void group_added();

Three/demo/Three/Example_plugin/Polyhedron_demo_example_plugin.cpp

@@ -9,13 +9,14 @@
 #include "ui_Polyhedron_demo_example_plugin.h"
 #include "ui_dock_example.h"
 
+//Helps Windows to manage its dll
 #ifdef scene_triangle_item_EXPORTS
 #  define SCENE_TRIANGLE_ITEM_EXPORT Q_DECL_EXPORT
 #else
 #  define SCENE_TRIANGLE_ITEM_EXPORT Q_DECL_IMPORT
 #endif
 
-//! The dialog class to get the coordinates of the triangle
+// The dialog class to get the coordinates of the triangle
 class Polyhedron_demo_example_plugin_dialog : public QDialog, private Ui::Polyhedron_demo_example_plugin_dialog
 {
   Q_OBJECT
@@ -40,7 +41,7 @@ class Polyhedron_demo_example_plugin_dialog : public QDialog, private Ui::Polyhe
     void setTriangleName(QString name) {triangle_name_label->setText(name); }
 };
 
-//! The special Scene_item only for triangles
+// The special Scene_item only for triangles
 class SCENE_TRIANGLE_ITEM_EXPORT Scene_triangle_item : public CGAL::Three::Scene_item
 {
 
@@ -51,6 +52,7 @@ public :
                         double cx,double cy, double cz)
         :  CGAL::Three::Scene_item(1,1)
     {
+        //Fills the position vector with data.
         vertices.resize(9);
         vertices[0] = ax; vertices[1] = ay; vertices[2] = az;
         vertices[3] = bx; vertices[4] = by; vertices[5] = bz;
@@ -74,12 +76,11 @@ public :
     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
+    // Indicated if rendering mode is supported
     bool supportsRenderingMode(RenderingMode m) const {
         return (m == Flat);
     }
@@ -89,12 +90,9 @@ public :
              QObject::tr( "<p>Number of vertices: %1<br />"
                            "Number of edges: %2<br />"
                          "Number of facets: %3")
-                .arg(this->name())
                 .arg(3)
                 .arg(3)
-                .arg(1)
+                .arg(1);
-                .arg(this->renderingModeName())
-                .arg(this->color().name());
         str+=QObject::tr("<br />Volume: %1").arg(0);
         str+=QObject::tr("<br />Area: %1").arg(0.5);
       str+="</p>";
@@ -112,29 +110,41 @@ public :
 
     void draw(CGAL::Three::Viewer_interface* viewer) const
     {
+        //Initializes the buffers only when specified.
         if(!are_buffers_filled)
             initialize_buffers(viewer);
+        //Binds the vao corresponding to the type of data we are drawing.
         vaos[0]->bind();
+        //Gets the program corresponding to the type of data we are drawing.
+        //Here we want triangles with light effects.
         program = getShaderProgram(PROGRAM_WITH_LIGHT);
+        //Gives most of the uniform values to the shaders.
         attrib_buffers(viewer, PROGRAM_WITH_LIGHT);
+        //Binds the program chosen before to use the right shaders.
         program->bind();
+        //Gives the wanted color to the fragment shader as uniform value.
         program->setAttributeValue("colors", this->color());
+        //Draws the items
         viewer->glDrawArrays(GL_TRIANGLES, 0, static_cast<GLsizei>(vertices.size()/3));
+        //clean up
         vaos[0]->release();
         program->release();
 
     }
 
+    //Specifies that the buffers need to be initialized again.
+    //Is mostly called after a change of geometry in the data.
     void changed()
     {
         are_buffers_filled = false;
     }
 
 private:
-
+    //contains the data
     std::vector<float> vertices;
     mutable QOpenGLShaderProgram *program;
     using CGAL::Three::Scene_item::initialize_buffers;
+    //Fills the buffers with data. The buffers allow us to give data to the shaders.
     void initialize_buffers(CGAL::Three::Viewer_interface *viewer)const
     {
 
@@ -161,7 +171,7 @@ private:
 }; //end of class Scene_triangle_item
 
 #include <CGAL/Three/Polyhedron_demo_plugin_helper.h>
-//!The actual plugin
+//The actual plugin
 using namespace CGAL::Three;
 class Polyhedron_demo_example_plugin :
         public QObject,
@@ -177,7 +187,7 @@ public :
     // To silent a warning -Woverloaded-virtual
     // See http://stackoverflow.com/questions/9995421/gcc-woverloaded-virtual-warnings
     using Polyhedron_demo_plugin_helper::init;
-    //! Adds an action to the menu and configures the widget
+    // Adds an action to the menu and configures the widget
     void init(QMainWindow* mainWindow,
               CGAL::Three::Scene_interface* scene_interface) {
       //get the references
@@ -216,10 +226,14 @@ public :
         // dock widget should be constructed in init()
         if(dock_widget->isVisible()) { dock_widget->hide(); }
         else                         { dock_widget->show(); }
+        //creates a new dialog
         dialog = new Polyhedron_demo_example_plugin_dialog();
+        //changes the value of the label according to the number of triangles
         dialog->setTriangleName(QString("Triangle %1").arg(triangle_array.size()));
+        //opens the dialog
         if(!dialog->exec())
             return;
+        //gets the values
         ax = dialog->getAx();
         ay = dialog->getAy();
         az = dialog->getAz();
@@ -229,20 +243,28 @@ public :
         cx = dialog->getCx();
         cy = dialog->getCy();
         cz = dialog->getCz();
+        //creates a triangle and store it in a vector.
         triangle_array.push_back(new Scene_triangle_item(ax, ay, az,
                                                                bx, by, bz,
                                                                cx, cy, cz));
+        triangle_array[triangle_array.size()-1]->setName(QString("Triangle %1").arg(triangle_array.size()));
+        //Adds the triangle to the items of the scene
+        scene->addItem(triangle_array[triangle_array.size()-1]);
+        //if the were less than 3 triangles created this way, opens a new dialog
         if(triangle_array.size()%3 > 0)
-        {
-            scene->addItem(triangle_array[triangle_array.size()-1]);
             populate_dialog();
-        }
+        //else creates a new group and passes the 3 last triangles to it.
         else
         {
-            Scene_group_item *group = new Scene_group_item("triangle group");
+            //clears the selection to avoid adding unwanted items to the group.
+            scene->setSelectedItem(-1);
+            //Creates a new group
+            Scene_group_item *group = new Scene_group_item("Triangle group");
+            //Then gives it its children
             for(int i =0; i<3; i++)
                 scene->changeGroup(triangle_array[triangle_array.size()-i-1], group);
-            scene->addItem(group);
+            //adds it to the scene
+            scene->add_group(group);
         }
     }
 

Three/doc/Three/Three.txt

@@ -122,6 +122,25 @@ and initialize them in the init fucntion :
 Use signal/slots to connect the dock widget to the plugin, and connect them in the init() function, and use the functions show()/hide() to make your 
 dock widget visible or not.
 
+\subsection exampleUsingAGroupItem Using a Scene_group_item
+This section will explain how to use a group item in a plugin. 
+A group item is a virtual item that is not seen in the viewer, nor drawn, but act as a parent for a list of actual items. Its main goal lays within the 
+interaction with the sceneView (which is the list of items on the left of the viewer). With group items, this view becomes hierarchic, which allows to interract with several objects at the same time, and organize this view.
+
+To use a group item in your plugin, you will need a CGAL::Three::Scene_group_item, of course, and a CGAL::Three::Scene_interface. As a group item will automatically contain all the selected items of the scene when it is created, 
+the first thing to do is to clear the selection with CGAL::Three::Scene_interface::setSelectedItem(-1). Then you can create a new Scene_group_item and give the items you want to regroup to it with CGAL::Three::Scene_interface::changeGroup().
+Once it is done, add the group to the scene with CGAL::Three::Scene_interface::add_group(). 
+~~~~~~~~~~~~~{.cpp}
+    //clears the selection to avoid adding unwanted items to the group.
+    scene->setSelectedItem(-1);
+    //Creates a new group
+    Scene_group_item *group = new Scene_group_item("New group");
+    //Then gives it its children
+    for(int i =0; i<3; i++)
+    scene->changeGroup(items[i], group);
+    //adds it to the scene
+    scene->add_group(group);
+~~~~~~~~~~~~~
 \section usefulItems List of useful classes :
 - MainWindow
 - CGAL::Three::Viewer_interface

Three/include/CGAL/Three/Scene_group_item.h

@@ -19,7 +19,7 @@ class DEMO_FRAMEWORK_EXPORT Scene_group_item : public Scene_item
 {
     Q_OBJECT
 public :
-    Scene_group_item(QString name = QString());
+    Scene_group_item(QString name = QString("New group"));
     ~Scene_group_item() {}
     //!Returns false to avoid disturbing the BBox of the scene.
     bool isFinite() const;

Three/include/CGAL/Three/Scene_interface.h

@@ -178,6 +178,11 @@ public:
 
   /*! Selects an item. Must be overloaded.*/
   virtual void setSelectedItem(Item_id) = 0;
+  /*!  Adds group to the Scene. If items were selected at the
+   * moment this function is called, they are added to the group.
+   * If all the selected items were in the same group, the new group
+   * is added as a sub-group of this group.*/
+  virtual void add_group(Scene_group_item* group) = 0;
   
 }; // end interface Scene_interface
 }