1 #pragma once
2 /*
3  *   Summary:	Utility object to track user activity
4  *   License:	LGPL - See file COPYING.LIB for details.
5  *   Author:	Stefan Hundhammer <sh@suse.de>
6  */
7 
8 #include <qobject.h>
9 
10 /**
11  * Helper class to track user activity of any kind: When the user uses an
12  * application's actions (menu items etc.), those actions notify this object of
13  * that fact. Each action has an amount of "activity points" assigned
14  * (i.e. what this action is "worth"). Those points are summed up here, and
15  * when a certain number of points is reached, a signal is triggered. This
16  * signal can be used for example to ask the user if he wouldn't like to rate
17  * this program - or register it if this is a shareware program.
18  *
19  * @short User activity tracker
20  **/
21 class KActivityTracker : public QObject {
22   Q_OBJECT
23 public:
24   /**
25    * Constructor. The ID is a name for the KConfig object to look in for
26    * accumulated activity points so far. 'initialThreshold' is only used if
27    * the application's @ref KConfig object doesn't contain a corresponding
28    * entry yet.
29    **/
30   KActivityTracker(QObject *parent, const QString &id, long initialThreshold);
31 
32   /**
33    * Destructor.
34    **/
35   virtual ~KActivityTracker();
36 
37   /**
38    * Returns the number of activity points accumulated so far.
39    **/
sum()40   long sum() const { return _sum; }
41 
42   /**
43    * Sets the activity threshold, i.e. when a signal will be sent.
44    **/
45   void setThreshold(long threshold);
46 
47   /**
48    * Returns the current threshold.
49    **/
threshold()50   long threshold() const { return _threshold; }
51 
52   /**
53    * Check the sum of activity points accumulated so far against the current
54    * threshold and emit a signal if appropriate.
55    **/
56   void checkThreshold();
57 
58 public slots:
59 
60   /**
61    * Track an activity, i.e. add the specified amount of activity points to
62    * the accumulated sum.
63    **/
64   void trackActivity(int points);
65 
66   /**
67    * Set the threshold to its double value.
68    **/
doubleThreshold()69   void doubleThreshold() { setThreshold(2 * threshold()); }
70 
71 signals:
72 
73   /**
74    * Emitted when the activity threshold is reached.
75    *
76    * You might want to set the threshold to a new value when this signal is
77    * emitted. You can simply connect it to @ref doubleThreshold().
78    **/
79   void thresholdReached(void);
80 
81 protected:
82   long _sum;
83   long _threshold;
84   long _lastSignal;
85   QString _id;
86 };
87 
88