KIO

faviconrequestjob.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2016 David Faure <[email protected]>
4  SPDX-FileCopyrightText: 2001 Malte Starostik <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KIO_FAVICONREQUESTJOB_H
10 #define KIO_FAVICONREQUESTJOB_H
11 
12 #include "kiogui_export.h"
13 #include <kio/job_base.h> // for LoadType
14 
15 #include <memory>
16 
17 class QUrl;
18 
19 namespace KIO
20 {
21 class FavIconRequestJobPrivate;
22 /**
23  * @class FavIconRequestJob faviconrequestjob.h <KIO/FavIconRequestJob>
24  *
25  * FavIconRequestJob handles the retrieval of a favicon (either from the local cache or from the internet)
26  *
27  * For instance, the icon for http://www.google.com exists at http://www.google.com/favicon.ico
28  * This job will (the first time) download the favicon, and make it available as a local PNG
29  * for fast lookups afterwards.
30  *
31  * Usage:
32  * Create a FavIconRequestJob, connect to result(KJob *), and from there use iconFile().
33  *
34  * @code
35  * // Let's say we want to show the icon for QUrl m_url
36  * KIO::FavIconRequestJob *job = new KIO::FavIconRequestJob(m_url);
37  * connect(job, &KIO::FavIconRequestJob::result, this, [job, this](KJob *){
38  * if (!job->error()) {
39  * // show the icon using QIcon(job->iconFile())
40  * }
41  * });
42  * @endcode
43  *
44  * For a given HTTP URL, you can find out if a favicon is available by calling KIO::favIconForUrl() in KIOCore.
45  * It is however not necessary to check this first, FavIconRequestJob will do this
46  * first and emit result right away if a cached icon is available and not too old.
47  *
48  * In Web Browsers, additional information exists: the HTML for a given page can
49  * specify something like
50  * &lt;link rel="shortcut icon" href="another_favicon.ico" /&gt;
51  * To handle this, call job->setIconUrl(iconUrl).
52  * (KParts-based web engines use the signal BrowserExtension::setIconUrl to call back
53  * into the web browser application, which should then call this).
54  * The signal urlIconChanged will be emitted once the icon has been downloaded.
55  *
56  * The on-disk cache is shared between processes.
57  *
58  * @since 5.19
59  */
60 class KIOGUI_EXPORT FavIconRequestJob : public KCompositeJob
61 {
62  Q_OBJECT
63 public:
64  /**
65  * @brief FavIconRequestJob constructor
66  * @param hostUrl The web page URL. We only use the scheme and host.
67  * @param reload set this to reload to skip the cache and force a refresh of the favicon.
68  * @param parent parent object
69  */
70  explicit FavIconRequestJob(const QUrl &hostUrl, KIO::LoadType reload = KIO::NoReload, QObject *parent = nullptr);
71 
72  /**
73  * Destructor. You do not need to delete the job, it will delete automatically,
74  * unless you call setAutoDelete(false).
75  */
76  ~FavIconRequestJob() override;
77 
78  /**
79  * @brief setIconUrl allows to set, for a specific URL, a different icon URL
80  * than the default one for the host (http://host/favicon.ico)
81  *
82  * This information is stored in the on-disk cache, so that
83  * other FavIconRequestJobs for this url and KIO::favIconForUrl
84  * will return the icon specified here.
85  *
86  * @param iconUrl the URL to the icon, usually parsed from the HTML
87  */
88  void setIconUrl(const QUrl &iconUrl);
89 
90  /**
91  * Returns the full local path to the icon from the cache.
92  * Only call this in the slot connected to the result(KJob*) signal.
93  * @return the path to the icon file
94  */
95  QString iconFile() const;
96 
97  /**
98  * Returns the URL passed to the constructor
99  * @since 5.20
100  */
101  QUrl hostUrl() const;
102 
103  /**
104  * @internal
105  * Do not call start(), KIO jobs are autostarted
106  */
107  void start() override
108  {
109  }
110 
111 private Q_SLOTS:
112  void doStart(); // not called start() so that exec() doesn't call it too
113  void slotResult(KJob *job) override;
114 
115 private:
116  std::unique_ptr<FavIconRequestJobPrivate> const d;
117 };
118 
119 }
120 #endif
A namespace for KIO globals.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Feb 5 2023 04:00:50 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.