Add some more comments to improve code understanding

(bzr r14949.1.75)

4 files changed, 100 insertions, 66 deletions

diff --git a/src/ui/dialog/cssdialog.cpp b/src/ui/dialog/cssdialog.cpp
index cd2f74d15..fa266b012 100644
--- a/src/ui/dialog/cssdialog.cpp
+++ b/src/ui/dialog/cssdialog.cpp
@@ -35,13 +35,17 @@ void CssDialog::_styleButton(Gtk::Button& btn, char const* iconName,
     gtk_widget_show(child);
     btn.add(*manage(Glib::wrap(child)));
     btn.set_relief(Gtk::RELIEF_NONE);
-    btn.set_tooltip_text (tooltip);
+    btn.set_tooltip_text(tooltip);
 }
 
 /**
  * Constructor
  * A treeview whose each row corresponds to a CSS property of selector selected.
- * TODO: Further, buttons to add and delete properties will be added.
+ * New CSS property can be added by clicking '+' at bottom of the CSS pane. '-'
+ * in front of the CSS property row can be clicked to delete the CSS property.
+ * Besides clicking on an already selected property row makes the property editable
+ * and clicking 'Enter' updates the property with changes reflected in the
+ * drawing.
  */
 CssDialog::CssDialog():
     UI::Widget::Panel("", "/dialogs/css", SP_VERB_DIALOG_CSS),
@@ -56,14 +60,14 @@ CssDialog::CssDialog():
     _store = Gtk::ListStore::create(_cssColumns);
     _treeView.set_model(_store);
 
-    Inkscape::UI::Widget::AddToIcon * addRenderer = manage(
-                new Inkscape::UI::Widget::AddToIcon() );
+    Inkscape::UI::Widget::AddToIcon * addRenderer = manage(new Inkscape::UI::
+                                                           Widget::AddToIcon());
     addRenderer->property_active() = false;
 
     int addCol = _treeView.append_column("Unset Property", *addRenderer) - 1;
     Gtk::TreeViewColumn *col = _treeView.get_column(addCol);
-    if ( col ) {
-        col->add_attribute( addRenderer->property_active(), _cssColumns._colUnsetProp);
+    if (col) {
+        col->add_attribute(addRenderer->property_active(), _cssColumns._colUnsetProp);
     }
     _textRenderer = Gtk::manage(new Gtk::CellRendererText());
     _textRenderer->property_editable() = true;
@@ -71,7 +75,7 @@ CssDialog::CssDialog():
     int nameColNum = _treeView.append_column("Property", *_textRenderer) - 1;
     _propCol = _treeView.get_column(nameColNum);
 
-    create = manage(new Gtk::Button());
+    Gtk::Button* create = manage(new Gtk::Button());
     _styleButton(*create, "list-add", "Add a new property");
 
     _mainBox.pack_end(_buttonBox, Gtk::PACK_SHRINK);
@@ -85,12 +89,21 @@ CssDialog::CssDialog():
     create->signal_clicked().connect(sigc::mem_fun(*this, &CssDialog::_addProperty));
 }
 
+/**
+ * @brief CssDialog::~CssDialog
+ * Class destructor
+ */
 CssDialog::~CssDialog()
 {
     setDesktop(NULL);
 }
 
-void CssDialog::setDesktop( SPDesktop* desktop )
+/**
+ * @brief CssDialog::setDesktop
+ * @param desktop
+ * This function sets the 'desktop' for the CSS pane.
+ */
+void CssDialog::setDesktop(SPDesktop* desktop)
 {
     _desktop = desktop;
 }
diff --git a/src/ui/dialog/cssdialog.h b/src/ui/dialog/cssdialog.h
index ef48686cc..3bbab5031 100644
--- a/src/ui/dialog/cssdialog.h
+++ b/src/ui/dialog/cssdialog.h
@@ -26,7 +26,10 @@ namespace Dialog {
 
 /**
  * @brief The CssDialog class
- * A list of CSS properties will show up in this dialog.
+ * This dialog allows to add, delete and modify CSS properties for selectors
+ * created in Style Dialog. Double clicking any selector in Style dialog, a list
+ * of CSS properties will show up in this dialog (if any exist), else new properties
+ * can be added and each new property forms a new row in this pane.
  */
 class CssDialog : public UI::Widget::Panel
 {
@@ -35,7 +38,7 @@ public:
     ~CssDialog();
 
     static CssDialog &getInstance() { return *new CssDialog(); }
-    void setDesktop( SPDesktop* desktop);
+    void setDesktop(SPDesktop* desktop);
 
     class CssColumns : public Gtk::TreeModel::ColumnRecord
     {
@@ -58,10 +61,9 @@ public:
     Gtk::CellRendererText *_textRenderer;
     Gtk::TreeViewColumn *_propCol;
     Glib::ustring _editedProp;
-    Gtk::Button* create;
     bool _newProperty;
 
-    void _styleButton( Gtk::Button& btn, char const* iconName, char const* tooltip);
+    void _styleButton(Gtk::Button& btn, char const* iconName, char const* tooltip);
     void _addProperty();
 };
 
diff --git a/src/ui/dialog/styledialog.cpp b/src/ui/dialog/styledialog.cpp
index 878ab1926..5246290b4 100644
--- a/src/ui/dialog/styledialog.cpp
+++ b/src/ui/dialog/styledialog.cpp
@@ -21,6 +21,10 @@
 using Inkscape::Util::List;
 using Inkscape::XML::AttributeRecord;
 
+/**
+ * This macro is used to remove spaces around selectors or any strings when
+ * parsing is done to update XML style element or row labels in this dialog.
+ */
 #define REMOVE_SPACES(x) x.erase(0, x.find_first_not_of(' ')); \
     x.erase(x.find_last_not_of(' ') + 1);
 
@@ -48,7 +52,8 @@ void StyleDialog::_styleButton(Gtk::Button& btn, char const* iconName,
 /**
  * Constructor
  * A treeview and a set of two buttons are added to the dialog. _addSelector
- * adds selectors to treeview. Currently, delete button is disabled.
+ * adds selectors to treeview. _delSelector deletes the selector from the dialog.
+ * Any addition/deletion of the selectors updates XML style element accordingly.
  */
 StyleDialog::StyleDialog() :
     UI::Widget::Panel("", "/dialogs/style", SP_VERB_DIALOG_STYLE),
@@ -127,11 +132,20 @@ StyleDialog::StyleDialog() :
                                                                       _selChanged));
 }
 
+/**
+ * @brief StyleDialog::~StyleDialog
+ * Class destructor
+ */
 StyleDialog::~StyleDialog()
 {
     setDesktop(NULL);
 }
 
+/**
+ * @brief StyleDialog::setDesktop
+ * @param desktop
+ * This function sets the 'desktop' for the Style Dialog.
+ */
 void StyleDialog::setDesktop( SPDesktop* desktop )
 {
     Panel::setDesktop(desktop);
@@ -182,10 +196,9 @@ void StyleDialog::_addSelector()
 
     /**
      * @brief selectorName
-     * This string stores selector name. If '#' or a '.' is present in the
-     * beginning of string, text from entrybox is saved directly as name for
-     * selector. If text like 'red' is written in entrybox, it is prefixed
-     * with a dot.
+     * This string stores selector name. The text from entrybox is saved as name
+     * for selector. If the entrybox is empty, the text (thus selectorName) is
+     * set to ".Class1"
      */
     if (!textEditPtr->get_text().empty()) {
         _selectorName = textEditPtr->get_text();
@@ -290,7 +303,6 @@ void StyleDialog::_addSelector()
         Inkscape::GC::release(newChild);
         _styleChild = newChild;
     }
-
     _selAdd(row);
 }
 
@@ -581,6 +593,12 @@ bool StyleDialog::_handleButtonEvent(GdkEventButton *event)
                             }
                         }
 
+                        /**
+                         * @brief matchSelector
+                         * For id selectors, whenever any child row is deleted,
+                         * the row label is updated and so is the entry for the
+                         * selector in style element.
+                         */
                         std::string matchSelector = parentKey;
                         REMOVE_SPACES(matchSelector);
                         if (key == matchSelector) {
@@ -635,6 +653,15 @@ bool StyleDialog::_handleButtonEvent(GdkEventButton *event)
                     }
 
                     _store->erase(row);
+
+                    /**
+                     * On continuous deletion of objects (child rows) from the
+                     * selector (parent row), if the parent row has no child, then
+                     * the row is erased from the _store. Further if there is no
+                     * row left in _store, which implies there is no content in
+                     * XML style element, then the 'svg:style' element is also
+                     * removed.
+                     */
                     if (parentKey.empty()) {
                         _store->erase(parentRow);
                     }
@@ -650,6 +677,12 @@ bool StyleDialog::_handleButtonEvent(GdkEventButton *event)
     return false;
 }
 
