documentation of item properties dialog and SPAttributeTable

header stuff

(bzr r10831)

5 files changed, 170 insertions, 70 deletions

diff --git a/src/dialogs/item-properties.cpp b/src/dialogs/item-properties.cpp
index 16c29a69f..5fed0b84e 100644
--- a/src/dialogs/item-properties.cpp
+++ b/src/dialogs/item-properties.cpp
@@ -18,8 +18,6 @@
 #ifdef HAVE_CONFIG_H
 # include "config.h"
 #endif
-#include <gtk/gtk.h>
-#include <glibmm/i18n.h>
 
 #include "../desktop-handles.h"
 #include "../document.h"
@@ -44,6 +42,9 @@ static void sp_item_dialog_delete( GtkObject */*object*/, GdkEvent */*event*/, g
 static void sp_item_widget_modify_selection (SPWidget *spw, Inkscape::Selection *selection, guint flags, GtkWidget *itemw);
 static void sp_item_widget_change_selection (SPWidget *spw, Inkscape::Selection *selection, GtkWidget *itemw);
 
+/**
+ * \brief SPItemDialog callback for closing the dialog.
+ */
 static void sp_item_dialog_delete( GtkObject */*object*/, GdkEvent */*event*/, gpointer /*data*/ )
 {
     if (spid)
@@ -53,6 +54,9 @@ static void sp_item_dialog_delete( GtkObject */*object*/, GdkEvent */*event*/, g
     }
 }
 
+/**
+ * \brief SPItemDialog callback for a modification of the selected object (e.g. size, color, fill, etc.).
+ */
 static void sp_item_widget_modify_selection( SPWidget */*spw*/,
                                  Inkscape::Selection */*selection*/,
                                  guint /*flags*/,
@@ -64,6 +68,9 @@ static void sp_item_widget_modify_selection( SPWidget */*spw*/,
     }
 }
 
+/**
+ * \brief SPItemDialog callback for the selection of an other object.
+ */
 static void sp_item_widget_change_selection ( SPWidget */*spw*/,
                                   Inkscape::Selection */*selection*/,
                                   GtkWidget */*itemw*/ )
@@ -86,10 +93,9 @@ void sp_item_dialog(void)
 }
 
 /**
- * SPItemDialog class.
- * A widget for showing and editing the properties of an object.
+ * \brief Constructor.
  */
-SPItemDialog::SPItemDialog (void) :
+ SPItemDialog::SPItemDialog (void) :
     prefs_path("/dialogs/object/"),
     x(-1000),// impossible original value to make sure they are read from prefs
     y(-1000),// impossible original value to make sure they are read from prefs
@@ -165,6 +171,9 @@ SPItemDialog::SPItemDialog (void) :
     MakeWidget();
 }
 
+/**
+ * \brief Destructor.
+ */
 SPItemDialog::~SPItemDialog (void)
 {
     if (closing)
@@ -196,6 +205,9 @@ SPItemDialog::~SPItemDialog (void)
     }
 }
 
+/**
+ * \brief Constructor auxiliary function creating the child widgets.
+ */
 void SPItemDialog::MakeWidget(void)
 {
 	// if (gtk_widget_get_visible (GTK_WIDGET(spw))) {
@@ -309,6 +321,9 @@ void SPItemDialog::MakeWidget(void)
     widget_setup();
 }
 
+/**
+ * \brief Updates entries and other child widgets on selection change, object modification, etc.
+ */
 void SPItemDialog::widget_setup(void)
 {
     if (blocked)
@@ -399,6 +414,9 @@ void SPItemDialog::widget_setup(void)
     blocked = false;
 }
 
+/**
+ * \brief Sets object properties (ID, label, title, description) on user input.
+ */
 void SPItemDialog::label_changed(void)
 {
     if (blocked)
@@ -459,6 +477,9 @@ void SPItemDialog::label_changed(void)
     blocked = false;
 }
 
+/**
+ * \brief Callback for checkbox Lock.
+ */
 void SPItemDialog::sensitivity_toggled (void)
 {
     if (blocked)
@@ -476,6 +497,9 @@ void SPItemDialog::sensitivity_toggled (void)
     blocked = false;
 }
 
