File indexing completed on 2024-05-12 05:00:04

 /* This file is part of the KDE project
    SPDX-FileCopyrightText: 2023 Stefano Crocco <stefano.crocco@alice.it>
 
    SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KONQINTERFACES_BROWSER_H
 #define KONQINTERFACES_BROWSER_H
 
 #include "libkonq_export.h"
 
 #include <QObject>
 
 namespace KParts {
     class ReadOnlyPart;
 };
 
 namespace KonqInterfaces {
 
 class CookieJar;
 
 /**
  * @brief Abstract class representing the Konqueror browser
  */
 class LIBKONQ_EXPORT Browser : public QObject
 {
     Q_OBJECT
 
 public:
     /**
      * Default Constructor
      *
      * @param parent the parent object
      */
     Browser(QObject* parent = nullptr);
     virtual ~Browser(); ///< Destructor
 
     /**
      * @brief Sets the object to use for cookies management
      *
      * @note this object *wont't* take ownership of @p jar.
      *
      * @param jar the object to use for cookie management
      */
     virtual void setCookieJar(CookieJar *jar) = 0;
 
     /**
      * @brief The object to use for cookie management
      * @return the object to use for cookie management
      */
     virtual CookieJar* cookieJar() const = 0;
 
     /**
      * @brief The standard user agent used by Konqueror
      * @return The standard user agent used by Konqueror
      */
     virtual QString konqUserAgent() const = 0;
 
     /**
      * @brief The default user agent
      * @return The default user agent
      */
     virtual QString defaultUserAgent() const = 0;
 
     /**
      * @brief The user agent currently in use
      *
      * This can be either defaultUserAgent() or a temporary user agent set with setTemporaryUserAgent()
      * @return The user agent currently in use
      * @see setTemporaryUserAgent()
      */
     virtual QString userAgent() const = 0;
 
     /**
      * @brief Sets a temporary user agent to be used instead of the default one
      *
      * The temporary user agent remains in use until the application is closed or this is called again.
      *
      * Implementations should emit the userAgentChanged() signal, unless the new user
      * agent is effectively equal to to old. If switching from the default user agent to a
      * temporary user agent but the two are equal (or vice versa) the signal shouldn't be emitted
      * @param newUA the new user agent string.
      */
     virtual void setTemporaryUserAgent(const QString &newUA) = 0;
 
     /**
      * @brief Stops using a temporary user agent and returns to the default one
      */
     virtual void clearTemporaryUserAgent() = 0;
 
     /**
      * @brief Casts the given object or one of its children to a Browser
      *
      * This is similar to
      * @code
      * obj->findChild<Browser*>();
      * @endcode
      * except that if @p obj derives from Browser, it will be returned, regardless of whether any
      * of its children also derive from it.
      * @param obj the object to cast to a Browser
      * @return @p obj or one of its children as a Browser* or `nullptr` if neither @p obj nor its children derive from Browser
      */
     static Browser* browser(QObject* obj);
 
     /**
      * @brief Whether a part has permission to navigate to the given URL
      * @param part the part
      * @param url the URL the part wants to navigate to
      * @return `true` if @p part can navigate to @p url and `false` otherwise.
      */
     virtual bool canNavigateTo(KParts::ReadOnlyPart *part, const QUrl &url) const = 0;
 
 signals:
     void configurationChanged(); ///< Signal emitted after the configuration has changed
 
     /**
      * @brief Signal emitted when the user agent changes
      *
      * This signal can be emitted in several situations:
      * - the default user agent is in use and the user changes it
      * - the user switched from the default user agent to a temporary one (or vice versa) and the two are different
      * - the user switched from a temporary user agent to a different temporary user agent
      *
      * @param currentUA the new current user agent
      * @see setTemporaryUserAgent()
      */
     void userAgentChanged(const QString &currentUA);
 };
 
 }
 
 #endif // KONQINTERFACES_BROWSER_H