+/**
+ * @brief StyleDialog::_selAdd
+ * @param row
+ * This routine is called when an object is added to a selector by clicking on
+ * '+' in front of the row with selector's label.
+ */
 void StyleDialog::_selAdd(Gtk::TreeModel::Row row)
 {
     Glib::ustring selectorName;
@@ -879,44 +912,43 @@ void StyleDialog::_handleEdited(const Glib::ustring& path, const Glib::ustring&
                 /** If a new property is added, existing value is appended with new
                  * property, else replacements in value are done in the 'else' block.
                  */
-            if (_cssPane->_newProperty) {
-                if (!new_text.empty()) {
-                    value.append((new_text + ";").c_str());
-                    _cssPane->_propCol->add_attribute(_cssPane->_textRenderer
-                                                      ->property_text(),
-                                                      _cssPane->_cssColumns
-                                                      ._propertyLabel);
-                    _cssPane->_newProperty = false;
+                if (_cssPane->_newProperty) {
+                    if (!new_text.empty()) {
+                        value.append((new_text + ";").c_str());
+                        _cssPane->_propCol->add_attribute(_cssPane->_textRenderer
+                                                          ->property_text(),
+                                                          _cssPane->_cssColumns
+                                                          ._propertyLabel);
+                        _cssPane->_newProperty = false;
+                    }
                 }
-            }
-            else {
-                std::stringstream ss(value);
-                std::string token, editedToken;
-                std::size_t found = value.find(";");
-                if (found!=std::string::npos) {
-                    while(std::getline(ss, token, ';')) {
-                        REMOVE_SPACES(token);
-                        if (!token.empty()) {
-                            if (token.substr(0, token.find(":")) == _cssPane
-                                    ->_editedProp.substr(0, _cssPane->_editedProp
-                                                         .find(":"))) {
-                                editedToken = _cssPane->_editedProp;
-                                size_t startPos = value.find(token);
-                                value.replace(startPos, token.length(), editedToken);
+                else {
+                    std::stringstream ss(value);
+                    std::string token, editedToken;
+                    std::size_t found = value.find(";");
+                    if (found!=std::string::npos) {
+                        while(std::getline(ss, token, ';')) {
+                            REMOVE_SPACES(token);
+                            if (!token.empty()) {
+                                if (token.substr(0, token.find(":")) == _cssPane
+                                        ->_editedProp.substr(0, _cssPane->_editedProp
+                                                             .find(":"))) {
+                                    editedToken = _cssPane->_editedProp;
+                                    size_t startPos = value.find(token);
+                                    value.replace(startPos, token.length(), editedToken);
+                                }
                             }
                         }
                     }
                 }
-            }
-            value.erase(std::remove(value.begin(), value.end(), '\n'), value.end());
-            (*it)._xmlContent = key + "{" + value + "}\n";
-            _updateStyleContent();
+                value.erase(std::remove(value.begin(), value.end(), '\n'), value.end());
+                (*it)._xmlContent = key + "{" + value + "}\n";
+                _updateStyleContent();
             }
         }
     }
 }
 
-
 /**
  * @brief StyleDialog::_delProperty
  * @param event
@@ -1067,27 +1099,11 @@ void StyleDialog::_selectRow(Selection */*sel*/)
             iter != children.end(); ++iter) {
             Gtk::TreeModel::Row row = *iter;
             std::vector<SPObject *> objVec = row[_mColumns._colObj];
-            std::vector<SPObject *> childObjVec;
-            Gtk::TreeModel::Row childRow;
-
             for (unsigned i = 0; i < objVec.size(); ++i) {
                 if (obj->getId() == objVec[i]->getId()) {
                     _treeView.get_selection()->select(row);
                 }
             }
-
-//            if (row.children()) {
-//                for(Gtk::TreeModel::Children::iterator it = row.children().begin();
-//                    it != row.children().end(); ++it) {
-//                    childRow = *it;
-//                    childObjVec = childRow[_mColumns._colObj];
-//                }
-//                for (unsigned j = 0; j < childObjVec.size(); ++j) {
-//                    if (obj->getId() == childObjVec[j]->getId()) {
-//                        _treeView.get_selection()->select(childRow);
-//                    }
-//                }
-//            }
         }
     }
     else {
diff --git a/src/ui/dialog/styledialog.h b/src/ui/dialog/styledialog.h
index af3014f88..b03a1d2e1 100644
--- a/src/ui/dialog/styledialog.h
+++ b/src/ui/dialog/styledialog.h
@@ -30,7 +30,10 @@ namespace Dialog {
 
 /**
  * @brief The StyleDialog class
- * A list of CSS selectors will show up in this dialog.
+ * A list of CSS selectors will show up in this dialog. This dialog allows to
+ * add and delete selectors. Objects can be added to and removed from the selectors
+ * in the dialog. Besides, selection of any selector row selects the matching
+ * objects in the drawing and vice-versa.
  */
 typedef std::pair<std::pair<std::string, std::vector<SPObject *> >, std::string>
 _selectorVecType;
@@ -42,11 +45,11 @@ public:
     ~StyleDialog();
 
     static StyleDialog &getInstance() { return *new StyleDialog(); }
-    void setDesktop( SPDesktop* desktop);
+    void setDesktop(SPDesktop* desktop);
 
 private:
-    void _styleButton( Gtk::Button& btn, char const* iconName, char const* tooltip);
-    std::string _setClassAttribute(std::vector<SPObject*>);
+    void _styleButton(Gtk::Button& btn, char const* iconName, char const* tooltip);
+    std::string _setClassAttribute(std::vector<SPObject *>);
 
     class InkSelector {
     public: