apps/konqueror/src/konqhistorymanager.h

   1 /* This file is part of the KDE project
   2    Copyright (C) 2000,2001 Carsten Pfeiffer <pfeiffer@kde.org>
   3    Copyright 2007 David Faure <faure@kde.org>
   4
   5    This program is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13     General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; see the file COPYING.  If not, write to
  17    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18    Boston, MA 02110-1301, USA.
  19 */
  20
  21 #ifndef KONQ_HISTORYMANAGER_H
  22 #define KONQ_HISTORYMANAGER_H
  23
  24 #include <QtCore/QObject>
  25 #include <QtCore/QMap>
  26 #include <QtCore/QTimer>
  27 #include <QtCore/QStringList>
  28
  29 #include <kparts/historyprovider.h>
  30
  31 #include "konqhistoryentry.h"
  32
  33 class KBookmarkManager;
  34 class QDBusMessage;
  35 class KCompletion;
  36
  37 class KONQUERORPRIVATE_EXPORT KonqHistoryList : public QList<KonqHistoryEntry>
  38 {
  39 public:
  40     /**
  41      * Finds an entry by URL and return an iterator to it.
  42      * If no matching entry is found, end() is returned.
  43      */
  44     iterator findEntry( const KUrl& url );
  45
  46     /**
  47      * Finds an entry by URL and removes it
  48      */
  49     void removeEntry( const KUrl& url );
  50 };
  51
  52
  53 ///////////////////////////////////////////////////////////////////
  54
  55
  56 /**
  57  * This class maintains and manages a history of all URLs visited by one
  58  * Konqueror instance. Additionally it synchronizes the history with other
  59  * Konqueror instances via DBUS to keep one global and persistant history.
  60  *
  61  * It keeps the history in sync with one KCompletion object
  62  */
  63 class KONQUERORPRIVATE_EXPORT KonqHistoryManager : public KParts::HistoryProvider
  64 {
  65     Q_OBJECT
  66
  67 public:
  68     /**
  69      * Returns the KonqHistoryManager instance. This relies on a KonqHistoryManager instance
  70      * being created first!
  71      * This is a bit like "qApp": you can access the instance anywhere, but you need to
  72      * create it first.
  73      */
  74     static KonqHistoryManager *kself() {
  75         return static_cast<KonqHistoryManager*>( KParts::HistoryProvider::self() );
  76     }
  77
  78     explicit KonqHistoryManager( KBookmarkManager* bookmarkManager, QObject *parent = 0 );
  79     ~KonqHistoryManager();
  80
  81     /**
  82      * Sets a new maximum size of history and truncates the current history
  83      * if necessary. Notifies all other Konqueror instances via DBUS
  84      * to do the same.
  85      *
  86      * The history is saved after receiving the DBUS call.
  87      */
  88     void emitSetMaxCount( int count );
  89
  90     /**
  91      * Sets a new maximum age of history entries and removes all entries that
  92      * are older than @p days. Notifies all other Konqueror instances via DBUS
  93      * to do the same.
  94      *
  95      * An age of 0 means no expiry based on the age.
  96      *
  97      * The history is saved after receiving the DBUS call.
  98      */
  99     void emitSetMaxAge( int days );
 100
 101     /**
 102      * Removes the history entry for @p url, if existent. Tells all other
 103      * Konqueror instances via DBUS to do the same.
 104      *
 105      * The history is saved after receiving the DBUS call.
 106      */
 107     void emitRemoveFromHistory( const KUrl& url );
 108
 109     /**
 110      * Removes the history entries for the given list of @p urls. Tells all
 111      * other Konqueror instances via DBUS to do the same.
 112      *
 113      * The history is saved after receiving the DBUS call.
 114      */
 115     void emitRemoveListFromHistory( const KUrl::List& urls );
 116
 117     /**
 118      * @returns the current maximum number of history entries.
 119      */
 120     int maxCount() const { return m_maxCount; }
 121
 122     /**
 123      * @returns the current maximum age (in days) of history entries.
 124      */
 125     int maxAge() const { return m_maxAgeDays; }
 126
 127     /**
 128      * Adds a pending entry to the history. Pending means, that the entry is
 129      * not verified yet, i.e. it is not sure @p url does exist at all. You
 130      * probably don't know the title of the url in that case either.
 131      * Call @ref confirmPending() as soon you know the entry is good and should
 132      * be updated.
 133      *
 134      * If an entry with @p url already exists,
 135      * it will be updated (lastVisited date will become the current time
 136      * and the number of visits will be incremented).
 137      *
 138      * @param url The url of the history entry
 139      * @param typedUrl the string that the user typed, which resulted in url
 140      *                 Doesn't have to be a valid url, e.g. "slashdot.org".
 141      * @param title The title of the URL. If you don't know it (yet), you may
 142                     specify it in @ref confirmPending().
 143      */
 144     void addPending( const KUrl& url, const QString& typedUrl = QString(),
 145                      const QString& title = QString() );
 146
 147     /**
 148      * Confirms and updates the entry for @p url.
 149      */
 150     void confirmPending( const KUrl& url,
 151                          const QString& typedUrl = QString(),
 152                          const QString& title = QString() );
 153
 154     /**
 155      * Removes a pending url from the history, e.g. when the url does not
 156      * exist, or the user aborted loading.
 157      */
 158     void removePending( const KUrl& url );
 159
 160     /**
 161      * @returns the KCompletion object.
 162      */
 163     KCompletion * completionObject() const { return m_pCompletion; }
 164
 165     /**
 166      * @returns the list of all history entries, sorted by date
 167      * (oldest entries first)
 168      */
 169     const KonqHistoryList& entries() const { return m_history; }
 170
 171     // HistoryProvider interface, let konq handle this
 172     /**
 173      * Reimplemented in such a way that all URLs that would be filtered
 174      * out normally (see @ref filterOut()) will still be added to the history.
 175      * By default, file:/ urls will be filtered out, but if they come thru
 176      * the HistoryProvider interface, they are added to the history.
 177      */
 178     virtual void insert( const QString& );
 179     virtual void remove( const QString& ) {}
 180     virtual void clear() {}
 181
 182
 183 public Q_SLOTS:
 184     /**
 185      * Loads the history and fills the completion object.
 186      */
 187     bool loadHistory();
 188
 189     /**
 190      * Saves the entire history.
 191      */
 192     bool saveHistory();
 193
 194     /**
 195      * Clears the history and tells all other Konqueror instances via DBUS
 196      * to do the same.
 197      * The history is saved afterwards, if necessary.
 198      */
 199     void emitClear();
 200
 201
 202 Q_SIGNALS:
 203     /**
 204      * Emitted after the entire history was loaded from disk.
 205      */
 206     void loadingFinished();
 207
 208     /**
 209      * Emitted after a new entry was added
 210      */
 211     void entryAdded( const KonqHistoryEntry& entry );
 212
 213     /**
 214      * Emitted after an entry was removed from the history
 215      * Note, that this entry will be deleted immediately after you got
 216      * that signal.
 217      */
 218     void entryRemoved( const KonqHistoryEntry& entry );
 219
 220 protected:
 221     /**
 222      * Resizes the history list to contain less or equal than m_maxCount
 223      * entries. The first (oldest) entries are removed.
 224      */
 225     void adjustSize();
 226
 227     /**
 228      * Notifes all running instances about a new HistoryEntry via DBUS
 229      */
 230     void emitAddToHistory( const KonqHistoryEntry& entry );
 231
 232 Q_SIGNALS: // DBUS methods/signals
 233
 234     /**
 235      * Every konqueror instance broadcasts new history entries to the other
 236      * konqueror instances. Those add the entry to their list, but don't
 237      * save the list, because the sender saves the list.
 238      *
 239      * @param e the new history entry
 240      * @param saveId is the dbus service of the sender so that
 241      * only the sender saves the new history.
 242      */
 243     void notifyHistoryEntry( const QByteArray & historyEntry );
 244
 245     /**
 246      * Called when the configuration of the maximum count changed.
 247      * Called via DBUS by some config-module
 248      */
 249     void notifyMaxCount( int count );
 250
 251     /**
 252      * Called when the configuration of the maximum age of history-entries
 253      * changed. Called via DBUS by some config-module
 254      */
 255     void notifyMaxAge( int days );
 256
 257     /**
 258      * Clears the history completely. Called via DBUS by some config-module
 259      */
 260     void notifyClear();
 261
 262     /**
 263      * Notifes about a url that has to be removed from the history.
 264      * The sender instance has to save the history.
 265      */
 266     void notifyRemove( const QString& url );
 267
 268     /**
 269      * Notifes about a list of urls that has to be removed from the history.
 270      * The sender instance has to save the history.
 271      */
 272     void notifyRemoveList( const QStringList& urls );
 273
 274 private Q_SLOTS: // connected to DBUS signals
 275     /**
 276      * @returns a list of all urls in the history.
 277      */
 278     //QStringList allURLs() const;
 279
 280     void slotNotifyHistoryEntry( const QByteArray & historyEntry, const QDBusMessage& msg );
 281     void slotNotifyMaxCount( int count, const QDBusMessage& msg );
 282     void slotNotifyMaxAge( int days, const QDBusMessage& msg );
 283     void slotNotifyClear( const QDBusMessage& msg );
 284     void slotNotifyRemove( const QString& url, const QDBusMessage& msg );
 285     void slotNotifyRemoveList( const QStringList& urls, const QDBusMessage& msg );
 286
 287 private:
 288     /**
 289      * Does the work for @ref addPending() and @ref confirmPending().
 290      *
 291      * Adds an entry to the history. If an entry with @p url already exists,
 292      * it will be updated (lastVisited date will become the current time
 293      * and the number of visits will be incremented).
 294      * @p pending means, the entry has not been "verified", it's been added
 295      * right after typing the url.
 296      * If @p pending is false, @p url will be removed from the pending urls
 297      * (if available) and NOT be added again in that case.
 298      */
 299     void addToHistory( bool pending, const KUrl& url,
 300                        const QString& typedUrl = QString(),
 301                        const QString& title = QString() );
 302
 303
 304     /**
 305      * @returns true if the given @p url should be filtered out and not be
 306      * added to the history. By default, all local urls (url.isLocalFile())
 307      * will return true, as well as urls with an empty host.
 308      */
 309     virtual bool filterOut( const KUrl& url );
 310
 311     void addToUpdateList( const QString& url ) {
 312         m_updateURLs.append( url );
 313         m_updateTimer->setSingleShot( true );
 314         m_updateTimer->start( 500 );
 315     }
 316
 317     /**
 318      * The list of urls that is going to be emitted in slotEmitUpdated. Add
 319      * urls to it whenever you modify the list of history entries and start
 320      * m_updateTimer.
 321      */
 322     QStringList m_updateURLs;
 323
 324 private Q_SLOTS:
 325     /**
 326      * Called by the updateTimer to emit the KParts::HistoryProvider::updated()
 327      * signal so that khtml can repaint the updated links.
 328      */
 329     void slotEmitUpdated();
 330
 331 private:
 332     /**
 333      * Returns whether the DBUS call we are handling was a call from us self
 334      */
 335     bool isSenderOfSignal( const QDBusMessage& msg );
 336
 337     void clearPending();
 338     /**
 339      * a little optimization for KonqHistoryList::findEntry(),
 340      * checking the dict of KParts::HistoryProvider before traversing the list.
 341      * Can't be used everywhere, because it always returns end() for "pending"
 342      * entries, as those are not added to the dict, currently.
 343      */
 344     KonqHistoryList::iterator findEntry( const KUrl& url );
 345
 346     /**
 347      * Stuff to create a proper history out of KDE 2.0's konq_history for
 348      * completion.
 349      */
 350     bool loadFallback();
 351     KonqHistoryEntry createFallbackEntry( const QString& ) const;
 352
 353     void addToCompletion( const QString& url, const QString& typedUrl, int numberOfTimesVisited = 1 );
 354     void removeFromCompletion( const QString& url, const QString& typedUrl );
 355
 356     /**
 357      * Ensures that the items are sorted by the lastVisited date
 358      * (oldest goes first)
 359      */
 360     static bool lastVisitedOrder( const KonqHistoryEntry& lhs, const KonqHistoryEntry& rhs ) {
 361         return lhs.lastVisited < rhs.lastVisited;
 362     }
 363
 364     QString m_filename;
 365     KonqHistoryList m_history;
 366
 367     /**
 368      * List of pending entries, which were added to the history, but not yet
 369      * confirmed (i.e. not yet added with pending = false).
 370      * Note: when removing an entry, you have to delete the KonqHistoryEntry
 371      * of the item you remove.
 372      */
 373     QMap<QString,KonqHistoryEntry*> m_pending;
 374
 375     int m_maxCount;   // maximum of history entries
 376     int m_maxAgeDays; // maximum age of a history entry
 377
 378     KCompletion *m_pCompletion; // the completion object we sync with
 379
 380     /**
 381      * A timer that will emit the KParts::HistoryProvider::updated() signal
 382      * thru the slotEmitUpdated slot.
 383      */
 384     QTimer *m_updateTimer;
 385
 386     KBookmarkManager* m_bookmarkManager;
 387
 388     static const int s_historyVersion;
 389 };
 390
 391
 392 #endif // KONQ_HISTORY_H