# HG changeset patch # User hegyi # Date 1137246157 0 # Node ID e8bf8bbcf75af92f061cec0a5287ddc999e3106a # Parent b8d778d4d100ef26108c662b733f392f46374f23 Documentation of classes realizing algorithm running. diff -r b8d778d4d100 -r e8bf8bbcf75a algobox.h --- a/algobox.h Sat Jan 14 08:17:00 2006 +0000 +++ b/algobox.h Sat Jan 14 13:42:37 2006 +0000 @@ -11,42 +11,157 @@ #include #include +///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 signal_maplist_need; - sigc::signal 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 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 signal_newmapwin_need; protected: + ///Holder of tabnames. Gtk::ComboBoxText tabcbt; + + ///Holder of widgets, in which nodemaps can be selected to work on. std::vector nodemapcbts; + + ///Holder of widgets, in which edgemaps can be selected to work on. std::vector edgemapcbts; + ///Maps of selected tabs. MapStorage * mapstorage; public: + ///Empty constructor called by children. AlgoBox(){}; - AlgoBox(std::vector); + ///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 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); - sigc::signal signal_maplist_needed(); - sigc::signal signal_newmapwin_needed(){return signal_newmapwin_need;}; + ///Signal emitted, when selected tab changes, and new list of maps required. + sigc::signal signal_maplist_needed(); + + ///Emitted if user wants to create a new map for inpuit or output. + sigc::signal 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 diff -r b8d778d4d100 -r e8bf8bbcf75a algowin.h --- a/algowin.h Sat Jan 14 08:17:00 2006 +0000 +++ b/algowin.h Sat Jan 14 13:42:37 2006 +0000 @@ -13,35 +13,122 @@ 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 signal_closed; - sigc::signal signal_maplist_need; - sigc::signal 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 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 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 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 signal_closing(); + + ///Returns \ref signal_maplist_need to be bindable somewhere. sigc::signal signal_maplist_needed(); - sigc::signal signal_newmapwin_needed(){return signal_newmapwin_need;}; + ///Returns \ref signal_newmapwin_need to be bindable somewhere. + sigc::signal 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); + ///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 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 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(); }; #endif //ALGOWIN_H diff -r b8d778d4d100 -r e8bf8bbcf75a kruskalbox.h --- a/kruskalbox.h Sat Jan 14 08:17:00 2006 +0000 +++ b/kruskalbox.h Sat Jan 14 13:42:37 2006 +0000 @@ -11,15 +11,34 @@ #include #include +///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 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(); }; #endif //KRUSKALBOX_H