You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
368 lines
12 KiB
368 lines
12 KiB
// -*- 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
|