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/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 367 insertions, 0 deletions

diff --git a/kio/bookmarks/kbookmarkmanager.h b/kio/bookmarks/kbookmarkmanager.h
new file mode 100644
index 000000000..03d0ac0c6
--- /dev/null
+++ b/kio/bookmarks/kbookmarkmanager.h
@@ -0,0 +1,367 @@
+//  -*- c-basic-offset:4; indent-tabs-mode:nil -*-
+// vim: set ts=4 sts=4 sw=4 et:
+/* This file is part of the KDE libraries
+   Copyright (C) 2000 David Faure <faure@kde.org>
+
+   This library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Library General Public
+   License version 2 as published by the Free Software Foundation.
+
+   This library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Library General Public License for more details.
+
+   You should have received a copy of the GNU Library General Public License
+   along with this library; see the file COPYING.LIB.  If not, write to
+   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+   Boston, MA 02110-1301, USA.
+*/
+#ifndef __kbookmarkmanager_h
+#define __kbookmarkmanager_h
+
+#include <qstring.h>
+#include <qstringlist.h>
+#include <qobject.h>
+#include <qdom.h>
+#include <dcopobject.h>
+#include "kbookmark.h"
+#include "kbookmarknotifier.h"
+
+/**
+ * This class implements the reading/writing of bookmarks in XML.
+ * The bookmarks file is read and written using the XBEL standard
+ * (http://pyxml.sourceforge.net/topics/xbel/)
+ *
+ * A sample file looks like this :
+ * \code
+ * <xbel>
+ *   <bookmark href="http://developer.kde.org"><title>Developer Web Site</title></bookmark>
+ *   <folder folded="no">
+ *     <title>Title of this folder</title>
+ *     <bookmark icon="kde" href="http://www.kde.org"><title>KDE Web Site</title></bookmark>
+ *     <folder toolbar="yes">
+ *       <title>My own bookmarks</title>
+ *       <bookmark href="http://www.koffice.org"><title>KOffice Web Site</title></bookmark>
+ *       <separator/>
+ *       <bookmark href="http://www.kdevelop.org"><title>KDevelop Web Site</title></bookmark>
+ *     </folder>
+ *   </folder>
+ * </xbel>
+ * \endcode
+ */
+class KIO_EXPORT KBookmarkManager : public QObject, public DCOPObject
+{
+    Q_OBJECT
+    K_DCOP
+protected:
+    /**
+     * Creates a bookmark manager with a path to the bookmarks.  By
+     * default, it will use the KDE standard dirs to find and create the
+     * correct location.  If you are using your own app-specific
+     * bookmarks directory, you must instantiate this class with your
+     * own path <em>before</em> KBookmarkManager::managerForFile() is ever
+     * called.
+     *
+     * @param bookmarksFile full path to the bookmarks file,
+     * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
+     *
+     * @param bImportDesktopFiles if true, and if the bookmarksFile
+     * doesn't already exist, import bookmarks from desktop files
+     */
+    KBookmarkManager( const QString & bookmarksFile, bool bImportDesktopFiles = true );
+
+    /**
+     * @since 3.2
+     */
+    KBookmarkManager();
+
+public:
+    /**
+     * Destructor
+     */
+    ~KBookmarkManager();
+
+    /**
+     * Set the update flag. Defaults to true. TODO - check
+     * @param update if true then KBookmarkManager will listen to DCOP update requests.
+     */
+    void setUpdate( bool update );
+
+    /**
+     * Save the bookmarks to the default konqueror XML file on disk.
+     * You should use emitChanged() instead of this function, it saves
+     * and notifies everyone that the file has changed.
+     * @param toolbarCache iff true save a cache of the toolbar folder, too
+     * @return true if saving was successful
+     */
+    bool save( bool toolbarCache = true ) const;
+
+    /**
+     * Save the bookmarks to the given XML file on disk.
+     * @param filename full path to the desired bookmarks file location
+     * @param toolbarCache iff true save a cache of the toolbar folder, too
+     * @return true if saving was successful
+     */
+    bool saveAs( const QString & filename, bool toolbarCache = true ) const;
+
+    /**
+     * Update access time stamps for a given url.
+     * @param url the viewed url
+     * @param emitSignal iff true emit KBookmarkNotifier signal
+     * @since 3.2
+     * @return true if any metadata was modified (bookmarks file is not saved automatically)
+     */
+    bool updateAccessMetadata( const QString &url, bool emitSignal = true );
+
+    /*
+     * NB. currently *unimplemented*
+     *
+     * Update favicon url for a given url.
+     * @param url the viewed url
+     * @param faviconurl the favicion url
+     * @emitSignal iff true emit KBookmarkNotifier signal
+     * @since 3.3
+     */
+    void updateFavicon( const QString &url, const QString &faviconurl, bool emitSignal = true );
+
+    /**
+     * This will return the path that this manager is using to read
+     * the bookmarks.
+     * @internal
+     * @return the path containing the bookmarks
+     */
+    QString path() { return m_bookmarksFile; }
+
+    /**
+     * This will return the root bookmark.  It is used to iterate
+     * through the bookmarks manually.  It is mostly used internally.
+     *
+     * @return the root (top-level) bookmark
+     */
+    KBookmarkGroup root() const;
+
+    /**
+     * This returns the root of the toolbar menu.
+     * In the XML, this is the group with the attribute TOOLBAR=1
+     *
+     * @return the toolbar group
+     */
+    KBookmarkGroup toolbar();
+
+    /**
+     * @return the bookmark designated by @p address
+     * @param address the address belonging to the bookmark you're looking for
+     * @param tolerate when true tries to find the most tolerable bookmark position
+     * @see KBookmark::address
+     */
+    KBookmark findByAddress( const QString & address, bool tolerate = false );
+
+    /**
+     * Saves the bookmark file and notifies everyone.
+     * @param group the parent of all changed bookmarks
+     */
+    void emitChanged( KBookmarkGroup & group );
+
+    void emitConfigChanged();
+
+    /**
+     * @return true if the NS bookmarks should be dynamically shown
+     *         in the toplevel kactionmenu
+     * @deprecated
+     */
+    bool showNSBookmarks() const;
+
+    /**
+     * Shows an extra menu for NS bookmarks. Set this to false, if you don't
+     * want this.
+     */
+    void setShowNSBookmarks( bool show );
+
+    /**
+     * Set options with which slotEditBookmarks called keditbookmarks
+     * this can be used to change the appearance of the keditbookmarks
+     * in order to provide a slightly differing outer shell depending
+     * on the bookmarks file / app which calls it.
+     * @param caption the --caption string, for instance "Konsole"
+     * @param browser iff false display no browser specific
+     *            menu items in keditbookmarks :: --nobrowser
+     * @since 3.2
+     */
+    void setEditorOptions( const QString& caption, bool browser );
+
+    /**
+     * This static function will return an instance of the
+     * KBookmarkManager, responsible for the given @p bookmarksFile.
+     * If you do not instantiate this class either
+     * natively or in a derived class, then it will return an object
+     * with the default behaviors.  If you wish to use different
+     * behaviors, you <em>must</em> derive your own class and
+     * instantiate it before this method is ever called.
+     *
+     * @param bookmarksFile full path to the bookmarks file,
+     * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
+     *
+     * @param bImportDesktopFiles if true, and if the bookmarksFile
+     * doesn't already exist, import bookmarks from desktop files
+     * @return a pointer to an instance of the KBookmarkManager.
+     */
+    static KBookmarkManager* managerForFile( const QString& bookmarksFile,
+                                   bool bImportDesktopFiles = true );
+
+
+    static KBookmarkManager* createTempManager();
+
+    /**
+     * Returns a pointer to the users main bookmark collection.
+     * @since 3.2
+     */
+    static KBookmarkManager* userBookmarksManager();
+    
+    /**
+     * Returns the path to the user's main bookmark collection file.
+     * @since 3.5.5
+     */
+    static QString userBookmarksFile();
+
+    /**
+     * @internal
+     */
+    const QDomDocument & internalDocument() const;
+
+    /**
+     * Access to bookmark notifier, for emitting signals.
+     * We need this object to exist in one instance only, so we could
+     * connectDCOP to it by name.
+     */
+    KBookmarkNotifier& notifier() { return m_notifier; }
+
+    /**
+     * @since 3.2
+     */
+    KBookmarkGroup addBookmarkDialog( const QString & _url, const QString & _title,
+                                      const QString & _parentBookmarkAddress = QString::null );
+
+public slots:
+    void slotEditBookmarks();
+    void slotEditBookmarksAtAddress( const QString& address );
+
+public:
+k_dcop:
+    /**
+     * Reparse the whole bookmarks file and notify about the change
+     * (Called by the bookmark editor)
+     */
+    ASYNC notifyCompleteChange( QString caller );
+
+    /**
+     * Emit the changed signal for the group whose address is given
+     * @see KBookmark::address()
+     * Called by the instance of konqueror that saved the file after
+     * a small change (new bookmark or new folder).
+     */
+    ASYNC notifyChanged( QString groupAddress );
+
+    ASYNC notifyConfigChanged();
+
+signals:
+    /**
+     * Signals that the group (or any of its children) with the address 
+     * @p groupAddress (e.g. "/4/5")
+     * has been modified by the caller @p caller.
+     */
+    void changed( const QString & groupAddress, const QString & caller );
+
+protected:
+    // consts added to avoid a copy-and-paste of internalDocument
+    void parse() const;
+    void importDesktopFiles();
+    static void convertToXBEL( QDomElement & group );
+    static void convertAttribute( QDomElement elem, const QString & oldName, const QString & newName );
+
+private:
+    KBookmarkNotifier m_notifier;
+    QString m_bookmarksFile;
+    mutable QDomDocument m_doc;
+    mutable QDomDocument m_toolbarDoc;
+    mutable bool m_docIsLoaded;
+    bool m_update;
+    static QPtrList<KBookmarkManager>* s_pSelf;
+    bool m_showNSBookmarks;
+
+private:
+    class KBookmarkManagerPrivate* dptr() const;
+};
+
+/**
+ * The KBookmarkMenu and KBookmarkBar classes gives the user
+ * the ability to either edit bookmarks or add their own.  In the
+ * first case, the app may want to open the bookmark in a special way.
+ * In the second case, the app <em>must</em> supply the name and the
+ * URL for the bookmark.
+ *
+ * This class gives the app this callback-like ability.
+ *
+ * If your app does not give the user the ability to add bookmarks and
+ * you don't mind using the default bookmark editor to edit your
+ * bookmarks, then you don't need to overload this class at all.
+ * Rather, just use something like:
+ *
+ * <CODE>
+ * bookmarks = new KBookmarkMenu(new KBookmarkOwner(), ...)
+ * </CODE>
+ *
+ * If you wish to use your own editor or allow the user to add
+ * bookmarks, you must overload this class.
+ */
+class KIO_EXPORT KBookmarkOwner
+{
+public:
+  /**
+   * This function is called if the user selects a bookmark.  It will
+   * open up the bookmark in a default fashion unless you override it.
+   */
+  virtual void openBookmarkURL(const QString& _url);
+
+  /**
+   * This function is called whenever the user wants to add the
+   * current page to the bookmarks list.  The title will become the
+   * "name" of the bookmark.  You must overload this function if you
+   * wish to give your users the ability to add bookmarks.
+   *
+   * @return the title of the current page.
+   */
+  virtual QString currentTitle() const { return QString::null; }
+
+  /**
+   * This function is called whenever the user wants to add the
+   * current page to the bookmarks list.  The URL will become the URL
+   * of the bookmark.  You must overload this function if you wish to
+   * give your users the ability to add bookmarks.
+   *
+   * @return the URL of the current page.
+   */
+  virtual QString currentURL() const { return QString::null; }
+
+protected:
+  virtual void virtual_hook( int id, void* data );
+};
+
+/**
+ * @since 3.2
+ */
+class KIO_EXPORT KExtendedBookmarkOwner : public QObject, virtual public KBookmarkOwner
+{
+    Q_OBJECT
+public:
+    typedef QValueList<QPair<QString,QString> > QStringPairList;
+public slots:
+    void fillBookmarksList( KExtendedBookmarkOwner::QStringPairList & list ) { emit signalFillBookmarksList( list ); };
+signals:
+    void signalFillBookmarksList( KExtendedBookmarkOwner::QStringPairList & list );
+private:
+    class KExtendedBookmarkOwnerPrivate;
+    KExtendedBookmarkOwnerPrivate *d;
+};
+
+#endif