From 625644e917ceadc7d61238089f1c849cf6636cbe Mon Sep 17 00:00:00 2001 From: scrawl Date: Tue, 15 Dec 2015 21:03:56 +0100 Subject: [PATCH] LoadingScreen: documentation updates --- apps/openmw/mwgui/loadingscreen.hpp | 3 +-- components/loadinglistener/loadinglistener.hpp | 13 +++++++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/apps/openmw/mwgui/loadingscreen.hpp b/apps/openmw/mwgui/loadingscreen.hpp index 92a3d9355e..ce9f0f6dc2 100644 --- a/apps/openmw/mwgui/loadingscreen.hpp +++ b/apps/openmw/mwgui/loadingscreen.hpp @@ -33,11 +33,10 @@ namespace MWGui LoadingScreen(const VFS::Manager* vfs, osgViewer::Viewer* viewer); virtual ~LoadingScreen(); + /// Overridden from Loading::Listener, see the Loading::Listener documentation for usage details virtual void setLabel (const std::string& label); - virtual void loadingOn(); virtual void loadingOff(); - virtual void setProgressRange (size_t range); virtual void setProgress (size_t value); virtual void increaseProgress (size_t increase=1); diff --git a/components/loadinglistener/loadinglistener.hpp b/components/loadinglistener/loadinglistener.hpp index e9a8cd3c7e..04e50dd28c 100644 --- a/components/loadinglistener/loadinglistener.hpp +++ b/components/loadinglistener/loadinglistener.hpp @@ -1,23 +1,32 @@ #ifndef COMPONENTS_LOADINGLISTENER_H #define COMPONENTS_LOADINGLISTENER_H +#include + namespace Loading { class Listener { public: + /// Set a text label to show on the loading screen. virtual void setLabel (const std::string& label) {} - // Use ScopedLoad instead of using these directly + /// Start a loading sequence. Must call loadingOff() when done. + /// @note To get the loading screen to actually update, you must call setProgress / increaseProgress periodically. + /// @note It is best to use the ScopedLoad object instead of using loadingOn()/loadingOff() directly, + /// so that the loading is exception safe. virtual void loadingOn() {} virtual void loadingOff() {} + /// Set the total range of progress (e.g. the number of objects to load). virtual void setProgressRange (size_t range) {} + /// Set current progress. Valid range is [0, progressRange) virtual void setProgress (size_t value) {} + /// Increase current progress, default by 1. virtual void increaseProgress (size_t increase = 1) {} }; - // Used for stopping a loading sequence when the object goes out of scope + /// @brief Used for stopping a loading sequence when the object goes out of scope struct ScopedLoad { ScopedLoad(Listener* l) : mListener(l) { mListener->loadingOn(); }