TDE core libraries
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

  1. // -*- c-basic-offset:4; indent-tabs-mode:nil -*-
  2. // vim: set ts=4 sts=4 sw=4 et:
  3. /* This file is part of the KDE libraries
  4. Copyright (C) 2000 David Faure <faure@kde.org>
  5. This library is free software; you can redistribute it and/or
  6. modify it under the terms of the GNU Library General Public
  7. License version 2 as published by the Free Software Foundation.
  8. This library is distributed in the hope that it will be useful,
  9. but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  11. Library General Public License for more details.
  12. You should have received a copy of the GNU Library General Public License
  13. along with this library; see the file COPYING.LIB. If not, write to
  14. the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  15. Boston, MA 02110-1301, USA.
  16. */
  17. #ifndef __kbookmarkmanager_h
  18. #define __kbookmarkmanager_h
  19. #include <tqstring.h>
  20. #include <tqstringlist.h>
  21. #include <tqobject.h>
  22. #include <tqdom.h>
  23. #include <dcopobject.h>
  24. #include "kbookmark.h"
  25. #include "kbookmarknotifier.h"
  26. /**
  27. * This class implements the reading/writing of bookmarks in XML.
  28. * The bookmarks file is read and written using the XBEL standard
  29. * (http://pyxml.sourceforge.net/topics/xbel/)
  30. *
  31. * A sample file looks like this :
  32. * \code
  33. * <xbel>
  34. * <bookmark href="http://developer.kde.org"><title>Developer Web Site</title></bookmark>
  35. * <folder folded="no">
  36. * <title>Title of this folder</title>
  37. * <bookmark icon="kde" href="http://www.kde.org"><title>KDE Web Site</title></bookmark>
  38. * <folder toolbar="yes">
  39. * <title>My own bookmarks</title>
  40. * <bookmark href="http://www.koffice.org"><title>KOffice Web Site</title></bookmark>
  41. * <separator/>
  42. * <bookmark href="http://www.tdevelop.org"><title>KDevelop Web Site</title></bookmark>
  43. * </folder>
  44. * </folder>
  45. * </xbel>
  46. * \endcode
  47. */
  48. class KIO_EXPORT KBookmarkManager : public TQObject, public DCOPObject
  49. {
  50. Q_OBJECT
  51. K_DCOP
  52. protected:
  53. /**
  54. * Creates a bookmark manager with a path to the bookmarks. By
  55. * default, it will use the KDE standard dirs to find and create the
  56. * correct location. If you are using your own app-specific
  57. * bookmarks directory, you must instantiate this class with your
  58. * own path <em>before</em> KBookmarkManager::managerForFile() is ever
  59. * called.
  60. *
  61. * @param bookmarksFile full path to the bookmarks file,
  62. * Use ~/.trinity/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
  63. *
  64. * @param bImportDesktopFiles if true, and if the bookmarksFile
  65. * doesn't already exist, import bookmarks from desktop files
  66. */
  67. KBookmarkManager( const TQString & bookmarksFile, bool bImportDesktopFiles = true );
  68. /**
  69. * @since 3.2
  70. */
  71. KBookmarkManager();
  72. public:
  73. /**
  74. * Destructor
  75. */
  76. ~KBookmarkManager();
  77. /**
  78. * Set the update flag. Defaults to true. TODO - check
  79. * @param update if true then KBookmarkManager will listen to DCOP update requests.
  80. */
  81. void setUpdate( bool update );
  82. /**
  83. * Save the bookmarks to the default konqueror XML file on disk.
  84. * You should use emitChanged() instead of this function, it saves
  85. * and notifies everyone that the file has changed.
  86. * @param toolbarCache iff true save a cache of the toolbar folder, too
  87. * @return true if saving was successful
  88. */
  89. bool save( bool toolbarCache = true ) const;
  90. /**
  91. * Save the bookmarks to the given XML file on disk.
  92. * @param filename full path to the desired bookmarks file location
  93. * @param toolbarCache iff true save a cache of the toolbar folder, too
  94. * @return true if saving was successful
  95. */
  96. bool saveAs( const TQString & filename, bool toolbarCache = true ) const;
  97. /**
  98. * Update access time stamps for a given url.
  99. * @param url the viewed url
  100. * @param emitSignal iff true emit KBookmarkNotifier signal
  101. * @since 3.2
  102. * @return true if any metadata was modified (bookmarks file is not saved automatically)
  103. */
  104. bool updateAccessMetadata( const TQString &url, bool emitSignal = true );
  105. /*
  106. * NB. currently *unimplemented*
  107. *
  108. * Update favicon url for a given url.
  109. * @param url the viewed url
  110. * @param faviconurl the favicion url
  111. * @emitSignal iff true emit KBookmarkNotifier signal
  112. * @since 3.3
  113. */
  114. void updateFavicon( const TQString &url, const TQString &faviconurl, bool emitSignal = true );
  115. /**
  116. * This will return the path that this manager is using to read
  117. * the bookmarks.
  118. * @internal
  119. * @return the path containing the bookmarks
  120. */
  121. TQString path() { return m_bookmarksFile; }
  122. /**
  123. * This will return the root bookmark. It is used to iterate
  124. * through the bookmarks manually. It is mostly used internally.
  125. *
  126. * @return the root (top-level) bookmark
  127. */
  128. KBookmarkGroup root() const;
  129. /**
  130. * This returns the root of the toolbar menu.
  131. * In the XML, this is the group with the attribute TOOLBAR=1
  132. *
  133. * @return the toolbar group
  134. */
  135. KBookmarkGroup toolbar();
  136. /**
  137. * @return the bookmark designated by @p address
  138. * @param address the address belonging to the bookmark you're looking for
  139. * @param tolerate when true tries to find the most tolerable bookmark position
  140. * @see KBookmark::address
  141. */
  142. KBookmark findByAddress( const TQString & address, bool tolerate = false );
  143. /**
  144. * Saves the bookmark file and notifies everyone.
  145. * @param group the parent of all changed bookmarks
  146. */
  147. void emitChanged( KBookmarkGroup & group );
  148. void emitConfigChanged();
  149. /**
  150. * @return true if the NS bookmarks should be dynamically shown
  151. * in the toplevel kactionmenu
  152. * @deprecated
  153. */
  154. bool showNSBookmarks() const;
  155. /**
  156. * Shows an extra menu for NS bookmarks. Set this to false, if you don't
  157. * want this.
  158. */
  159. void setShowNSBookmarks( bool show );
  160. /**
  161. * Set options with which slotEditBookmarks called keditbookmarks
  162. * this can be used to change the appearance of the keditbookmarks
  163. * in order to provide a slightly differing outer shell depending
  164. * on the bookmarks file / app which calls it.
  165. * @param caption the --caption string, for instance "Konsole"
  166. * @param browser iff false display no browser specific
  167. * menu items in keditbookmarks :: --nobrowser
  168. * @since 3.2
  169. */
  170. void setEditorOptions( const TQString& caption, bool browser );
  171. /**
  172. * This static function will return an instance of the
  173. * KBookmarkManager, responsible for the given @p bookmarksFile.
  174. * If you do not instantiate this class either
  175. * natively or in a derived class, then it will return an object
  176. * with the default behaviors. If you wish to use different
  177. * behaviors, you <em>must</em> derive your own class and
  178. * instantiate it before this method is ever called.
  179. *
  180. * @param bookmarksFile full path to the bookmarks file,
  181. * Use ~/.trinity/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
  182. *
  183. * @param bImportDesktopFiles if true, and if the bookmarksFile
  184. * doesn't already exist, import bookmarks from desktop files
  185. * @return a pointer to an instance of the KBookmarkManager.
  186. */
  187. static KBookmarkManager* managerForFile( const TQString& bookmarksFile,
  188. bool bImportDesktopFiles = true );
  189. static KBookmarkManager* createTempManager();
  190. /**
  191. * Returns a pointer to the users main bookmark collection.
  192. * @since 3.2
  193. */
  194. static KBookmarkManager* userBookmarksManager();
  195. /**
  196. * Returns the path to the user's main bookmark collection file.
  197. * @since 3.5.5
  198. */
  199. static TQString userBookmarksFile();
  200. /**
  201. * @internal
  202. */
  203. const TQDomDocument & internalDocument() const;
  204. /**
  205. * Access to bookmark notifier, for emitting signals.
  206. * We need this object to exist in one instance only, so we could
  207. * connectDCOP to it by name.
  208. */
  209. KBookmarkNotifier& notifier() { return m_notifier; }
  210. /**
  211. * @since 3.2
  212. */
  213. KBookmarkGroup addBookmarkDialog( const TQString & _url, const TQString & _title,
  214. const TQString & _parentBookmarkAddress = TQString::null );
  215. public slots:
  216. void slotEditBookmarks();
  217. void slotEditBookmarksAtAddress( const TQString& address );
  218. public:
  219. k_dcop:
  220. /**
  221. * Reparse the whole bookmarks file and notify about the change
  222. * (Called by the bookmark editor)
  223. */
  224. ASYNC notifyCompleteChange( TQString caller );
  225. /**
  226. * Emit the changed signal for the group whose address is given
  227. * @see KBookmark::address()
  228. * Called by the instance of konqueror that saved the file after
  229. * a small change (new bookmark or new folder).
  230. */
  231. ASYNC notifyChanged( TQString groupAddress );
  232. ASYNC notifyConfigChanged();
  233. signals:
  234. /**
  235. * Signals that the group (or any of its children) with the address
  236. * @p groupAddress (e.g. "/4/5")
  237. * has been modified by the caller @p caller.
  238. */
  239. void changed( const TQString & groupAddress, const TQString & caller );
  240. protected:
  241. // consts added to avoid a copy-and-paste of internalDocument
  242. void parse() const;
  243. void importDesktopFiles();
  244. static void convertToXBEL( TQDomElement & group );
  245. static void convertAttribute( TQDomElement elem, const TQString & oldName, const TQString & newName );
  246. private:
  247. KBookmarkNotifier m_notifier;
  248. TQString m_bookmarksFile;
  249. mutable TQDomDocument m_doc;
  250. mutable TQDomDocument m_toolbarDoc;
  251. mutable bool m_docIsLoaded;
  252. bool m_update;
  253. static TQPtrList<KBookmarkManager>* s_pSelf;
  254. bool m_showNSBookmarks;
  255. private:
  256. class KBookmarkManagerPrivate* dptr() const;
  257. };
  258. /**
  259. * The KBookmarkMenu and KBookmarkBar classes gives the user
  260. * the ability to either edit bookmarks or add their own. In the
  261. * first case, the app may want to open the bookmark in a special way.
  262. * In the second case, the app <em>must</em> supply the name and the
  263. * URL for the bookmark.
  264. *
  265. * This class gives the app this callback-like ability.
  266. *
  267. * If your app does not give the user the ability to add bookmarks and
  268. * you don't mind using the default bookmark editor to edit your
  269. * bookmarks, then you don't need to overload this class at all.
  270. * Rather, just use something like:
  271. *
  272. * <CODE>
  273. * bookmarks = new KBookmarkMenu(new KBookmarkOwner(), ...)
  274. * </CODE>
  275. *
  276. * If you wish to use your own editor or allow the user to add
  277. * bookmarks, you must overload this class.
  278. */
  279. class KIO_EXPORT KBookmarkOwner
  280. {
  281. public:
  282. /**
  283. * This function is called if the user selects a bookmark. It will
  284. * open up the bookmark in a default fashion unless you override it.
  285. */
  286. virtual void openBookmarkURL(const TQString& _url);
  287. /**
  288. * This function is called whenever the user wants to add the
  289. * current page to the bookmarks list. The title will become the
  290. * "name" of the bookmark. You must overload this function if you
  291. * wish to give your users the ability to add bookmarks.
  292. *
  293. * @return the title of the current page.
  294. */
  295. virtual TQString currentTitle() const { return TQString::null; }
  296. /**
  297. * This function is called whenever the user wants to add the
  298. * current page to the bookmarks list. The URL will become the URL
  299. * of the bookmark. You must overload this function if you wish to
  300. * give your users the ability to add bookmarks.
  301. *
  302. * @return the URL of the current page.
  303. */
  304. virtual TQString currentURL() const { return TQString::null; }
  305. protected:
  306. virtual void virtual_hook( int id, void* data );
  307. };
  308. /**
  309. * @since 3.2
  310. */
  311. class KIO_EXPORT KExtendedBookmarkOwner : public TQObject, virtual public KBookmarkOwner
  312. {
  313. Q_OBJECT
  314. public:
  315. typedef TQValueList<QPair<TQString,TQString> > QStringPairList;
  316. public slots:
  317. void fillBookmarksList( KExtendedBookmarkOwner::QStringPairList & list ) { emit signalFillBookmarksList( list ); };
  318. signals:
  319. void signalFillBookmarksList( KExtendedBookmarkOwner::QStringPairList & list );
  320. private:
  321. class KExtendedBookmarkOwnerPrivate;
  322. KExtendedBookmarkOwnerPrivate *d;
  323. };
  324. #endif