Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 127 insertions, 0 deletions

diff --git a/kicker/applets/launcher/popularity.h b/kicker/applets/launcher/popularity.h
new file mode 100644
index 000000000..b1dcb32d6
--- /dev/null
+++ b/kicker/applets/launcher/popularity.h
@@ -0,0 +1,127 @@
+/*****************************************************************
+
+Copyright (c) 2005 Fred Schaettgen <kde.sch@ttgen.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+******************************************************************/
+
+#ifndef __popularity_h__
+#define __popularity_h__
+
+#include <qstring.h>
+#include <qstringlist.h>
+
+class PopularityStatisticsImpl;
+class Prefs;
+
+/**
+ * Tracks the usage of any kind of service to offer recommendations.
+ * A service is identified by a string. After calling @useService
+ * a few times, you can get a popularity ranking for the used
+ * services.
+ * The algorithm tries to take both short- and long-term usage
+ * into account at the same time.
+ * The popularity value can be interpreted as the probability
+ * that the given service will be the next one to be used.
+ * If some new services are suddenly used a few times, their ranking
+ * may grow higher than the ranking of services, which were used very
+ * frequently a while ago. But after this short term usage has
+ * stopped, its influence gets weaker more quickly then for the old, 
+ * more frequently used services.
+ * During first time usage, the algorithm needs some time to stabilize, 
+ * since there is simply no dependable long term usage data available, 
+ * so the ranking is more likely to change at first.
+ * But in the long run, the behaviour of the algorithm is 
+ * completely stable, unlike simple usage counting for instance.
+ */
+class PopularityStatistics
+{
+public:
+    PopularityStatistics();
+    virtual ~PopularityStatistics();
+    
+    /**
+     * Touch a service. This will increase the usage
+     * counters for the given service and decrease the
+     * counters for all the others.
+     */
+    void useService(const QString& service);
+    
+    /**
+     * Exchange all state variables of the most
+     * popular service with those from services,
+     * moving the given services to the top of the
+     * list. Apart from that the order stays the same
+     * as before. Order of items in the string list
+     * does *not* matter/
+     */
+    void moveToTop(const QStringList& services);
+    
+    /**
+     * Sets all counters to zero for the given service
+     */
+    void moveToBottom(const QString& service);
+    
+    /**
+     * Retrieve the name of a service by its position
+     * in the current popularity ranking
+     */
+    QString serviceByRank(int n) const;
+    
+    /**
+     * Retrieve the popularity (0-1) of a service by 
+     * its position in the current popularity ranking
+     */
+    double popularityByRank(int n) const;
+
+    /**
+     * Gets the rank of a given service. 
+     * Returns -1 if the service is not in the ranking
+     */
+    int rankByService(const QString service);
+ 
+    /** 
+     * Writes the configuration.
+     * A section must be set already for config.
+     */
+    void writeConfig(Prefs* prefs) const;
+
+    /**
+     * Reads the configuration.
+     * A section must be set already for config.
+     */
+    void readConfig(Prefs* prefs);
+
+    /**
+     * Modify the weighting of the history logs.
+     * 0 <= h <= 1. 1 means long term history
+     * 0 means short term history - in fact the popularity ranking
+     * becomes a recently-used list in that case.
+     */
+    void setHistoryHorizon(double h);
+    double historyHorizon();
+
+protected:
+    PopularityStatisticsImpl *d;
+
+private:
+    PopularityStatistics(const PopularityStatistics&) {}
+};
+
+#endif