+/**
+ * \brief Callback for checkbox Hide.
+ */
 void SPItemDialog::hidden_toggled(void)
 {
     if (blocked)
diff --git a/src/dialogs/item-properties.h b/src/dialogs/item-properties.h
index 1be25f46f..1c978bd29 100644
--- a/src/dialogs/item-properties.h
+++ b/src/dialogs/item-properties.h
@@ -15,14 +15,21 @@
 
 #include <gtk/gtk.h>
 #include <gtkmm.h>
+#include <glibmm/i18n.h>
 #include "dialog-events.h"
-#include "../widgets/sp-attribute-widget.h"
 
-GtkWidget *sp_item_widget_new(void);
+#include "../widgets/sp-attribute-widget.h"
 
 void sp_item_dialog(void);
 
 class SPItemDialog : public Gtk::Widget {
+/**
+ * \class SPItemDialog
+ * \brief A dialog widget to show object properties.
+ *
+ * A widget to enter an ID, label, title and description for an object.
+ * In addition it allows to edit the properties of an object.
+ */
 public:
     SPItemDialog ();
     ~SPItemDialog ();
diff --git a/src/ui/context-menu.cpp b/src/ui/context-menu.cpp
index 4d2c242a6..331026aac 100644
--- a/src/ui/context-menu.cpp
+++ b/src/ui/context-menu.cpp
@@ -27,8 +27,7 @@ static void sp_object_type_menu(GType type, SPObject *object, SPDesktop *desktop
 
 /* Append object-specific part to context menu */
 
-void
-sp_object_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu)
+void sp_object_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu)
 {
     GObjectClass *klass;
     klass = G_OBJECT_GET_CLASS(object);
@@ -50,7 +49,6 @@ sp_object_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu)
 #include "sp-image.h"
 #include "sp-text.h"
 
-#include "document.h"
 #include "desktop-handles.h"
 #include "selection.h"
 #include "selection-chemistry.h"
@@ -71,8 +69,7 @@ static void sp_image_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu);
 static void sp_shape_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu);
 static void sp_text_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu);
 
-static void
-sp_object_type_menu(GType type, SPObject *object, SPDesktop *desktop, GtkMenu *menu)
+static void sp_object_type_menu(GType type, SPObject *object, SPDesktop *desktop, GtkMenu *menu)
 {
     static GHashTable *t2m = NULL;
     void (* handler)(SPObject *object, SPDesktop *desktop, GtkMenu *menu);
@@ -98,10 +95,9 @@ static void sp_set_mask(GtkMenuItem *menuitem, SPItem *item);
 static void sp_release_mask(GtkMenuItem *menuitem, SPItem *item);
 static void sp_set_clip(GtkMenuItem *menuitem, SPItem *item);
 static void sp_release_clip(GtkMenuItem *menuitem, SPItem *item);
-/* Generate context menu item section */
 
-static void
-sp_item_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
+/* Generate context menu item section */
+static void sp_item_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
 {
     SPItem *item;
     GtkWidget *w;
@@ -182,8 +178,7 @@ sp_item_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
 
 }
 
-static void
-sp_item_properties(GtkMenuItem *menuitem, SPItem *item)
+static void sp_item_properties(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -198,8 +193,7 @@ sp_item_properties(GtkMenuItem *menuitem, SPItem *item)
 }
 
 
-static void
-sp_set_mask(GtkMenuItem *menuitem, SPItem *item)
+static void sp_set_mask(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -212,8 +206,7 @@ sp_set_mask(GtkMenuItem *menuitem, SPItem *item)
 }
 
 
-static void
-sp_release_mask(GtkMenuItem *menuitem, SPItem *item)
+static void sp_release_mask(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -226,8 +219,7 @@ sp_release_mask(GtkMenuItem *menuitem, SPItem *item)
 }
 
 
-static void
-sp_set_clip(GtkMenuItem *menuitem, SPItem *item)
+static void sp_set_clip(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -240,8 +232,7 @@ sp_set_clip(GtkMenuItem *menuitem, SPItem *item)
 }
 
 
-static void
-sp_release_clip(GtkMenuItem *menuitem, SPItem *item)
+static void sp_release_clip(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -254,8 +245,7 @@ sp_release_clip(GtkMenuItem *menuitem, SPItem *item)
 }
 
 
-static void
-sp_item_select_this(GtkMenuItem *menuitem, SPItem *item)
+static void sp_item_select_this(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -267,8 +257,7 @@ sp_item_select_this(GtkMenuItem *menuitem, SPItem *item)
     sp_desktop_selection(desktop)->set(item);
 }
 
-static void
-sp_item_create_link(GtkMenuItem *menuitem, SPItem *item)
+static void sp_item_create_link(GtkMenuItem *menuitem, SPItem *item)
 {
     g_assert(SP_IS_ITEM(item));
     g_assert(!SP_IS_ANCHOR(item));
@@ -303,8 +292,7 @@ sp_item_create_link(GtkMenuItem *menuitem, SPItem *item)
 
 static void sp_item_group_ungroup_activate(GtkMenuItem *menuitem, SPGroup *group);
 
-static void
-sp_group_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu)
+static void sp_group_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu)
 {
     SPItem *item=SP_ITEM(object);
     GtkWidget *w;
@@ -317,8 +305,7 @@ sp_group_menu(SPObject *object, SPDesktop *desktop, GtkMenu *menu)
     gtk_menu_shell_append(GTK_MENU_SHELL(menu), w);
 }
 
