Changeset 121:637c12cbd64c in glemon-0.x for nbtab.h

Timestamp:

01/12/06 14:28:54 (18 years ago)

Author:

Hegyi Péter

Branch:

gui

Phase:

public

Convert:

svn:c9d7d8f5-90d6-0310-b91f-818b3a526b0e/lemon/trunk/gui@2466

Message:

Documentation of NoteBookTab?. Redundant function parameters are removed from other classes as well.

File:

• nbtab.h (modified) (3 diffs)

nbtab.h

@@ -12 +12 @@
 #include <libgnomecanvasmm/polygon.h>
 
+///One tab in the Notebook that is placed in the main window (\ref MainWin).
+
+///One graph and all of its accessories like maps are assigned to one tab in the notebook.
+///\ref NoteBookTab is responsible for the user defined display of the graph: view can be
+///set by visualized maps, therefore \ref NoteBookTab must provide an interface to set the
+///view of graph. This is \ref Mapwin window.
+///
+///\ref NoteBookTab is also
+///responsible for modify the graph if it is
+///requested. Therefore it is responsible for translating user events to modifications to
+///do on graph, like node/edge addition/deletion, map modification, addition and so on.
+///
+///To be able to solve these tasks the help of \ref MainWin is also needed, for example to
+///know which editor-tool is active at the moment. Therefore \ref MainWin knows \ref NoteBookTab.
+///
+///Some information in the other direction is needed as well: for example when new map creation is requested for this tab
+///\ref NoteBookTab must ask \ref MainWin to pop-up a \ref NewMapWin. Communication in this direction is realized by signals
+///therefore \ref NoteBookTab does not know \ref MainWin at all, but in this way it is not necessary.
 class NoteBookTab : public Gtk::VBox
 {
 public:
+  
+  ///Constructor of \ref NoteBookTab
+
+  ///It initiates the \re GraphDisplayerCanvas, on which the graph will be drawn
+  ///Signals of \ref MapStorage will be bound to the appropriate callback functions here.
   NoteBookTab();
   
+  ///Maps assigned to the graph displayed in this \ref NoteBookTab of notebook.
   MapStorage mapstorage;
     
+  ///Title changement indicator.
+
+  ///If graph is loaded from disk or saved to disk or changed its name somehow
+  ///this signal will be emit to let
+  ///\ref MainWin know that it has to modify the title of the main window.
+  ///It contains the new title.
   sigc::signal<void, std::string> signal_title;
 
+  ///Returns \ref signal_title to be the caller able to connect it to a callback function.
   sigc::signal<void, std::string> signal_title_ch();
 
+  ///Indicates that new map window should be popped up.
+
+  ///\ref NoteBookTab can ask \ref MainWin to pop up a \ref NweMapWin ny emitting this signal.
+  ///The signal contains whether an edgemap or a nodemap should be popped up. \ref NewMapWin
+  ///is not popped up by \ref NoteBookTab, because not only \ref NoteBookTab needs \ref NewMapWin,
+  ///but for example \ref MainWin and \ref AlgoWin s as well.
   sigc::signal<void, NoteBookTab *, bool> signal_newmap;
 
+  ///Returns \ref signal_newmap to be the caller able to connect it to a callback function.
   sigc::signal<void, NoteBookTab *, bool> signal_newmap_needed();
 
+  ///Loads the given file.
+
+  ///The given file will be load in the \ref MapStorage and afeter that
+  ///\ref GraphDisplayerCanvas will be requested to display the graph.
+  ///\ref GraphDisplayer will get datas from the recently set \ref MapStorage.
   void readFile(const std::string &);
     
@@ -32 +75 @@
   GraphDisplayerCanvas * gd_canvas;
 
+  ///Indicates whether the \ref MapWin is opened or not. See \ref mapwin.
   bool mapwinexists;
 
+  ///Address of the only \ref MapWin that the \ref NoteBookTab can open.
+
+  ///Only one of this window can be opened at the same time (\ref mapwinexists), 
+  ///because there is no need for more, one per tab is enough.
+  ///There won1t be benefit of more than one, but it would be
+  ///more complicated to synchronize them.
   MapWin * mapwin;
     
@@ -48 +98 @@
   virtual void close();
 
-  void propertyChange(bool, int, std::string);
-  void popupNewMapWin(bool, int);
+  ///Handles changement of view of graph.
 
-  std::string getActiveEdgeMap(int);
-  std::string getActiveNodeMap(int);
+  ///If the user changes the map to show by a property to a nother in \ref MapWin,
+  ///\ref MapWin will call this function. This function will registrate in \ref MapStorage
+  ///the new map to display by the changed property. After that \ref MapStorage will
+  ///emits a signal that will be forwarded to \ref GraphDisplayerCanvas to update the
+  ///appropriate parts of graph.
+  ///\param itiesedge whether the changed property is edge property or node property
+  ///\param prop id of property, see all_include.h
+  ///\param mapname name of the recently selected map
+  void propertyChange(bool itisedge, int prop, std::string mapname);
 
-  void registerNewEdgeMap(std::string);
-  void registerNewNodeMap(std::string);
+  ///Emits a signal that request \ref MainWin to pop up \ref NewMapWin
 
+  ///This function is called by \ref MapWin.
+  ///\param itisedge whether the new map should be an edgemap or a nodemap.
+  void popupNewMapWin(bool itisedge);
+
+  ///Returns the actually selected edgemap to visualize by the given property.
+
+  ///\ref MapWin calls this function, beacuse it does not know \ref MapStorage.
+  ///\param prop property to inquire.
+  std::string getActiveEdgeMap(int prop);
+
+  ///Returns the actually selected nodemap to visualize by the given property.
+
+  ///\ref MapWin calls this function, beacuse it does not know \ref MapStorage.
+  ///\param prop property to inquire.
+  std::string getActiveNodeMap(int prop);
+
+  ///Registers recently created edgemap in \ref MapWin.
+
+  ///After creation of new map \ref MapStorage emits a signal.
+  ///This signal is bound to this callback function, that will call
+  ///a function with the same name and same parameterin \ref MapWin.
+  ///This call-forwarder function is needed, because \ref Mapstorage does not know \ref MapWin
+  ///\param mapname name of new map
+  void registerNewEdgeMap(std::string mapname);
+
+  ///Registers recently created nodemap in \ref MapWin.
+
+  ///After creation of new map \ref MapStorage emits a signal.
+  ///This signal is bound to this callback function, that will call
+  ///a function with the same name and same parameter in \ref MapWin.
+  ///This call-forwarder function is needed, because \ref Mapstorage does not know \ref MapWin
+  ///\param mapname name of new map
+  void registerNewNodeMap(std::string mapname);
+
+  ///Pops up and registrates the \ref MapWin of \ref NoteBookTab.
+  
+  ///See also
+  ///\ref mapwin.
   void createMapWin(std::string);
+
+  ///Closes and deregistrates the \ref MapWin of \ref NoteBookTab.
+  
+  ///See also
+  ///\ref mapwin.
   void closeMapWin();
 };