File indexing completed on 2024-10-06 09:34:14

 /*
     This file is part of the KDE libraries
     SPDX-FileCopyrightText: 2000, 2006 David Faure <faure@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-only
 */
 #ifndef KBOOKMARK_OWNER_H
 #define KBOOKMARK_OWNER_H
 
 #include "kbookmark.h"
 
 #include <QSharedDataPointer>
 #include <QString>
 
 class QWidget;
 
 class KBookmarkGroup;
 class KBookmarkDialog;
 
 /**
  * @class KBookmarkOwner kbookmarkowner.h KBookmarkOwner
  *
  * 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 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(manager, nullptr, menu, actionCollection);
  * @endcode
  *
  * If you wish to use your own editor or allow the user to add
  * bookmarks, you must overload this class.
  */
 class KBOOKMARKS_EXPORT KBookmarkOwner
 {
 public:
     // TODO KF6: add non-inline constructor, de-inline destructor. Otherwise the d pointer cannot be used.
     virtual ~KBookmarkOwner()
     {
     }
 
     /**
      * 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.
      * The default returns an empty string.
      *
      * @return the title of the current page.
      */
     virtual QString currentTitle() const
     {
         return QString();
     }
 
     /**
      * 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.
      * The default returns an empty string.
      *
      * @return the URL of the current page.
      * Since 5.0 this method returns a QUrl. While porting it, remember to implement currentIcon too.
      */
     virtual QUrl currentUrl() const
     {
         return QUrl();
     }
 
     /**
      * This function is called whenever the user wants to add the
      * current page to the bookmarks list.  The icon will become the icon
      * of the bookmark.  You must overload this function if you wish to
      * give your users the ability to add bookmarks.
      * The default returns an empty string.
      *
      * A very common implementation for this method is
      * return KIO::iconNameForUrl(currentUrl());
      *
      * @return the icon name of the current page.
      * @since 5.0
      */
     virtual QString currentIcon() const
     {
         return QString();
     }
 
     /**
      * This function returns whether the owner supports tabs.
      * The default returns @c false.
      */
     virtual bool supportsTabs() const
     {
         return false;
     }
 
     class FutureBookmarkPrivate;
     /**
      * Represents the data for a bookmark that will be added.
      * @since 5.0
      */
     class KBOOKMARKS_EXPORT FutureBookmark
     {
     public:
         FutureBookmark(const QString &title, const QUrl &url, const QString &icon);
         ~FutureBookmark();
         FutureBookmark(const FutureBookmark &other);
         FutureBookmark &operator=(const FutureBookmark &other);
 
         QString title() const;
         QUrl url() const;
         QString icon() const;
 
     private:
         QSharedDataPointer<FutureBookmarkPrivate> d;
     };
 
     /**
      * Returns a list of bookmark data for the open tabs.
      * The default returns an empty list.
      */
     virtual QList<FutureBookmark> currentBookmarkList() const
     {
         return QList<FutureBookmark>();
     }
 
     enum BookmarkOption { ShowAddBookmark, ShowEditBookmark };
 
     /** Returns true if \p action should be shown in the menu
      *  The default is to show both a add and editBookmark Entry
      *  //TODO ContextMenuAction? to disable the contextMenu?
      *         Delete and Properties to disable those in the
      *         context menu?
      */
     virtual bool enableOption(BookmarkOption option) const;
 
     /**
      * Called if a bookmark is selected. You need to override this.
      */
     virtual void openBookmark(const KBookmark &bm, Qt::MouseButtons mb, Qt::KeyboardModifiers km) = 0;
 
     /**
      * Called if the user wants to open every bookmark in this folder in a new tab.
      * The default implementation does nothing.
      * This is only called if supportsTabs() returns true
      */
     virtual void openFolderinTabs(const KBookmarkGroup &bm);
 
     virtual KBookmarkDialog *bookmarkDialog(KBookmarkManager *mgr, QWidget *parent);
 
     /**
      * Called when a bookmark should be opened in a new tab.
      * The default implementation calls openBookmark.
      * @since 5.0
      */
     virtual void openInNewTab(const KBookmark &bm);
 
     /**
      * Called when a bookmark should be opened in a new window.
      * The default implementation calls openBookmark.
      * @since 5.0
      */
     virtual void openInNewWindow(const KBookmark &bm);
 
 private:
     class KBookmarkOwnerPrivate;
     KBookmarkOwnerPrivate *d;
 };
 
 #endif