diff --git a/src/config-store/model/attribute-default-iterator.h b/src/config-store/model/attribute-default-iterator.h index 8384abbfb..63bba3e21 100644 --- a/src/config-store/model/attribute-default-iterator.h +++ b/src/config-store/model/attribute-default-iterator.h @@ -13,53 +13,179 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * - * Authors: Faker Moatamri - * Mathieu Lacage + * Author: Mathieu Lacage */ -#ifndef ATTRIBUTE_DEFAULT_ITERATOR_H -#define ATTRIBUTE_DEFAULT_ITERATOR_H +#ifndef ATTRIBUTE_ITERATOR_H +#define ATTRIBUTE_ITERATOR_H -#include "ns3/type-id.h" -#include +#include "ns3/ptr.h" +#include "ns3/object.h" +#include "ns3/object-ptr-container.h" +#include namespace ns3 { /** * \ingroup configstore * - * \brief Iterator to iterate on the default values of attributes of an ns3::Object + * \brief Iterator to iterate on the values of attributes of an ns3::Object + * \note This class is used internally by ConfigStore and GtkConfigStore. */ -class AttributeDefaultIterator +class AttributeIterator { public: - virtual ~AttributeDefaultIterator () = 0; + AttributeIterator (); + virtual ~AttributeIterator (); + /** - * \brief This function will go through all the TypeIds and get only the attributes which are - * explicit values (not vectors or pointer or arrays) and apply StartVisitTypeId - * and VisitAttribute on the attributes in one TypeId. At the end of each TypeId - * EndVisitTypeId is called. + * Start the process of iterating all objects from the root namespace object */ void Iterate (void); +protected: + /** + * Get the current attribute path + * \returns the current path string + */ + std::string GetCurrentPath (void) const; private: /** - * \brief Just an interface that needs to be implemented + * This method visits and performs a config-store action (such as saving + * to a text file) on the attribute values corresponding to the input + * object pointer and attribute name. + * + * \param object the object visited + * \param name the attribute name */ - virtual void StartVisitTypeId (std::string name); + virtual void DoVisitAttribute (Ptr object, std::string name) = 0; /** - * \brief Just an interface that needs to be implemented + * This method is called to start the process of visiting the input object + * \param object the object visited */ - virtual void EndVisitTypeId (void); + virtual void DoStartVisitObject (Ptr object); /** - * \brief This method can be implemented, otherwise, it will call DoVisitAttribute + * This method is called to end the process of visiting the currently + * visited object. */ - virtual void VisitAttribute (TypeId tid, std::string name, std::string defaultValue, uint32_t index); + virtual void DoEndVisitObject (void); /** - * \brief This method is just an interface and needs to be implemented + * Visit the attribute of type ns3::PointerValue, with the provided name, + * found on the object pointed to by the first argument. + * + * \param object the object on which the attribute of type PointerValue resides + * \param name the attribute name provided + * \param [in] value Ptr to the ns3::Object pointed to by the attribute */ - virtual void DoVisitAttribute (std::string name, std::string defaultValue); + virtual void DoStartVisitPointerAttribute (Ptr object, std::string name, Ptr value); + /** + * End the visit to the attribute of type ns3::PointerValue. + */ + virtual void DoEndVisitPointerAttribute (void); + /** + * Visit the attribute of type ns3::ObjectVectorValue, with the + * provided name, found on the object pointed to by the first argument. + * + * \note type name ObjectVectorValue is an alias for ObjectPtrContainerValue + * + * \param object the object on which the attribute of type ObjectVectorValue resides + * \param name the attribute name provided + * \param [in] vector the ObjectPtrContainerValue corresponding to the named attribute + */ + virtual void DoStartVisitArrayAttribute (Ptr object, std::string name, const ObjectPtrContainerValue &vector); + /** + * End the visit to the attribute of type ns3::ObjectVectorValue. + */ + virtual void DoEndVisitArrayAttribute (void); + /** + * Start to visit the object found in the input array at the provided index + * \param vector the array + * \param index the index into the array + * \param [in] item the array item to visit + */ + virtual void DoStartVisitArrayItem (const ObjectPtrContainerValue &vector, uint32_t index, Ptr item); + /** + * End the visit to the array item + */ + virtual void DoEndVisitArrayItem (void); + + /** + * Perform the iteration + * \param object the object visited + */ + void DoIterate (Ptr object); + /** + * Check if this object has already been examined + * \param object the object to check + * \returns true if object has been examined + */ + bool IsExamined (Ptr object); + /** + * Get current attribute path + * \param attr the current attribute string + * \returns the current path string + */ + std::string GetCurrentPath (std::string attr) const; + + /** + * Visit attribute to perform a config store operation on it + * \param object the current object + * \param name the attribute name + */ + void VisitAttribute (Ptr object, std::string name); + /** + * Start to visit an object to visit its attributes + * \param object the current object + */ + void StartVisitObject (Ptr object); + /** + * End the visit to the object + */ + void EndVisitObject (void); + /** + * Visit the attribute of type ns3::PointerValue, with the provided name, + * found on the object pointed to by the first argument. + * + * \param object the object on which the attribute of type PointerValue resides + * \param name the attribute name provided + * \param [in] value Ptr to the ns3::Object pointed to by the attribute + */ + void StartVisitPointerAttribute (Ptr object, std::string name, Ptr value); + /** + * End the visit to the attribute of type ns3::PointerValue. + */ + void EndVisitPointerAttribute (void); + /** + * Visit the attribute of type ns3::ObjectVectorValue, with the + * provided name, found on the object pointed to by the first argument. + * + * \note type name ObjectVectorValue is an alias for ObjectPtrContainerValue + * + * \param object the object on which the attribute of type ObjectVectorValue resides + * \param name the attribute name provided + * \param [in] vector the ObjectPtrContainerValue corresponding to the named attribute + */ + void StartVisitArrayAttribute (Ptr object, std::string name, const ObjectPtrContainerValue &vector); + /** + * End the visit to the attribute of type ns3::ObjectVectorValue. + */ + void EndVisitArrayAttribute (void); + /** + * Start to visit the object found in the input array at the provided index + * \param vector the array + * \param index the index into the array + * \param [in] item the array item to visit + */ + void StartVisitArrayItem (const ObjectPtrContainerValue &vector, uint32_t index, Ptr item); + /** + * End the visit to the array item + */ + void EndVisitArrayItem (void); + + + std::vector > m_examined; ///< list of attributes examined + std::vector m_currentPath; ///< current attribute path }; } // namespace ns3 -#endif /* ATTRIBUTE_DEFAULT_ITERATOR_H */ +#endif /* ATTRIBUTE_ITERATOR_H */ diff --git a/src/config-store/model/config-store.h b/src/config-store/model/config-store.h index cc051be2a..57dff39e4 100644 --- a/src/config-store/model/config-store.h +++ b/src/config-store/model/config-store.h @@ -121,12 +121,21 @@ private: }; /** - * @{ - * \ingroup configstore + * \brief Stream insertion operator. + * + * \param [in] os The reference to the output stream. + * \param [in] mode The configStore mode. + * \returns The reference to the output stream. */ std::ostream & operator << (std::ostream & os, ConfigStore::Mode & mode); +/** + * \brief Stream insertion operator. + * + * \param [in] os The reference to the output stream. + * \param [in] format The configStore file format. + * \returns The reference to the output stream. + */ std::ostream & operator << (std::ostream & os, ConfigStore::FileFormat & format); -/**@}*/ } // namespace ns3 diff --git a/src/config-store/model/display-functions.cc b/src/config-store/model/display-functions.cc index 5194e1352..040267e65 100644 --- a/src/config-store/model/display-functions.cc +++ b/src/config-store/model/display-functions.cc @@ -24,7 +24,7 @@ #include "ns3/pointer.h" namespace ns3 { -/** +/* * This function includes the name of the attribute or the editable value * in the second column */ @@ -51,7 +51,7 @@ cell_data_function_col_1 (GtkTreeViewColumn *col, GtkCellRenderer *renderer, g_object_set (renderer, "editable", FALSE, (char*) 0); } } -/** +/* * This function includes the name of the object, pointer, vector or vector item * in the first column */ @@ -91,7 +91,7 @@ cell_data_function_col_0 (GtkTreeViewColumn *col, GtkCellRenderer *renderer, Gtk } } -/** +/* * This is the callback called when the value of an attribute is changed */ void @@ -111,7 +111,7 @@ cell_edited_callback (GtkCellRendererText *cell, gchar *path_string, node->object->SetAttribute (node->name, StringValue (new_text)); } -/** +/* * This function gets the column number 0 or 1 from the mouse * click */ @@ -128,7 +128,7 @@ get_col_number_from_tree_view_column (GtkTreeViewColumn *col) return num; } -/** +/* * This function displays the tooltip for an object, pointer, vector * item or an attribute */ @@ -230,7 +230,7 @@ cell_tooltip_callback (GtkWidget *widget, gint x, gint y, gboolean keyboard_tip, return FALSE; } -/** +/* * This is the main view opening the widget, getting tooltips and drawing the * tree of attributes... */ @@ -271,7 +271,7 @@ create_view (GtkTreeStore *model) return view; } -/** +/* * Exit the window when exit button is pressed */ void @@ -281,7 +281,7 @@ exit_clicked_callback (GtkButton *button, gpointer user_data) gtk_widget_hide (GTK_WIDGET (user_data)); } -/** +/* * Exit the application */ gboolean @@ -292,7 +292,7 @@ delete_event_callback (GtkWidget *widget, GdkEvent *event, gpointer user_data) return TRUE; } -/** +/* * Delete the tree model contents */ gboolean @@ -310,8 +310,8 @@ clean_model_callback (GtkTreeModel *model, GtkTreePath *path, return FALSE; } -/************************** display functions used by default configurator **********************/ -/** +// display functions used by default configurator +/* * This function writes data in the second column, this data is going to be editable * if it is a NODE_ATTRIBUTE */ @@ -337,7 +337,7 @@ cell_data_function_col_1_config_default (GtkTreeViewColumn *col, GtkCellRenderer g_object_set (renderer, "editable", FALSE, (char*) 0); } } -/** +/* * This function writes the attribute or typeid name in the column 0 */ void @@ -364,7 +364,7 @@ cell_data_function_col_0_config_default (GtkTreeViewColumn *col, GtkCellRenderer } -/** +/* * This functions is called whenever there is a change in the value of an attribute * If the input value is ok, it will be updated in the default value and in the * gui, otherwise, it won't be updated in both. @@ -389,12 +389,12 @@ cell_edited_callback_config_default (GtkCellRendererText *cell, gchar *path_stri } } -/** +/* * This function is used to display a tooltip whenever the user puts the mouse * over a type ID or an attribute. It will give the type and the possible values of * an attribute value and the type of the object for an attribute object or a * typeID object - + * * \param widget is the display object * \param x is the x position * \param y is the y position @@ -464,7 +464,7 @@ cell_tooltip_callback_config_default (GtkWidget *widget, gint x, gint y, return FALSE; } -/** +/* * This is the action done when the user presses on the save button. * It will save the config to a file. * @@ -507,7 +507,7 @@ save_clicked_default (GtkButton *button, gpointer user_data) g_object_unref (native); } -/** +/* * If the user presses the button load, it will load the config file into memory. * * \param button (unused) @@ -542,7 +542,7 @@ load_clicked_default (GtkButton *button, gpointer user_data) g_object_unref (native); } -/** +/* * This is the action done when the user presses on the save button. * It will save the config to a file. * @@ -585,7 +585,7 @@ save_clicked_attribute (GtkButton *button, gpointer user_data) g_object_unref (native); } -/** +/* * If the user presses the button load, it will load the config file into memory. * * \param button (unused) @@ -620,7 +620,7 @@ load_clicked_attribute (GtkButton *button, gpointer user_data) g_object_unref (native); } -/** +/* * This is the main view opening the widget, getting tooltips and drawing the * tree of attributes */ @@ -661,7 +661,7 @@ create_view_config_default (GtkTreeStore *model) return view; } -/** +/* * Delete the tree model contents */ gboolean diff --git a/src/config-store/model/display-functions.h b/src/config-store/model/display-functions.h index 2d067258e..ec04d842f 100644 --- a/src/config-store/model/display-functions.h +++ b/src/config-store/model/display-functions.h @@ -27,6 +27,12 @@ namespace ns3 { /** * This function includes the name of the attribute or the editable value * in the second column + * + * \param col Pointer to the GtkTreeViewColumn + * \param renderer Pointer to the GtkCellRenderer + * \param model Pointer to the GtkTreeModel + * \param iter Pointer to the GtkTreeIter + * \param user_data Pointer to the data to be displayed (or modified) */ void cell_data_function_col_1 (GtkTreeViewColumn *col, GtkCellRenderer *renderer, @@ -34,12 +40,22 @@ cell_data_function_col_1 (GtkTreeViewColumn *col, GtkCellRenderer *renderer, /** * This function includes the name of the object, pointer, vector or vector item * in the first column + * \param col Pointer to the GtkTreeViewColumn + * \param renderer Pointer to the GtkCellRenderer + * \param model Pointer to the GtkTreeModel + * \param iter Pointer to the GtkTreeIter + * \param user_data Pointer to the data to be displayed (or modified) */ void cell_data_function_col_0 (GtkTreeViewColumn *col, GtkCellRenderer *renderer, GtkTreeModel *model, GtkTreeIter *iter, gpointer user_data); /** * This is the callback called when the value of an attribute is changed + * + * \param cell the changed cell + * \param path_string the path + * \param new_text the updated text in the cell + * \param user_data user data */ void cell_edited_callback (GtkCellRendererText *cell, gchar *path_string, @@ -47,12 +63,22 @@ cell_edited_callback (GtkCellRendererText *cell, gchar *path_string, /** * This function gets the column number 0 or 1 from the mouse * click + * \param col the column being clicked + * \returns the column index */ int get_col_number_from_tree_view_column (GtkTreeViewColumn *col); /** * This function displays the tooltip for an object, pointer, vector * item or an attribute + * + * \param widget is the display object + * \param x is the x position + * \param y is the y position + * \param keyboard_tip + * \param tooltip is the tooltip information to be displayed + * \param user_data + * \return false if the tooltip is not displayed */ gboolean cell_tooltip_callback (GtkWidget *widget, gint x, gint y, gboolean keyboard_tip, @@ -60,29 +86,51 @@ cell_tooltip_callback (GtkWidget *widget, gint x, gint y, gboolean keyboard_tip, /** * This is the main view opening the widget, getting tooltips and drawing the * tree of attributes... + * \param model the GtkTreeStore model + * \returns a GtkWidget on success */ GtkWidget * create_view (GtkTreeStore *model); /** * Exit the window when exit button is pressed + * \param button the pressed button + * \param user_data */ void exit_clicked_callback (GtkButton *button, gpointer user_data); /** * Exit the application + * \param widget a pointer to the widget + * \param event the event responsible for the aplication exit + * \param user_data user data + * \returns true on clean exit */ gboolean delete_event_callback (GtkWidget *widget, GdkEvent *event, gpointer user_data); /** * Delete the tree model contents + * \param model the GtkTreeModel + * \param path the GtkTreePath + * \param iter a GtkTreeIter + * \param data user data + * \return true if an error occurred. */ gboolean clean_model_callback (GtkTreeModel *model, GtkTreePath *path, GtkTreeIter *iter, gpointer data); -/************************** display functions used by default configurator **********************/ + + +// display functions used by default configurator + /** * This function writes data in the second column, this data is going to be editable * if it is a NODE_ATTRIBUTE + * + * \param col Pointer to the GtkTreeViewColumn + * \param renderer Pointer to the GtkCellRenderer + * \param model Pointer to the GtkTreeModel + * \param iter Pointer to the GtkTreeIter + * \param user_data Pointer to the data to be displayed (or modified) */ void cell_data_function_col_1_config_default (GtkTreeViewColumn *col, GtkCellRenderer *renderer, @@ -90,6 +138,11 @@ cell_data_function_col_1_config_default (GtkTreeViewColumn *col, GtkCellRenderer gpointer user_data); /** * This function writes the attribute or typeid name in the column 0 + * \param col Pointer to the GtkTreeViewColumn + * \param renderer Pointer to the GtkCellRenderer + * \param model Pointer to the GtkTreeModel + * \param iter Pointer to the GtkTreeIter + * \param user_data Pointer to the data to be displayed (or modified) */ void cell_data_function_col_0_config_default (GtkTreeViewColumn *col, GtkCellRenderer *renderer, GtkTreeModel *model, @@ -97,22 +150,34 @@ cell_data_function_col_0_config_default (GtkTreeViewColumn *col, GtkCellRenderer /** * This is the action done when the user presses on the save button for the Default attributes. * It will save the config to a file. + * + * \param button (unused) + * \param user_data */ void save_clicked_default (GtkButton *button, gpointer user_data); /** * If the user presses the button load, it will load the config file into memory for the Default attributes. + * + * \param button (unused) + * \param user_data */ void load_clicked_default (GtkButton *button, gpointer user_data); /** * This is the action done when the user presses on the save button for the Attributes. * It will save the config to a file. + * + * \param button (unused) + * \param user_data */ void save_clicked_attribute (GtkButton *button, gpointer user_data); /** * If the user presses the button load, it will load the config file into memory for the Attributes. + * + * \param button (unused) + * \param user_data */ void load_clicked_attribute (GtkButton *button, gpointer user_data); @@ -120,6 +185,11 @@ load_clicked_attribute (GtkButton *button, gpointer user_data); * This functions is called whenever there is a change in the value of an attribute * If the input value is ok, it will be updated in the default value and in the * GUI, otherwise, it won't be updated in both. + * + * \param cell the changed cell + * \param path_string the path + * \param new_text the updated text in the cell + * \param user_data user data */ void cell_edited_callback_config_default (GtkCellRendererText *cell, gchar *path_string, @@ -129,6 +199,14 @@ cell_edited_callback_config_default (GtkCellRendererText *cell, gchar *path_stri * over a type ID or an attribute. It will give the type and the possible values of * an attribute value and the type of the object for an attribute object or a * typeID object + * + * \param widget is the display object + * \param x is the x position + * \param y is the y position + * \param keyboard_tip + * \param tooltip is the tooltip information to be displayed + * \param user_data + * \return false if the tooltip is not displayed */ gboolean cell_tooltip_callback_config_default (GtkWidget *widget, gint x, gint y, @@ -136,11 +214,18 @@ cell_tooltip_callback_config_default (GtkWidget *widget, gint x, gint y, /** * This is the main view opening the widget, getting tooltips and drawing the * tree of attributes + * \param model the GtkTreeStore model + * \returns a GtkWidget on success */ GtkWidget * create_view_config_default (GtkTreeStore *model); /** * Delete the tree model contents + * \param model the GtkTreeModel + * \param path the GtkTreePath + * \param iter a GtkTreeIter + * \param data user data + * \return true if an error occurred. */ gboolean clean_model_callback_config_default (GtkTreeModel *model, GtkTreePath *path, diff --git a/src/config-store/model/model-typeid-creator.h b/src/config-store/model/model-typeid-creator.h index 1e0cc1202..ae022dfdd 100644 --- a/src/config-store/model/model-typeid-creator.h +++ b/src/config-store/model/model-typeid-creator.h @@ -66,15 +66,22 @@ public: /** * \brief This method will iterate on typeIds having default attributes and create a model * for them, this model will be used by the view. + * + * \param treestore the GtkTreeStore. */ void Build (GtkTreeStore *treestore); private: /** * \brief This method will add a ModelTypeid to the GtkTreeIterator + * \param tid TypeId + * \param name attribute name + * \param defaultValue default value + * \param index index of the attribute in the specified Typeid */ virtual void VisitAttribute (TypeId tid, std::string name, std::string defaultValue, uint32_t index); /** * \brief Add a node for the new TypeId object + * \param name TypeId name */ virtual void StartVisitTypeId (std::string name); /** @@ -83,6 +90,7 @@ private: virtual void EndVisitTypeId (void); /** * \brief Adds a treestore iterator to m_treestore model + * \param node the node to be added */ void Add (ModelTypeid *node); /**