Changeset 1896:92ef660710f1 in lemon-0.x

Timestamp:

01/14/06 14:42:37 (18 years ago)

Author:

Hegyi Péter

Branch:

default

Phase:

public

Convert:

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

Message:

Documentation of classes realizing algorithm running.

Location:

gui

Files:

• algobox.h (modified) (1 diff)
• algowin.h (modified) (1 diff)
• kruskalbox.h (modified) (1 diff)

gui/algobox.h

@@ -12 +12 @@
 #include <libgnomecanvasmm/polygon.h>
 
+///Ancestor class of algorithm graphical interface classes.
+
+///It also demonstrates, how should an algorithm graphical interface
+///work. Children of this class have the same functions and attributes,
+///therefore with all of them can the holder \ref AlgoWin communicate
+///in the same way.
+///
+///IMPORTANT! In a child class only the following tasks are to do:
+///
+///-call \ref init function with correct parameters from correctly parametrized constructor
+///
+///-implement \ref build_box function
+///
+///-implement \ref run function
+///
+///because all other thing is automatically done in \ref init function!
+
 class AlgoBox : public Gtk::VBox
 {
-  sigc::signal<void, std::string> signal_maplist_need;  
-  sigc::signal<void, std::string, bool> signal_newmapwin_need;  
+  ///Signal emitted in case of need for list of maps.
+
+  ///If the user has selected different tab to work on
+  ///new maps are selected as well. These new maps should be
+  ///provided for \ref AlgoBox. To get these maps, \ref AlgoBox
+  ///emits this signal.
+  sigc::signal<void, std::string> signal_maplist_need;
+
+  ///Signal emitted in case of need for \ref NewMapWin.
+
+  ///If user wants to create a new for an input, or output
+  ///it can let \ref NewMapWin popped up from here as well.
+  ///In that case will be this signal emitted.
+  sigc::signal<void, std::string, bool> signal_newmapwin_need;
 
 protected:
+  ///Holder of tabnames.
   Gtk::ComboBoxText tabcbt;
+
+  ///Holder of widgets, in which nodemaps can be selected to work on.
   std::vector<MapSelector *> nodemapcbts;
+
+  ///Holder of widgets, in which edgemaps can be selected to work on.
   std::vector<MapSelector *> edgemapcbts;
 
+  ///Maps of selected tabs.
   MapStorage * mapstorage;
 
 public:
+  ///Empty constructor called by children.
   AlgoBox(){};
-  AlgoBox(std::vector<std::string>);
 
+  ///Constructor
+
+  ///Calls \ref init function
+  ///with the provided parameters. \ref init function
+  ///is needed, because it is virtual, therefore the
+  ///functions of the proper class will be called when
+  ///running.
+  ///\param tablist list of tabs in \ref MainWin
+  AlgoBox(std::vector<std::string> tablist);
+
+  ///Initiates \ref AlgoBox.
+
+  ///Creates the graphical interface for the realized algorithm, initiates variables, connects signals.
+  ///
+  ///List of tabs in \ref MainWin is required, but no one
+  ///will be selected automatically. Every other
+  ///entry field remains empty (unselected), until a \ref NoteBookTab
+  ///is selected.
+  ///
+  ///It also have to bind all the signals to the correct place.
+  ///This function is virtual, in all type of children of
+  ///\ref AlgoBox the correct function willbe called.
+  ///
+  ///Therefore it is IMPORTANT that only \ref run and \ref build_box
+  ///has to be implemented in children of \ref AlgoBox, every other
+  ///thing will automatically work properly by the help of this
+  ///function that must be called in constructor of child!!!
   virtual void init(std::vector<std::string>);
 
-  sigc::signal<void, std::string> signal_maplist_needed();  
-  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};  
+  ///Signal emitted, when selected tab changes, and new list of maps required.
+  sigc::signal<void, std::string> signal_maplist_needed();
+
+  ///Emitted if user wants to create a new map for inpuit or output.
+  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};
+
+  ///Emits signal that requires list of maps for the recently selected \ref NoteBookTab.
   void emit_tab_change();
 
+  ///Interface, through which \ref AlgoBox can be notified about tab addition, deletion in \ref MainWin
+
+  ///\param tl list
+  ///of new tab state.
   void update_tablist( std::vector< std::string > tl );
-  void update_maplist( MapStorage * );
 
