Documentation of classes realizing algorithm running.
authorhegyi
Sat, 14 Jan 2006 13:42:37 +0000
changeset 189692ef660710f1
parent 1895 5b01801efbc0
child 1897 dd90f57b01d1
Documentation of classes realizing algorithm running.
gui/algobox.h
gui/algowin.h
gui/kruskalbox.h
     1.1 --- a/gui/algobox.h	Sat Jan 14 08:44:59 2006 +0000
     1.2 +++ b/gui/algobox.h	Sat Jan 14 13:42:37 2006 +0000
     1.3 @@ -11,42 +11,157 @@
     1.4  #include <libgnomecanvasmm.h>
     1.5  #include <libgnomecanvasmm/polygon.h>
     1.6  
     1.7 +///Ancestor class of algorithm graphical interface classes.
     1.8 +
     1.9 +///It also demonstrates, how should an algorithm graphical interface
    1.10 +///work. Children of this class have the same functions and attributes,
    1.11 +///therefore with all of them can the holder \ref AlgoWin communicate
    1.12 +///in the same way.
    1.13 +///
    1.14 +///IMPORTANT! In a child class only the following tasks are to do:
    1.15 +///
    1.16 +///-call \ref init function with correct parameters from correctly parametrized constructor
    1.17 +///
    1.18 +///-implement \ref build_box function
    1.19 +///
    1.20 +///-implement \ref run function
    1.21 +///
    1.22 +///because all other thing is automatically done in \ref init function!
    1.23 +
    1.24  class AlgoBox : public Gtk::VBox
    1.25  {
    1.26 -  sigc::signal<void, std::string> signal_maplist_need;  
    1.27 -  sigc::signal<void, std::string, bool> signal_newmapwin_need;  
    1.28 +  ///Signal emitted in case of need for list of maps.
    1.29 +
    1.30 +  ///If the user has selected different tab to work on
    1.31 +  ///new maps are selected as well. These new maps should be
    1.32 +  ///provided for \ref AlgoBox. To get these maps, \ref AlgoBox
    1.33 +  ///emits this signal.
    1.34 +  sigc::signal<void, std::string> signal_maplist_need;
    1.35 +
    1.36 +  ///Signal emitted in case of need for \ref NewMapWin.
    1.37 +
    1.38 +  ///If user wants to create a new for an input, or output
    1.39 +  ///it can let \ref NewMapWin popped up from here as well.
    1.40 +  ///In that case will be this signal emitted.
    1.41 +  sigc::signal<void, std::string, bool> signal_newmapwin_need;
    1.42  
    1.43  protected:
    1.44 +  ///Holder of tabnames.
    1.45    Gtk::ComboBoxText tabcbt;
    1.46 +
    1.47 +  ///Holder of widgets, in which nodemaps can be selected to work on.
    1.48    std::vector<MapSelector *> nodemapcbts;
    1.49 +
    1.50 +  ///Holder of widgets, in which edgemaps can be selected to work on.
    1.51    std::vector<MapSelector *> edgemapcbts;
    1.52  
    1.53 +  ///Maps of selected tabs.
    1.54    MapStorage * mapstorage;
    1.55  
    1.56  public:
    1.57 +  ///Empty constructor called by children.
    1.58    AlgoBox(){};
    1.59 -  AlgoBox(std::vector<std::string>);
    1.60  
    1.61 +  ///Constructor
    1.62 +
    1.63 +  ///Calls \ref init function
    1.64 +  ///with the provided parameters. \ref init function
    1.65 +  ///is needed, because it is virtual, therefore the
    1.66 +  ///functions of the proper class will be called when
    1.67 +  ///running.
    1.68 +  ///\param tablist list of tabs in \ref MainWin
    1.69 +  AlgoBox(std::vector<std::string> tablist);
    1.70 +
    1.71 +  ///Initiates \ref AlgoBox.
    1.72 +
    1.73 +  ///Creates the graphical interface for the realized algorithm, initiates variables, connects signals.
    1.74 +  ///
    1.75 +  ///List of tabs in \ref MainWin is required, but no one
    1.76 +  ///will be selected automatically. Every other
    1.77 +  ///entry field remains empty (unselected), until a \ref NoteBookTab
    1.78 +  ///is selected.
    1.79 +  ///
    1.80 +  ///It also have to bind all the signals to the correct place.
    1.81 +  ///This function is virtual, in all type of children of
    1.82 +  ///\ref AlgoBox the correct function willbe called.
    1.83 +  ///
    1.84 +  ///Therefore it is IMPORTANT that only \ref run and \ref build_box
    1.85 +  ///has to be implemented in children of \ref AlgoBox, every other
    1.86 +  ///thing will automatically work properly by the help of this
    1.87 +  ///function that must be called in constructor of child!!!
    1.88    virtual void init(std::vector<std::string>);
    1.89  
    1.90 -  sigc::signal<void, std::string> signal_maplist_needed();  
    1.91 -  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};  
    1.92 +  ///Signal emitted, when selected tab changes, and new list of maps required.
    1.93 +  sigc::signal<void, std::string> signal_maplist_needed();
    1.94 +
    1.95 +  ///Emitted if user wants to create a new map for inpuit or output.
    1.96 +  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};
    1.97 +
    1.98 +  ///Emits signal that requires list of maps for the recently selected \ref NoteBookTab.
    1.99    void emit_tab_change();
   1.100  
   1.101 +  ///Interface, through which \ref AlgoBox can be notified about tab addition, deletion in \ref MainWin
   1.102 +
   1.103 +  ///\param tl list
   1.104 +  ///of new tab state.
   1.105    void update_tablist( std::vector< std::string > tl );
   1.106 -  void update_maplist( MapStorage * );
   1.107  
   1.108 +  ///Interface, through which \ref AlgoBox can get the maps of the recently selected \ref NoteBookTab
   1.109 +
   1.110 +  ///\param ms the maps
   1.111 +  ///of the recently selected \ref NoteBookTab
   1.112 +  void update_maplist( MapStorage * ms);
   1.113 +
   1.114 +  ///Interface, through which \ref AlgoBox can be notified about nodemap addition.
   1.115 +
   1.116 +  ///If new map was added to \ref MapStorage of currently selected \ref NoteBookTab
   1.117 +  ///a signal is emitted by it. This signal is connected to this function, so \ref MapSelector s
   1.118 +  ///in \ref nodemapcbts can be notified, and those can registrate the new map. (\ref MapSelector::append_text)
   1.119    void nodemaplist_changed(std::string);
   1.120 +
   1.121 +  ///Interface, through which \ref AlgoBox can be notified about edgemap addition.
   1.122 +
   1.123 +  ///If new map was added to \ref MapStorage of currently selected \ref NoteBookTab
   1.124 +  ///a signal is emitted by it. This signal is connected to this function, so \ref MapSelector s
   1.125 +  ///in \ref edgemapcbts can be notified, and those can registrate the new map. (\ref MapSelector::append_text)
   1.126    void edgemaplist_changed(std::string);
   1.127  
   1.128 -  void update_cbt( std::vector< std::string > tl, Gtk::ComboBoxText &);
   1.129 -  
   1.130 +  ///Aid function to provide data for a given entry.
   1.131 +
   1.132 +  ///At the moment it is only used for updating info
   1.133 +  ///in \ref tabcbt. It clears it first, after that
   1.134 +  ///inserts the data got from caller, and if there
   1.135 +  ///was previously selected item it switches entry
   1.136 +  ///to that.
   1.137 +  ///\param tl list of entries (at the moment tabs in \ref MainWin)
   1.138 +  ///\param cbt the entry to update (at the moment only \ref tabcbt)
   1.139 +  void update_cbt( std::vector< std::string > tl, Gtk::ComboBoxText & cbt);
   1.140 +
   1.141 +  ///Runs the ralized algorithm.
   1.142 +
   1.143 +  ///Prepare the data for it
   1.144 +  ///and after that postprocess it if necessary.
   1.145 +  ///This is only a demo here, but in children it
   1.146 +  ///runs the algorithm really.
   1.147    virtual void run();
   1.148 -  
   1.149 +
   1.150 +  ///Creates the layout of the \ref AlgoBox
   1.151 +
   1.152 +  ///Place all the entries
   1.153 +  ///required. Run and close button is not
   1.154 +  ///its responsibility!
   1.155    virtual void build_box();
   1.156  
   1.157 -  virtual void emit_new_map_signal(bool);
   1.158 +  ///Emits \ref signal_newmapwin_need if user wants to create new input or output map.
   1.159  
   1.160 -  void addMapSelector(std::string, bool);
   1.161 +  ///Called in case of pressing \ref MapSelector::newbut.
   1.162 +  ///\param itisedge edge or nodemap is required.
   1.163 +  virtual void emit_new_map_signal(bool itisedge);
   1.164 +
   1.165 +  ///Aid function to make addition of \ref MapSelector easy in \ref build_box.
   1.166 +
   1.167 +  ///\param label label to show in \ref MapSelector
   1.168 +  ///\param itisedge whether edge or nodemaps stored in \ref MapSelector
   1.169 +  void addMapSelector(std::string label, bool itisedge);
   1.170  };
   1.171  #endif //ALGOBOX_H
     2.1 --- a/gui/algowin.h	Sat Jan 14 08:44:59 2006 +0000
     2.2 +++ b/gui/algowin.h	Sat Jan 14 13:42:37 2006 +0000
     2.3 @@ -13,35 +13,122 @@
     2.4  
     2.5  class MapStorage;
     2.6  
     2.7 +///Algorithm identifiers.
     2.8  enum {GENERAL, KRUSKAL, ALGO_NUM}; // algorithm IDs;
     2.9  
    2.10 +///Window displaying graphical interface for different algorithms.
    2.11 +
    2.12 +///This class displays a graphical interface to set up
    2.13 +///and run different algorithms. Different algorithms need
    2.14 +///different inputs, running methods, etc. Therefore
    2.15 +///class \ref AlgoWin is only a holder of a base class, the so
    2.16 +///called AlgoBox. \ref AlgoBox is the ancestor of other
    2.17 +///classes. These child classes realize interfaces of different
    2.18 +///algorithms, but as their common ancestor is \ref AlgoBox
    2.19 +///the interface of them is the same. \ref AlgoWin communicates
    2.20 +///with these classes through this common interface. But it the
    2.21 +///real object to be placed in \ref AlgoWin depends on the algorithm
    2.22 +///which the \ref AlgoWin actually has to display. It gets the
    2.23 +///id of algorithm to display at initialization, and therefore it is
    2.24 +///able to place in itself the requested child of \ref AlgoBox
    2.25 +/// visualizing the appropriate algorithm.
    2.26  class AlgoWin : public Gtk::Window
    2.27  {
    2.28  private:
    2.29 +  ///Algorithm specific part of \ref AlgoWin
    2.30    AlgoBox * ab;
    2.31 +
    2.32 +  ///Run button.
    2.33 +
    2.34 +  ///If pressed, algorithm should run.
    2.35 +  ///That is why common ancestor of different
    2.36 +  ///algorithm realizer classes have to be. In case of
    2.37 +  ///pressing run button a common method can be called.
    2.38    Gtk::Button * runbutton;
    2.39 +
    2.40 +  ///Close button. If pressed, \ref AlgoWin should close.
    2.41    Gtk::Button * closebutton;
    2.42  
    2.43  protected:
    2.44 -  sigc::signal<void, AlgoWin *> signal_closed;  
    2.45 -  sigc::signal<void, AlgoWin *, std::string> signal_maplist_need;  
    2.46 -  sigc::signal<void, std::string, bool> signal_newmapwin_need;  
    2.47 +  ///Signal emitted upon close of window
    2.48 +
    2.49 +  ///It is necessary, because \ref MainWin have to
    2.50 +  ///score the opened \ref AlgoWin s, to be able to communicate
    2.51 +  ///with them: let them know about changement in tabs, maps, etc.
    2.52 +  ///If \ref AlgoWin is closed, \ref MainWin has to deregistrate it.
    2.53 +  ///Therefore signal contains address of emitter \ref AlgoWin.
    2.54 +  sigc::signal<void, AlgoWin *> signal_closed;
    2.55 +
    2.56 +  ///Signal indicating that informatino on certain maplist is required.
    2.57 +
    2.58 +  ///It is just a forwarded signal from \ref AlgoBox, benefit of common ancestor
    2.59 +  ///algorithm class. User can select the graph (the holder \ref NoteBookTab) on
    2.60 +  ///which the algorithm should run. But different graphs (\ref NoteBookTab) have
    2.61 +  ///different maps. If selected tab changes this signal is emitted by \ref AlgoBox,
    2.62 +  ///caught and reemitted by \ref AlgoWin.
    2.63 +  ///
    2.64 +  ///Signal contains the address of \ref AlgoWin to let \ref MainWin know
    2.65 +  ///where should the information needed forwarded, and the name of
    2.66 +  ///\ref NoteBookTab, of which maps are inquired.
    2.67 +  sigc::signal<void, AlgoWin *, std::string> signal_maplist_need;
    2.68 +
    2.69 +  ///Signal that indicates that a \ref NewMapWin should be popped up.
    2.70 +
    2.71 +  ///This is a forwarded signal. If \ref AlgoBox emits a signal
    2.72 +  ///to let a \ref NewMapWin pop up, |ref AlgoWin catch and reemit it.
    2.73 +  ///
    2.74 +  ///Signal contains the name of \ref NoteBookTab, in which the new map
    2.75 +  ///should be created and a boolean that indicates whether an edge or a
    2.76 +  ///nodemap should be created.
    2.77 +  sigc::signal<void, std::string, bool> signal_newmapwin_need;
    2.78  
    2.79  public:
    2.80 +  ///Close window if escape key is pressed.
    2.81    bool closeIfEscapeIsPressed(GdkEventKey* e);
    2.82  
    2.83 +  ///Returns \ref signal_closed to be bindable somewhere.
    2.84    sigc::signal<void, AlgoWin *> signal_closing();
    2.85 +
    2.86 +  ///Returns \ref signal_maplist_need to be bindable somewhere.
    2.87    sigc::signal<void, AlgoWin *, std::string> signal_maplist_needed();
    2.88 -  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};  
    2.89  
    2.90 +  ///Returns \ref signal_newmapwin_need to be bindable somewhere.
    2.91 +  sigc::signal<void, std::string, bool> signal_newmapwin_needed(){return signal_newmapwin_need;};
    2.92 +
    2.93 +  ///Forwards signal emitted by \ref AlgoBox, in which it indicates changement in selection of tabs.
    2.94    void emit_tab_change(std::string);
    2.95 +
    2.96 +  ///Forwards signal emitted by \ref AlgoBox, in which it indicates need for \ref NewMapWin.
    2.97    void emit_new_map_signal(std::string tabname, bool itisedge){signal_newmapwin_need.emit(tabname, itisedge);};
    2.98  
    2.99 -  AlgoWin(int, std::vector<std::string>);
   2.100 +  ///Constructor
   2.101  
   2.102 +  ///It builds the window according to the information provided
   2.103 +  ///by the creator. It needs the identifier of the algorithm
   2.104 +  ///to visualize, and a list of name of \ref NoteBookTab s that can
   2.105 +  ///be found in \ref MainWin.
   2.106 +  ///\param algoid identifier of algorithm to show
   2.107 +  ///\param tablist list of tabs in \ref MainWin
   2.108 +  AlgoWin(int algoid, std::vector<std::string> tablist);
   2.109 +
   2.110 +  ///Forwards list of \ref NoteBookTabs toward \ref AlgoBox
   2.111 +
   2.112 +  ///In case of changement in tabs in \ref MainWin
   2.113 +  ///\ref MainWin automatically updates tablist in
   2.114 +  ///\ref AlgoWin s.
   2.115    void update_tablist(std::vector<std::string> tabnames);
   2.116 +
   2.117 +  ///Forwards list of requested maps toward \ref AlgoBox
   2.118 +
   2.119 +  ///Upon catching the signal in which \ref AlgoBox requests
   2.120 +  ///list of maps \ref MainWin responds
   2.121 +  ///through this function.
   2.122    void update_maplist(MapStorage *);
   2.123  
   2.124 +  ///Called when window is closing.
   2.125 +
   2.126 +  ///\ref AlgoWin has to be deregistrated in \ref MainWin
   2.127 +  ///thereforeit emits signal \ref signal_closed.
   2.128    void on_hide();
   2.129  };
   2.130  #endif //ALGOWIN_H
     3.1 --- a/gui/kruskalbox.h	Sat Jan 14 08:44:59 2006 +0000
     3.2 +++ b/gui/kruskalbox.h	Sat Jan 14 13:42:37 2006 +0000
     3.3 @@ -11,15 +11,34 @@
     3.4  #include <libgnomecanvasmm.h>
     3.5  #include <libgnomecanvasmm/polygon.h>
     3.6  
     3.7 +///Graphical interface to run Kruskal algorithm.
     3.8 +
     3.9 +///Child of \ref AlgoBox,
    3.10 +///therefore the only task to do at implementation was to
    3.11 +///
    3.12 +///-call init function with correct parameters from correctly parametrized constructor
    3.13 +///
    3.14 +///-implement \ref build_box function
    3.15 +///
    3.16 +///-implement \ref run function
    3.17  class KruskalBox : public AlgoBox
    3.18  {
    3.19 +  ///Shows result of Kruskal algorithm
    3.20    Gtk::Label resultlabel;
    3.21  
    3.22  public:
    3.23 +  ///Calls \ref AlgoBox::init function to initialize class properly, automatically.
    3.24    KruskalBox(std::vector<std::string> t);
    3.25 -    
    3.26 +
    3.27 +  ///Prepare, run and postprocess Kruskal algorithm.
    3.28 +
    3.29 +  ///\ref glemon works only with maps filled with double values
    3.30 +  ///at the moment. While Kruskal nedds a bool map as output.
    3.31 +  ///As postprocess this bool map should be transformed to
    3.32 +  ///double map.
    3.33    void run();
    3.34 -    
    3.35 +
    3.36 +  ///Builds the graphical design of the interface.
    3.37    void build_box();
    3.38  };
    3.39  #endif //KRUSKALBOX_H