kbookmark.h

Go to the documentation of this file.

// -*- 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-2005 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 __kbookmark_h
#define __kbookmark_h

#include <kio/kio_export.h>

#include <QtCore/QString>
#include <QtCore/QList>
#include <QtCore/QMetaType>
#include <QtXml/QDomElement>
#include <kurl.h>

class KBookmarkManager;
class KBookmarkGroup;

class KIO_EXPORT KBookmark
{
    friend class KBookmarkGroup;
public:
    enum MetaDataOverwriteMode {
        OverwriteMetaData, DontOverwriteMetaData
    };

    class KIO_EXPORT List : public QList<KBookmark>
    {
    public:
        List();

        void populateMimeData( QMimeData* mimeData ) const;

        static bool canDecode( const QMimeData *mimeData );

        static QStringList mimeDataTypes();

#ifndef KDE_NO_DEPRECATED
        static KDE_DEPRECATED KBookmark::List fromMimeData( const QMimeData *mimeData );
#endif

        static KBookmark::List fromMimeData( const QMimeData *mimeData, QDomDocument& parentDocument );
    };


    KBookmark( );

    explicit KBookmark( const QDomElement &elem );

    static KBookmark standaloneBookmark( const QString & text, const KUrl & url, const QString & icon = QString() );

    bool isGroup() const;

    bool isSeparator() const;

    bool isNull() const;

    bool hasParent() const;

    QString text() const;
    QString fullText() const;
    void setFullText(const QString &fullText);
    KUrl url() const;
    void setUrl(const KUrl &url);

    QString icon() const;

    void setIcon(const QString &icon);

    QString description() const;

    void setDescription(const QString &description);

    QString mimeType() const;

    void setMimeType(const QString &mimeType);

    bool showInToolbar() const;

    void setShowInToolbar(bool show);


    KBookmarkGroup parentGroup() const;

    KBookmarkGroup toGroup() const;

    QString address() const;

    int positionInParent() const;

    // Hard to decide. Good design would imply that each bookmark
    // knows about its manager, so that there can be several managers.
    // But if we say there is only one manager (i.e. set of bookmarks)
    // per application, then KBookmarkManager::self() is much easier.
    //KBookmarkManager * manager() const { return m_manager; }

    QDomElement internalElement() const;

    void updateAccessMetadata();

    // Utility functions (internal)

    static QString parentAddress( const QString & address );

    static uint positionInParent( const QString & address );

    static QString previousAddress( const QString & address );

    static QString nextAddress( const QString & address );

    static QString commonParent( const QString &A, const QString &B );

    QDomNode metaData(const QString &owner, bool create) const;

    QString metaDataItem( const QString &key ) const;

    void setMetaDataItem( const QString &key, const QString &value, MetaDataOverwriteMode mode = OverwriteMetaData );

    void populateMimeData( QMimeData* mimeData ) const;

    bool operator==(const KBookmark& rhs) const;

protected:
    QDomElement element;
    // Note: you can't add new member variables here.
    // The KBookmarks are created on the fly, as wrappers
    // around internal QDomElements. Any additional information
    // has to be implemented as an attribute of the QDomElement.

};

#ifdef MAKE_KIO_LIB
KDE_DUMMY_QHASH_FUNCTION(KBookmark)
#endif

class KIO_EXPORT KBookmarkGroup : public KBookmark
{
public:
    KBookmarkGroup();

    KBookmarkGroup( const QDomElement &elem );

    bool isOpen() const;

    KBookmark first() const;
    KBookmark previous( const KBookmark & current ) const;
    KBookmark next( const KBookmark & current ) const;

    int indexOf(const KBookmark& child) const;

    KBookmarkGroup createNewFolder( const QString & text );
    KBookmark createNewSeparator();

    KBookmark addBookmark( const KBookmark &bm );

    KBookmark addBookmark( const QString & text, const KUrl & url, const QString & icon = QString() );

    bool moveBookmark( const KBookmark & bookmark, const KBookmark & after);

#ifndef KDE_NO_DEPRECATED
    KDE_DEPRECATED bool moveItem( const KBookmark & item, const KBookmark & after );
#endif

    void deleteBookmark( const KBookmark &bk );

    bool isToolbarGroup() const;
    QDomElement findToolbar() const;

    QList<KUrl> groupUrlList() const;

protected:
    QDomElement nextKnownTag( const QDomElement &start, bool goNext ) const;

private:

    // Note: you can't add other member variables here, except for caching info.
    // The KBookmarks are created on the fly, as wrappers
    // around internal QDomElements. Any additional information
    // has to be implemented as an attribute of the QDomElement.
};

class KIO_EXPORT KBookmarkGroupTraverser {
protected:
    virtual ~KBookmarkGroupTraverser();
    void traverse(const KBookmarkGroup &);
    virtual void visit(const KBookmark &);
    virtual void visitEnter(const KBookmarkGroup &);
    virtual void visitLeave(const KBookmarkGroup &);
};

#define KIO_KBOOKMARK_METATYPE_DEFINED 1
Q_DECLARE_METATYPE( KBookmark )

#endif