+  ///Interface, through which \ref AlgoBox can get the maps of the recently selected \ref NoteBookTab
+
+  ///\param ms the maps
+  ///of the recently selected \ref NoteBookTab
+  void update_maplist( MapStorage * ms);
+
+  ///Interface, through which \ref AlgoBox can be notified about nodemap addition.
+
+  ///If new map was added to \ref MapStorage of currently selected \ref NoteBookTab
+  ///a signal is emitted by it. This signal is connected to this function, so \ref MapSelector s
+  ///in \ref nodemapcbts can be notified, and those can registrate the new map. (\ref MapSelector::append_text)
   void nodemaplist_changed(std::string);
+
+  ///Interface, through which \ref AlgoBox can be notified about edgemap addition.
+
+  ///If new map was added to \ref MapStorage of currently selected \ref NoteBookTab
+  ///a signal is emitted by it. This signal is connected to this function, so \ref MapSelector s
+  ///in \ref edgemapcbts can be notified, and those can registrate the new map. (\ref MapSelector::append_text)
   void edgemaplist_changed(std::string);
 
-  void update_cbt( std::vector< std::string > tl, Gtk::ComboBoxText &);
-  
+  ///Aid function to provide data for a given entry.
+
+  ///At the moment it is only used for updating info
+  ///in \ref tabcbt. It clears it first, after that
+  ///inserts the data got from caller, and if there
+  ///was previously selected item it switches entry
+  ///to that.
+  ///\param tl list of entries (at the moment tabs in \ref MainWin)
+  ///\param cbt the entry to update (at the moment only \ref tabcbt)
+  void update_cbt( std::vector< std::string > tl, Gtk::ComboBoxText & cbt);
+
+  ///Runs the ralized algorithm.
+
+  ///Prepare the data for it
+  ///and after that postprocess it if necessary.
+  ///This is only a demo here, but in children it
+  ///runs the algorithm really.
   virtual void run();
-  
+
+  ///Creates the layout of the \ref AlgoBox
+
+  ///Place all the entries
+  ///required. Run and close button is not
+  ///its responsibility!
   virtual void build_box();
 
-  virtual void emit_new_map_signal(bool);
+  ///Emits \ref signal_newmapwin_need if user wants to create new input or output map.
 
-  void addMapSelector(std::string, bool);
+  ///Called in case of pressing \ref MapSelector::newbut.
+  ///\param itisedge edge or nodemap is required.
+  virtual void emit_new_map_signal(bool itisedge);
+
+  ///Aid function to make addition of \ref MapSelector easy in \ref build_box.
+
+  ///\param label label to show in \ref MapSelector
+  ///\param itisedge whether edge or nodemaps stored in \ref MapSelector
+  void addMapSelector(std::string label, bool itisedge);
 };
 #endif //ALGOBOX_H

gui/algowin.h

@@ -14 +14 @@
 class MapStorage;
 
+///Algorithm identifiers.
 enum {GENERAL, KRUSKAL, ALGO_NUM}; // algorithm IDs;
 
+///Window displaying graphical interface for different algorithms.
+
+///This class displays a graphical interface to set up
+///and run different algorithms. Different algorithms need
+///different inputs, running methods, etc. Therefore
+///class \ref AlgoWin is only a holder of a base class, the so
+///called AlgoBox. \ref AlgoBox is the ancestor of other
+///classes. These child classes realize interfaces of different
+///algorithms, but as their common ancestor is \ref AlgoBox
+///the interface of them is the same. \ref AlgoWin communicates
+///with these classes through this common interface. But it the
+///real object to be placed in \ref AlgoWin depends on the algorithm
+///which the \ref AlgoWin actually has to display. It gets the
+///id of algorithm to display at initialization, and therefore it is
+///able to place in itself the requested child of \ref AlgoBox
+/// visualizing the appropriate algorithm.
 class AlgoWin : public Gtk::Window
 {
 private:
+  ///Algorithm specific part of \ref AlgoWin
   AlgoBox * ab;
+
+  ///Run button.
+
+  ///If pressed, algorithm should run.
+  ///That is why common ancestor of different
+  ///algorithm realizer classes have to be. In case of
+  ///pressing run button a common method can be called.
   Gtk::Button * runbutton;
+
+  ///Close button. If pressed, \ref AlgoWin should close.
   Gtk::Button * closebutton;
 
 protected:
-  sigc::signal<void, AlgoWin *> signal_closed;  
-  sigc::signal<void, AlgoWin *, std::string> signal_maplist_need;  
-  sigc::signal<void, std::string, bool> signal_newmapwin_need;  
+  ///Signal emitted upon close of window
+
+  ///It is necessary, because \ref MainWin have to
+  ///score the opened \ref AlgoWin s, to be able to communicate
+  ///with them: let them know about changement in tabs, maps, etc.
+  ///If \ref AlgoWin is closed, \ref MainWin has to deregistrate it.
+  ///Therefore signal contains address of emitter \ref AlgoWin.
+  sigc::signal<void, AlgoWin *> signal_closed;
+
+  ///Signal indicating that informatino on certain maplist is required.
+
+  ///It is just a forwarded signal from \ref AlgoBox, benefit of common ancestor
+  ///algorithm class. User can select the graph (the holder \ref NoteBookTab) on
+  ///which the algorithm should run. But different graphs (\ref NoteBookTab) have
+  ///different maps. If selected tab changes this signal is emitted by \ref AlgoBox,
+  ///caught and reemitted by \ref AlgoWin.
+  ///
+  ///Signal contains the address of \ref AlgoWin to let \ref MainWin know
+  ///where should the information needed forwarded, and the name of
+  ///\ref NoteBookTab, of which maps are inquired.
+  sigc::signal<void, AlgoWin *, std::string> signal_maplist_need;
+
+  ///Signal that indicates that a \ref NewMapWin should be popped up.
+
+  ///This is a forwarded signal. If \ref AlgoBox emits a signal
+  ///to let a \ref NewMapWin pop up, |ref AlgoWin catch and reemit it.
+  ///
+  ///Signal contains the name of \ref NoteBookTab, in which the new map
+  ///should be created and a boolean that indicates whether an edge or a
+  ///nodemap should be created.
+  sigc::signal<void, std::string, bool> signal_newmapwin_need;
 
 public:
+  ///Close window if escape key is pressed.
   bool closeIfEscapeIsPressed(GdkEventKey* e);
 
+  ///Returns \ref signal_closed to be bindable somewhere.
   sigc::signal<void, AlgoWin *> signal_closing();
+
+  ///Returns \ref signal_maplist_need to be bindable somewhere.
   sigc::signal<void, AlgoWin *, std::string> signal_maplist_needed();
-  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};  
 
