Commit 0063f780 authored by Timothy M. Shead's avatar Timothy M. Shead
Browse files

STYLE: Improved source documentation

parent 200ad84b
...@@ -46,14 +46,16 @@ Manages playback of test-cases, demos, tutorials, etc. ...@@ -46,14 +46,16 @@ Manages playback of test-cases, demos, tutorials, etc.
pqEventPlayer converts high-level ParaView events pqEventPlayer converts high-level ParaView events
(button click, row selection, etc) into low-level Qt events (button click, row selection, etc) into low-level Qt events
that drive the user interface. that drive the user interface.
The high-level events created by pqEventTranslator are fed to The high-level events created by pqEventTranslator are fed to
pqEventPlayer::playEvent() one-by-one, which passes each event pqEventPlayer::playEvent() one-by-one, which passes each event
through a collection of pqWidgetEventPlayer objects. through a collection of pqWidgetEventPlayer objects. Each
Once a pqWidgetEventPlayer accepts the event and updates Qt, pqWidgetEventPlayer has the chance to ignore the event or
playEvent() returns, ready for the next high-level event. accept and update the program state using low-level Qt events.
pqEventPlayerXML is an example of an object that can retrieve pqEventDispatcher is an example of an object that can retrieve
high-level events from a file, feeding them to pqEventPlayer. high-level events from a pqEventSource object, feeding them
to pqEventPlayer.
For specialized Qt widgets it may be necessary to create "custom" For specialized Qt widgets it may be necessary to create "custom"
pqWidgetEventPlayer derivatives, which can be added to pqEventPlayer pqWidgetEventPlayer derivatives, which can be added to pqEventPlayer
...@@ -62,7 +64,8 @@ pqWidgetEventPlayer objects are searched in order for ...@@ -62,7 +64,8 @@ pqWidgetEventPlayer objects are searched in order for
event playback, so you can also use this mechanism to event playback, so you can also use this mechanism to
"override" the builtin event players. "override" the builtin event players.
\sa pqWidgetEventPlayer, pqEventTranslator, pqEventPlayerXML \sa pqWidgetEventPlayer, pqEventTranslator, pqEventDispatcher,
pqEventSource, pqXMLEventSource
*/ */
class QTTESTING_EXPORT pqEventPlayer : class QTTESTING_EXPORT pqEventPlayer :
...@@ -74,17 +77,25 @@ public: ...@@ -74,17 +77,25 @@ public:
pqEventPlayer(); pqEventPlayer();
~pqEventPlayer(); ~pqEventPlayer();
/// Adds the default set of widget players to the current working set. /** Adds the default set of widget players to the current working set.
/// Players are executed in-order, so you can call addWidgetEventPlayer() Players are executed in-order, so you can call addWidgetEventPlayer()
/// before this function to override default players. before this function to override default players. */
void addDefaultWidgetEventPlayers(); void addDefaultWidgetEventPlayers();
/// Adds a new player to the current working set of widget players. /** Adds a new player to the current working set of widget players.
/// pqEventPlayer assumes control of the lifetime of the supplied object. pqEventPlayer assumes control of the lifetime of the supplied object. */
void addWidgetEventPlayer(pqWidgetEventPlayer*); void addWidgetEventPlayer(pqWidgetEventPlayer*);
/// This method is called with each high-level ParaView event, which
/// will invoke the corresponding low-level Qt functionality in-turn. /** This method is called with each high-level ParaView event, which
/// If there was an error playing the event, the error() signal is emitted will invoke the corresponding low-level Qt functionality in-turn.
void playEvent(const QString& Object, const QString& Command, const QString& Arguments, bool& Error); If there was an error playing the event, Error argument will be set
to "true". Note: Currently there is no guarantee that playEvent()
will return immediately, since the functionality it invokes may enter
a separate event loop (a modal dialog or context menu, for example). */
void playEvent(
const QString& Object,
const QString& Command,
const QString& Arguments,
bool& Error);
private: private:
pqEventPlayer(const pqEventPlayer&); pqEventPlayer(const pqEventPlayer&);
...@@ -96,4 +107,3 @@ private: ...@@ -96,4 +107,3 @@ private:
}; };
#endif // !_pqEventPlayer_h #endif // !_pqEventPlayer_h
...@@ -43,7 +43,8 @@ class QTTESTING_EXPORT pqEventSource ...@@ -43,7 +43,8 @@ class QTTESTING_EXPORT pqEventSource
public: public:
virtual ~pqEventSource() {} virtual ~pqEventSource() {}
/// Retrieves the next available event. Returns true if an event was returned, false if there are no more events /** Retrieves the next available event. Returns true if an event was
returned, false if there are no more events. */
virtual bool getNextEvent( virtual bool getNextEvent(
QString& object, QString& object,
QString& command, QString& command,
......
...@@ -45,7 +45,7 @@ signal. ...@@ -45,7 +45,7 @@ signal.
\note Output is sent to the stream from this object's destructor, so you \note Output is sent to the stream from this object's destructor, so you
must ensure that it goes out of scope before trying to playback the stream. must ensure that it goes out of scope before trying to playback the stream.
\sa pqEventObserverStdout, pqEventTranslator, pqEventPlayerXML \sa pqEventTranslator, pqStdoutEventObserver, pqXMLEventSource.
*/ */
class pqXMLEventObserver : class pqXMLEventObserver :
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment