kbookmark.h

/* 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 __kbookmark_h
#define __kbookmark_h
 
#include <tqstring.h>
#include <tqvaluelist.h>
#include <tqdom.h>
#include <kurl.h>
 
class KBookmarkManager;
class KBookmarkGroup;
 
class TDEIO_EXPORT KBookmark
{
    friend class KBookmarkGroup;
public:
    enum MetaDataOverwriteMode {
        OverwriteMetaData, DontOverwriteMetaData
    };
 
    KBookmark( ) {}
    KBookmark( TQDomElement elem ) : element(elem) {}
 
    static KBookmark standaloneBookmark( const TQString & text, const KURL & url, const TQString & icon = TQString::null );

    bool isGroup() const;

    bool isSeparator() const;

    bool isNull() const {return element.isNull();}

    bool hasParent() const;

    TQString text() const;
    TQString fullText() const;
    KURL url() const;
    TQString icon() const;

    KBookmarkGroup parentGroup() const;

    KBookmarkGroup toGroup() const;

    TQString address() 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; }

    TQDomElement internalElement() const { return element; }

    void updateAccessMetadata();
 
    // Utility functions (internal)

    static TQString parentAddress( const TQString & address )
    { return address.left( address.findRev('/') ); }

    static uint positionInParent( const TQString & address )
    { return address.mid( address.findRev('/') + 1 ).toInt(); }

    static TQString previousAddress( const TQString & address )
    {
        uint pp = positionInParent(address);
        return pp>0 ? parentAddress(address) + '/' + TQString::number(pp-1) : TQString::null;
    }

    static TQString nextAddress( const TQString & address )
    { return parentAddress(address) + '/' + TQString::number(positionInParent(address)+1); }

     static TQString commonParent(TQString A, TQString B);

    TQString metaDataItem( const TQString &key ) const;

    void setMetaDataItem( const TQString &key, const TQString &value, MetaDataOverwriteMode mode = OverwriteMetaData );
 
protected:
    TQDomElement 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 TQDomElement.
 
private:
    bool hasMetaData() const;
    static TQString left(const TQString & str, uint len);
};

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

    KBookmarkGroup( TQDomElement elem );

    TQString groupAddress() const;

    bool isOpen() const;

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

    KBookmarkGroup createNewFolder( KBookmarkManager* mgr, const TQString & text = TQString::null, bool emitSignal = true );
    KBookmark createNewSeparator();

    KBookmark addBookmark( KBookmarkManager* mgr, const KBookmark &bm, bool emitSignal = true );

    KBookmark addBookmark( KBookmarkManager* mgr, const TQString & text, const KURL & url, const TQString & icon = TQString::null, bool emitSignal = true );

    bool moveItem( const KBookmark & item, const KBookmark & after );

    void deleteBookmark( KBookmark bk );

    bool isToolbarGroup() const;
    TQDomElement findToolbar() const;

    TQValueList<KURL> groupUrlList() const;
 
protected:
    TQDomElement nextKnownTag( TQDomElement start, bool goNext ) const;
 
private:
    mutable TQString m_address;
    // 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 TQDomElement.
};

class TDEIO_EXPORT KBookmarkGroupTraverser {
protected:
    virtual ~KBookmarkGroupTraverser() { ; }
    void traverse(const KBookmarkGroup &);
    virtual void visit(const KBookmark &) { ; }
    virtual void visitEnter(const KBookmarkGroup &) { ; }
    virtual void visitLeave(const KBookmarkGroup &) { ; }
private:
    class KBookmarkGroupTraverserPrivate *d;
};
 
#endif