+  ///Returns \ref signal_newmapwin_need to be bindable somewhere.
+  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};
+
+  ///Forwards signal emitted by \ref AlgoBox, in which it indicates changement in selection of tabs.
   void emit_tab_change(std::string);
+
+  ///Forwards signal emitted by \ref AlgoBox, in which it indicates need for \ref NewMapWin.
   void emit_new_map_signal(std::string tabname, bool itisedge){signal_newmapwin_need.emit(tabname, itisedge);};
 
-  AlgoWin(int, std::vector<std::string>);
+  ///Constructor
 
+  ///It builds the window according to the information provided
+  ///by the creator. It needs the identifier of the algorithm
+  ///to visualize, and a list of name of \ref NoteBookTab s that can
+  ///be found in \ref MainWin.
+  ///\param algoid identifier of algorithm to show
+  ///\param tablist list of tabs in \ref MainWin
+  AlgoWin(int algoid, std::vector<std::string> tablist);
+
+  ///Forwards list of \ref NoteBookTabs toward \ref AlgoBox
+
+  ///In case of changement in tabs in \ref MainWin
+  ///\ref MainWin automatically updates tablist in
+  ///\ref AlgoWin s.
   void update_tablist(std::vector<std::string> tabnames);
+
+  ///Forwards list of requested maps toward \ref AlgoBox
+
+  ///Upon catching the signal in which \ref AlgoBox requests
+  ///list of maps \ref MainWin responds
+  ///through this function.
   void update_maplist(MapStorage *);
 
+  ///Called when window is closing.
+
+  ///\ref AlgoWin has to be deregistrated in \ref MainWin
+  ///thereforeit emits signal \ref signal_closed.
   void on_hide();
 };

gui/kruskalbox.h

@@ -12 +12 @@
 #include <libgnomecanvasmm/polygon.h>
 
+///Graphical interface to run Kruskal algorithm.
+
+///Child of \ref AlgoBox,
+///therefore the only task to do at implementation was to
+///
+///-call init function with correct parameters from correctly parametrized constructor
+///
+///-implement \ref build_box function
+///
+///-implement \ref run function
 class KruskalBox : public AlgoBox
 {
+  ///Shows result of Kruskal algorithm
   Gtk::Label resultlabel;
 
 public:
+  ///Calls \ref AlgoBox::init function to initialize class properly, automatically.
   KruskalBox(std::vector<std::string> t);
-    
+
+  ///Prepare, run and postprocess Kruskal algorithm.
+
+  ///\ref glemon works only with maps filled with double values
+  ///at the moment. While Kruskal nedds a bool map as output.
+  ///As postprocess this bool map should be transformed to
+  ///double map.
   void run();
-    
+
+  ///Builds the graphical design of the interface.
   void build_box();
 };