kio Library API Documentation

kbookmark.h

00001 // -*- c-basic-offset: 4; indent-tabs-mode:nil -*-
00002 // vim: set ts=4 sts=4 sw=4 et:
00003 /* This file is part of the KDE libraries
00004    Copyright (C) 2000 David Faure <faure@kde.org>
00005 
00006    This library is free software; you can redistribute it and/or
00007    modify it under the terms of the GNU Library General Public
00008    License version 2 as published by the Free Software Foundation.
00009 
00010    This library is distributed in the hope that it will be useful,
00011    but WITHOUT ANY WARRANTY; without even the implied warranty of
00012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013    Library General Public License for more details.
00014 
00015    You should have received a copy of the GNU Library General Public License
00016    along with this library; see the file COPYING.LIB.  If not, write to
00017    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00018    Boston, MA 02111-1307, USA.
00019 */
00020 #ifndef __kbookmark_h
00021 #define __kbookmark_h
00022 
00023 #include <qstring.h>
00024 #include <qvaluelist.h>
00025 #include <qdom.h>
00026 #include <kurl.h>
00027 
00028 class KBookmarkManager;
00029 class KBookmarkGroup;
00030 
00031 class KIO_EXPORT KBookmark
00032 {
00033     friend class KBookmarkGroup;
00034 public:
00035     enum MetaDataOverwriteMode {
00036         OverwriteMetaData, DontOverwriteMetaData
00037     };
00038 
00039     KBookmark( ) {}
00040     KBookmark( QDomElement elem ) : element(elem) {}
00041 
00042     static KBookmark standaloneBookmark( const QString & text, const KURL & url, const QString & icon = QString::null );
00043 
00047     bool isGroup() const;
00048 
00052     bool isSeparator() const;
00053 
00059     bool isNull() const {return element.isNull();}
00060 
00067     bool hasParent() const;
00068 
00074     QString text() const;
00079     QString fullText() const;
00083     KURL url() const;
00088     QString icon() const;
00089 
00093     KBookmarkGroup parentGroup() const;
00094 
00099     KBookmarkGroup toGroup() const;
00100 
00107     QString address() const;
00108 
00109     // Hard to decide. Good design would imply that each bookmark
00110     // knows about its manager, so that there can be several managers.
00111     // But if we say there is only one manager (i.e. set of bookmarks)
00112     // per application, then KBookmarkManager::self() is much easier.
00113     //KBookmarkManager * manager() const { return m_manager; }
00114 
00118     QDomElement internalElement() const { return element; }
00119 
00125     void updateAccessMetadata();
00126 
00127     // Utility functions (internal)
00128 
00132     static QString parentAddress( const QString & address )
00133     { return address.left( address.findRev('/') ); }
00134 
00138     static uint positionInParent( const QString & address )
00139     { return address.mid( address.findRev('/') + 1 ).toInt(); }
00140 
00145     static QString previousAddress( const QString & address )
00146     {
00147         uint pp = positionInParent(address);
00148         return pp>0 ? parentAddress(address) + '/' + QString::number(pp-1) : QString::null;
00149     }
00150 
00155     static QString nextAddress( const QString & address )
00156     { return parentAddress(address) + '/' + QString::number(positionInParent(address)+1); }
00157 
00165     QString metaDataItem( const QString &key ) const;
00166 
00175     void setMetaDataItem( const QString &key, const QString &value, MetaDataOverwriteMode mode = OverwriteMetaData );
00176 
00177 protected:
00178     QDomElement element;
00179     // Note: you can't add new member variables here.
00180     // The KBookmarks are created on the fly, as wrappers
00181     // around internal QDomElements. Any additional information
00182     // has to be implemented as an attribute of the QDomElement.
00183 
00184 private:
00185     bool hasMetaData() const;
00186 };
00187 
00191 class KIO_EXPORT KBookmarkGroup : public KBookmark
00192 {
00193 public:
00200     KBookmarkGroup();
00201 
00205     KBookmarkGroup( QDomElement elem );
00206 
00211     QString groupAddress() const;
00212 
00216     bool isOpen() const;
00217 
00221     KBookmark first() const;
00226     KBookmark previous( const KBookmark & current ) const;
00231     KBookmark next( const KBookmark & current ) const;
00232 
00239     KBookmarkGroup createNewFolder( KBookmarkManager* mgr, const QString & text = QString::null, bool emitSignal = true );
00243     KBookmark createNewSeparator();
00244 
00254     KBookmark addBookmark( KBookmarkManager* mgr, const KBookmark &bm, bool emitSignal = true );
00255 
00267     KBookmark addBookmark( KBookmarkManager* mgr, const QString & text, const KURL & url, const QString & icon = QString::null, bool emitSignal = true );
00268 
00273     bool moveItem( const KBookmark & item, const KBookmark & after );
00274 
00278     void deleteBookmark( KBookmark bk );
00279 
00283     bool isToolbarGroup() const;
00287     QDomElement findToolbar() const;
00288 
00293     QValueList<KURL> groupUrlList() const;
00294 
00295 protected:
00296     QDomElement nextKnownTag( QDomElement start, bool goNext ) const;
00297 
00298 private:
00299     mutable QString m_address;
00300     // Note: you can't add other member variables here, except for caching info.
00301     // The KBookmarks are created on the fly, as wrappers
00302     // around internal QDomElements. Any additional information
00303     // has to be implemented as an attribute of the QDomElement.
00304 };
00305 
00309 class KIO_EXPORT KBookmarkGroupTraverser {
00310 protected:
00311     virtual ~KBookmarkGroupTraverser() { ; }
00312     void traverse(const KBookmarkGroup &);
00313     virtual void visit(const KBookmark &) { ; }
00314     virtual void visitEnter(const KBookmarkGroup &) { ; }
00315     virtual void visitLeave(const KBookmarkGroup &) { ; }
00316 private:
00317     class KBookmarkGroupTraverserPrivate *d;
00318 };
00319 
00320 #endif
KDE Logo
This file is part of the documentation for kio Library Version 3.4.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Feb 8 08:02:21 2006 by doxygen 1.4.4 written by Dimitri van Heesch, © 1997-2003