From 45e77707f0fe880b2036c5e269619c17d200e3f8 Mon Sep 17 00:00:00 2001 From: Thilo Graf Date: Fri, 10 Feb 2017 19:10:15 +0100 Subject: [PATCH] CProgressWindow: add documentation for Doxygen --- src/gui/widget/progresswindow.cpp | 2 +- src/gui/widget/progresswindow.h | 156 +++++++++++++++++++++++++++++- 2 files changed, 154 insertions(+), 4 deletions(-) diff --git a/src/gui/widget/progresswindow.cpp b/src/gui/widget/progresswindow.cpp index 564df2204..84c74e15d 100644 --- a/src/gui/widget/progresswindow.cpp +++ b/src/gui/widget/progresswindow.cpp @@ -3,7 +3,7 @@ Copyright (C) 2001 by Steffen Hehn 'McClean' Implementation of CComponent Window class. - Copyright (C) 2014 Thilo Graf 'dbt' + Copyright (C) 2014-2017 Thilo Graf 'dbt' License: GPL diff --git a/src/gui/widget/progresswindow.h b/src/gui/widget/progresswindow.h index 18d4c9273..811b5714a 100644 --- a/src/gui/widget/progresswindow.h +++ b/src/gui/widget/progresswindow.h @@ -3,7 +3,7 @@ Copyright (C) 2001 by Steffen Hehn 'McClean' Implementation of CComponent Window class. - Copyright (C) 2014 Thilo Graf 'dbt' + Copyright (C) 2014-2017 Thilo Graf 'dbt' License: GPL @@ -44,7 +44,92 @@ class CProgressWindow : public CComponentsWindow, public CMenuTarget void fitItems(); public: - + /**CProgressWindow Constructor + * @param[in] parent + * @li optional: expects type CComponentsForm * as possible parent object, default = NULL + * @param[in] dx + * @li optional: expects type const &int, width of window, default = 0, auto size with declared default values + * @param[in] dy + * @li optional: expects type const &int, height of window, default = 0, auto size with declared default values + * @param[in] status_Signal + * @li optional: expects type sigc::signal, defines an optional signal container for + * current changing values. + * @param[in] localSignal + * @li optional: expects type sigc::signal, defines an optional signal container for + * current changing local values. + * @param[in] globalSignal + * @li optional: expects type sigc::signal, defines an optional signal container for + * current changing global values. + * + * @example + * void CFooClass::DoCount{ + * //Usage with classic init inside method: + * + * //Create a CProgressWindow object + * CProgressWindow progress; + * + * //set possible properties, eg. like here we dont't need a header + * status.showHeader(false); + * + * //paint window + * status.paint(); + * + * //set possible properties, like current status text + * status.showStatusMessageUTF("test progress"); + * + * //set current progress, call functions, methods or use a while, next loop or what ever + * status.showStatus(25) + * + * //finally remove window from screen + * status.hide(); + * } + * + * //That's it. Until now these steps are a classical way inside neutrino, but you can use proress window with signals too. + * //Working with signals have the advantage that the implementation could be more compactly, because + * //complex constructions within the classes are usually unnecessary, + * //beacuse of the signals can be installed where they directly take the required values. See next example: + * + * class CFooClass + * { + * //Usage with signals: + * //declare a signal eg. in header file + * private: + * //other members... + * sigc::signal OnProgress; + * //other members... + * public: + * //other members... + * void DoAnything(); + * //other members... + * }; + * + * //add the OnProgress signal into a counter methode + * void CFooClass::DoCount{ + * size_t max = 10 + * for (size_t i = 0; i < max; i++){ + * OnProgress(i, max, "Test"); + * } + * } + * + * void CFooClass::DoAnything{ + * //inside of methode which calls the progress define a CProgressWindow object and the counter method: + * //...any code + * CProgressWindow progress(NULL, 500, 150, &OnProgress); + * //paint window + * progress.paint(); // paint() + * + * //... + * + * DoCount(); + * + * //... + * + * //finally remove window from screen + * progress.hide(); + * } + * @note + * Don't use status_Signal at same time with localSignal and globalSignal. In This case please set status_Signal = NULL + */ CProgressWindow(CComponentsForm *parent = NULL, const int &dx = 700, const int &dy = 200, @@ -52,6 +137,12 @@ class CProgressWindow : public CComponentsWindow, public CMenuTarget sigc::signal *localSignal = NULL, sigc::signal *globalSignal = NULL); + /**CProgressWindow Constructor + * @param[in] title + * @li expects type neutrino_locale_t as window title + * + * @see For other arguments and examples, see related constructor(s) + */ CProgressWindow(const neutrino_locale_t title, const int &dx = 700, const int &dy = 200, @@ -59,18 +150,77 @@ class CProgressWindow : public CComponentsWindow, public CMenuTarget sigc::signal *localSignal = NULL, sigc::signal *globalSignal = NULL); + /**Sets titel of window + * @param[in] title + * @li expects type neutrino_locale_t as window title + */ void setTitle(const neutrino_locale_t title); + + /**Sets titel of window + * @param[in] title + * @li expects type std::string as window title + */ + void setTitle(const std::string & title); + + /** + * Remove window from screen, restores background. + */ virtual void hide(); + /** + * Executes the exec contents. In this case it will paint the window and remove possible parents from screen + * @param[in] parent + * @li optional: expects type CMenuTarget* + * @param[in] actionKey + * @li optional: without effect + * @return int = menu_return::RETURN_REPAINT + */ virtual int exec( CMenuTarget* parent, const std::string & actionKey ); + /** + * Sets current progress value and show progress in window. + * @param[in] prog + * @li expects type unsigned int, describes current progress value + * @param[in] max + * @li optional: expects type unsigned int, describes maximal progress value, default = 100 + * @param[in] statusText + * @li optional: expects type std::string, describes current status text, default = empty + */ void showStatus(const unsigned int prog, const unsigned int max = 100, const std::string &statusText = std::string()); + + /** + * Sets current local progressbar value and show progress in window. + * @note For other arguments take a look to related method showStatus() + * @see showStatus() + */ void showLocalStatus(const unsigned int prog, const unsigned int max = 100, const std::string &statusText = std::string()); + + /** + * Sets current global progressbar value and show progress in window. + * @note For other arguments take a look to related method showStatus() + * @see showStatus() + */ void showGlobalStatus(const unsigned int prog, const unsigned int max = 100, const std::string &statusText = std::string()); + + /** + * Gets current progress value + * @return unsigned int + */ unsigned int getGlobalStatus(void); + + /** + * Sets current progress value and show progress in window. + * @param[in] text + * @li expects type std::string, describes current status text + */ void showStatusMessageUTF(const std::string & text); // UTF-8 + + /** + * Paint window + * @param[in] do_save_bg + * @li optional: expects type bool, sets background save mode + */ void paint(bool do_save_bg = true); - void setTitle(const std::string & title); };