-static void
-sp_item_group_ungroup_activate(GtkMenuItem *menuitem, SPGroup *group)
+static void sp_item_group_ungroup_activate(GtkMenuItem *menuitem, SPGroup *group)
 {
     SPDesktop *desktop;
     GSList *children;
@@ -341,8 +328,7 @@ static void sp_anchor_link_properties(GtkMenuItem *menuitem, SPAnchor *anchor);
 static void sp_anchor_link_follow(GtkMenuItem *menuitem, SPAnchor *anchor);
 static void sp_anchor_link_remove(GtkMenuItem *menuitem, SPAnchor *anchor);
 
-static void
-sp_anchor_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
+static void sp_anchor_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
 {
     SPItem *item;
     GtkWidget *w;
@@ -368,14 +354,12 @@ sp_anchor_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
     gtk_menu_shell_append(GTK_MENU_SHELL(m), w);
 }
 
-static void
-sp_anchor_link_properties(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
+static void sp_anchor_link_properties(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
 {
     sp_object_attributes_dialog(anchor, "Link");
 }
 
-static void
-sp_anchor_link_follow(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
+static void sp_anchor_link_follow(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
 {
     g_return_if_fail(anchor != NULL);
     g_return_if_fail(SP_IS_ANCHOR(anchor));
@@ -383,8 +367,7 @@ sp_anchor_link_follow(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
     /* shell out to an external browser here */
 }
 
-static void
-sp_anchor_link_remove(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
+static void sp_anchor_link_remove(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
 {
     GSList *children;
 
@@ -402,8 +385,7 @@ sp_anchor_link_remove(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
 static void sp_image_image_properties(GtkMenuItem *menuitem, SPAnchor *anchor);
 static void sp_image_image_edit(GtkMenuItem *menuitem, SPAnchor *anchor);
 
-static void
-sp_image_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
+static void sp_image_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
 {
     SPItem *item = SP_ITEM(object);
     GtkWidget *w;
@@ -427,8 +409,7 @@ sp_image_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
     }
 }
 
-static void
-sp_image_image_properties(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
+static void sp_image_image_properties(GtkMenuItem */*menuitem*/, SPAnchor *anchor)
 {
     sp_object_attributes_dialog(anchor, "Image");
 }
@@ -503,9 +484,7 @@ static void sp_image_image_edit(GtkMenuItem *menuitem, SPAnchor *anchor)
 }
 
 /* Fill and Stroke entry */
-
-static void
-sp_fill_settings(GtkMenuItem *menuitem, SPItem *item)
+static void sp_fill_settings(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -522,9 +501,7 @@ sp_fill_settings(GtkMenuItem *menuitem, SPItem *item)
 }
 
 /* SPShape */
-
-static void
-sp_shape_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
+static void sp_shape_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
 {
     SPItem *item;
     GtkWidget *w;
@@ -540,9 +517,7 @@ sp_shape_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
 }
 
 /* Edit Text entry */
-
-static void
-sp_text_settings(GtkMenuItem *menuitem, SPItem *item)
+static void sp_text_settings(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -559,9 +534,7 @@ sp_text_settings(GtkMenuItem *menuitem, SPItem *item)
 }
 
 /* Spellcheck entry */
-
-static void
-sp_spellcheck_settings(GtkMenuItem *menuitem, SPItem *item)
+static void sp_spellcheck_settings(GtkMenuItem *menuitem, SPItem *item)
 {
     SPDesktop *desktop;
 
@@ -578,9 +551,7 @@ sp_spellcheck_settings(GtkMenuItem *menuitem, SPItem *item)
 }
 
 /* SPText */
-
-static void
-sp_text_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
+static void sp_text_menu(SPObject *object, SPDesktop *desktop, GtkMenu *m)
 {
     SPItem *item;
     GtkWidget *w;
diff --git a/src/widgets/sp-attribute-widget.cpp b/src/widgets/sp-attribute-widget.cpp
index 529fccffd..986295aef 100644
--- a/src/widgets/sp-attribute-widget.cpp
+++ b/src/widgets/sp-attribute-widget.cpp
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Base widget for user input of object properties.
+ */
 /* Authors:
  *  Lauris Kaplinski <lauris@ximian.com>
  *  Abhishek Sharma
@@ -8,16 +12,14 @@
  * Released under GNU GPL, read the file 'COPYING' for more information
  */
 
-#include <gtk/gtk.h>
-#include "xml/repr.h"
-#include "macros.h"
-#include "document.h"
-#include "sp-object.h"
 #include <glibmm/i18n.h>
-
 #include <sigc++/functors/ptr_fun.h>
 #include <sigc++/adaptors/bind.h>
 
+#include "sp-object.h"
+#include "xml/repr.h"
+#include "macros.h"
+#include "document.h"
 #include "sp-attribute-widget.h"
 
 using Inkscape::DocumentUndo;
@@ -29,6 +31,10 @@ static void sp_attribute_table_object_release (SPObject */*object*/, SPAttribute
 #define XPAD 4
 #define YPAD 0
 
+
+/**
+ * \brief Constructor defaulting to no content.
+ */
 SPAttributeTable::SPAttributeTable () : 
     blocked(0),
     hasobj(0),
@@ -41,8 +47,21 @@ SPAttributeTable::SPAttributeTable () :
     src.object = NULL;
 }
 
+ /**
+ * \brief Constructor referring to a specific object.
+ *
+ * This constructor initializes all data fields and creates the necessary widgets.
+ * set_object is called for this purpose.
+ * 
+ * @param object the SPObject to which this instance is referring to. It should be the object that is currently selected and whose properties are being shown by this SPAttributeTable instance.
+ * @param labels list of labels to be shown for the different attributes.
+ * @param attributes list of attributes whose value can be edited.
+ * @param parent the parent object owning the SPAttributeTable instance.
+ * 
+ * @see set_object
+ */
 SPAttributeTable::SPAttributeTable (SPObject *object, std::vector<Glib::ustring> &labels, std::vector<Glib::ustring> &attributes, GtkWidget* parent) : 
-    blocked(0),
+   blocked(0),
     hasobj(0),
     table(0),
     _attributes(),
@@ -55,11 +74,17 @@ SPAttributeTable::SPAttributeTable (SPObject *object, std::vector<Glib::ustring>
     set_object(object, labels, attributes, parent);
 }
 
+/**
+ * \brief Destructor.
+ */
 SPAttributeTable::~SPAttributeTable ()
 {
     clear();
 }
 
+/**
+ * \brief Clears data of SPAttributeTable instance, destroys all child widgets and closes connections.
+ */
 void SPAttributeTable::clear(void)
 {
     Gtk::Widget *w;
@@ -104,6 +129,18 @@ void SPAttributeTable::clear(void)
     }
 }
 
+/**
+ * \brief Sets class properties and creates child widgets
+ *
+ * set_object initializes all data fields, creates links to the
+ * SPOject item and creates the necessary widgets. For n properties
+ * n labels and n entries are created and shown in tabular format.
+ * 
+ * @param object the SPObject to which this instance is referring to. It should be the object that is currently selected and whose properties are being shown by this SPAttribuTable instance.
+ * @param labels list of labels to be shown for the different attributes.
+ * @param attributes list of attributes whose value can be edited.
+ * @param parent the parent object owning the SPAttributeTable instance.
+ */
 void SPAttributeTable::set_object(SPObject *object,
                             std::vector<Glib::ustring> &labels,
                             std::vector<Glib::ustring> &attributes,
@@ -166,6 +203,18 @@ void SPAttributeTable::set_object(SPObject *object,
     }
 }
 
+/**
+ * \brief Update values in entry boxes on change of object.
+ *
+ * change_object updates the values of the entry boxes in case the user
+ * of Inkscape selects an other object.
+ * change_object is a subset of set_object and should only be called by
+ * the parent class (holding the SPAttributeTable instance). This function
+ * should only be called when the number of properties/entries nor
+ * the labels do not change.
+ * 
+ * @param object the SPObject to which this instance is referring to. It should be the object that is currently selected and whose properties are being shown by this SPAttribuTable instance.
+ */
 void SPAttributeTable::change_object(SPObject *object)
 {
     g_return_if_fail (!object || SP_IS_OBJECT (object));
@@ -264,6 +313,17 @@ void SPAttributeTable::change_object(SPObject *object)
 }
 */
 
+/**
+ * \brief Callback for a modification of the selected object (size, color, properties, etc.).
+ *
+ * sp_attribute_table_object_modified rereads the object properties
+ * and shows the values in the entry boxes. It is a callback from a
+ * connection of the SPObject.
+ * 
+ * @param object the SPObject to which this instance is referring to.
+ * @param flags gives the applied modifications
+ * @param spat pointer to the SPAttributeTable instance.
+ */
 static void sp_attribute_table_object_modified ( SPObject */*object*/,
                                      guint flags,
                                      SPAttributeTable *spat )
@@ -293,6 +353,16 @@ static void sp_attribute_table_object_modified ( SPObject */*object*/,
 
 } // end of sp_attribute_table_object_modified()
 
+/**
+ * \brief Callback for user input in one of the entries.
+ *
+ * sp_attribute_table_entry_changed set the object property
+ * to the new value and updates history. It is a callback from
+ * the entries created by SPAttributeTable.
+ * 
+ * @param editable pointer to the entry box.
+ * @param spat pointer to the SPAttributeTable instance.
+ */
 static void sp_attribute_table_entry_changed ( Gtk::Editable *editable,
                                    SPAttributeTable *spat )
 {
@@ -327,6 +397,12 @@ static void sp_attribute_table_entry_changed ( Gtk::Editable *editable,
 
 } // end of sp_attribute_table_entry_changed()
 
+/**
+ * \brief Callback for the delection of the selected object.
+ *
+ * sp_attribute_table_object_release invalidates all data of 
+ * SPAttributeTable and disables the widget.
+ */
 static void sp_attribute_table_object_release (SPObject */*object*/, SPAttributeTable *spat)
 {
     std::vector<Glib::ustring> labels;
diff --git a/src/widgets/sp-attribute-widget.h b/src/widgets/sp-attribute-widget.h
index 58be48fbd..ca0b170c6 100644
--- a/src/widgets/sp-attribute-widget.h
+++ b/src/widgets/sp-attribute-widget.h
@@ -21,17 +21,24 @@
 #include <stddef.h>
 #include <sigc++/connection.h>
 
+
 namespace Inkscape {
 namespace XML {
 class Node;
 }
 }
 
-struct SPAttributeTable;
-struct SPAttributeTableClass;
 class  SPObject;
 
 class SPAttributeTable : public Gtk::Widget {
+/**
+ * \class SPAttributeTable
+ * \brief A base class for dialogs to enter the value of several properties.
+ *
+ * SPAttributeTable is used if you want to alter several properties of
+ * an object. For each property, it creates an entry next to a label and
+ * positiones these labels and entries one by one below each other.
+ */
 public:
     SPAttributeTable ();
     SPAttributeTable (SPObject *object, std::vector<Glib::ustring> &labels, std::vector<Glib::ustring> &attributes, GtkWidget* parent);
@@ -42,14 +49,29 @@ public:
     // void set_repr(Inkscape::XML::Node *repr, std::vector<Glib::ustring> &labels, std::vector<Glib::ustring> &attributes, GtkWidget* parent);
     void clear(void);
     
+	/**
+     * \brief Gives access to the attributes list.
+     */
     std::vector<Glib::ustring> get_attributes(void) {return _attributes;};
+    
+	/**
+     * \brief Gives access to the Gtk::Entry list.
+     */
     std::vector<Gtk::Entry *> get_entries(void) {return _entries;};
+    
+	/**
+     * \brief Stores pointer to the selected object.
+     */
     union {
         SPObject *object;
         Inkscape::XML::Node *repr;
     } src;
+    
+	/**
+     * \brief Indicates whether SPAttributeTable is processing callbacks and whether it should accept any updating.
+     */
     guint blocked;
-    guint hasobj;
+    guint hasobj; //currently unused: set_repr is not used to data: decide later on whether to keep it
 
 private:
     Gtk::Table *table;