KDEWebKit

kwebview.h
1 /*
2  * This file is part of the KDE project.
3  *
4  * Copyright (C) 2007 Trolltech ASA
5  * Copyright (C) 2008 Urs Wolfer <uwolfer @ kde.org>
6  * Copyright (C) 2008 Laurent Montel <[email protected]>
7  * Copyright (C) 2008 Michael Howell <[email protected]>
8  * Copyright (C) 2009 Dawit Alemayehu <adawit @ kde.org>
9  *
10  * This library is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU Library General Public
12  * License as published by the Free Software Foundation; either
13  * version 2 of the License, or (at your option) any later version.
14  *
15  * This library is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18  * Library General Public License for more details.
19  *
20  * You should have received a copy of the GNU Library General Public License
21  * along with this library; see the file COPYING.LIB. If not, write to
22  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
23  * Boston, MA 02110-1301, USA.
24  *
25  */
26 #ifndef KWEBVIEW_H
27 #define KWEBVIEW_H
28 
29 #include <kdewebkit_export.h>
30 
31 #include <QWebView>
32 
33 class QUrl;
34 template<class T> class KWebViewPrivate;
35 
36 /**
37  * @short A re-implementation of QWebView that provides integration with KDE
38  * frameworks.
39  *
40  * This is a drop-in replacement for QWebView that provides full KDE frameworks
41  * integration through @ref KWebPage as well as additional signals that
42  * capture middle, shift and ctrl mouse clicks on links and URL pasting
43  * from the selection clipboard.
44  *
45  * The specific functionality provided by this class (over and above what
46  * would be achieved by using KWebPage with a QWebView) is that scrolling
47  * with the mouse wheel while holding down CTRL zooms the page (see
48  * QWebView::setZoomFactor) and several useful signals are emitted when
49  * the user performs certain actions.
50  *
51  * See the signal documentation for more details.
52  *
53  * @author Urs Wolfer <uwolfer @ kde.org>
54  * @author Dawit Alemayehu <adawit @ kde.org>
55  * @since 4.4
56  */
57 class KDEWEBKIT_EXPORT KWebView : public QWebView
58 {
59  Q_OBJECT
60  Q_PROPERTY(bool externalContentAllowed READ isExternalContentAllowed WRITE setAllowExternalContent)
61 public:
62  /**
63  * Constructs a KWebView object with parent @p parent.
64  *
65  * Set @p createCustomPage to false to prevent the creation of a
66  * @ref KWebPage object for KDE frameworks integration. Doing so allows you
67  * to avoid unnecessary object creation and deletion if you are going to use
68  * a subclass of KWebPage.
69  *
70  * @param parent the parent object
71  * @param createCustomPage if @c true, the view's page is set to an
72  * instance of KWebPage
73  */
74  explicit KWebView(QWidget *parent = nullptr, bool createCustomPage = true);
75 
76  /**
77  * Destroys the KWebView.
78  */
79  ~KWebView();
80 
81  /**
82  * Returns true if access to remote content is allowed.
83  *
84  * By default access to remote content is allowed.
85  *
86  * @see setAllowExternalContent()
87  * @see KWebPage::isExternalContentAllowed()
88  */
89  bool isExternalContentAllowed() const;
90 
91  /**
92  * Set @p allow to false if you want to prevent access to remote content.
93  *
94  * If this function is set to false only resources on the local system
95  * can be accessed through this class. By default fetching external content
96  * is allowed.
97  *
98  * @see isExternalContentAllowed()
99  * @see KWebPage::setAllowExternalContent(bool)
100  */
101  void setAllowExternalContent(bool allow);
102 
103 Q_SIGNALS:
104  /**
105  * Emitted when a URL from the selection clipboard is pasted on this view.
106  *
107  * This is triggered when the user clicks on the page with the middle
108  * mouse button when there is something in the global mouse selection
109  * clipboard. This is typically only possible on X11.
110  *
111  * Uri filters are applied to the selection clipboard to generate @p url.
112  *
113  * If the content in the selection clipboard is not a valid url and a
114  * default search engine is configured, @p url will be set to a query
115  * to the default search engine.
116  *
117  * @param url url generated from the selection clipboard content
118  *
119  * @deprecated use selectionClipboardUrlPasted(QUrl, bool) instead
120  * @see QClipboard
121  */
122 #ifndef KDEWEBKIT_NO_DEPRECATED
123  KDEWEBKIT_DEPRECATED void selectionClipboardUrlPasted(const QUrl &url);
124 #endif
125 
126  /**
127  * Emitted when a URL from the selection clipboard is pasted on this view.
128  *
129  * This is triggered when the user clicks on the page with the middle
130  * mouse button when there is something in the global mouse selection
131  * clipboard. This is typically only possible on X11.
132  *
133  * Uri filters are applied to the selection clipboard to generate @p url.
134  *
135  * If the content in the selection clipboard is not a valid URL and a
136  * default search engine is configured, @p searchText will be set to the
137  * content of the clipboard (250 characters maximum) and @p url will be
138  * set to a query to the default search engine.
139  *
140  * @param url the URL generated from the selection clipboard content
141  * @param searchText content of the selection clipboard if it is not a
142  * valid URL
143  *
144  * @see KUriFilter
145  * @see QClipboard
146  * @since 4.6
147  */
148  void selectionClipboardUrlPasted(const QUrl &url, const QString &searchText);
149 
150  /**
151  * Emitted when a link is clicked with the left mouse button while SHIFT is
152  * held down.
153  *
154  * A user of Plasma desktop would typically expect this to result in the
155  * triggering of a "save link as" action.
156  *
157  * @param url the URL of the clicked link
158  */
159  void linkShiftClicked(const QUrl &url);
160 
161  /**
162  * Emitted when a link is clicked with the middle mouse button or clicked
163  * with the left mouse button while CTRL is held down.
164  *
165  * Typically, the user would expect this to result in the URL being opened
166  * in a new tab or window.
167  *
168  * @param url the URL of the clicked link
169  */
170  void linkMiddleOrCtrlClicked(const QUrl &url);
171 
172 protected:
173  /**
174  * @reimp
175  *
176  * Reimplemented for internal reasons, the API is not affected.
177  *
178  * @see QWidget::wheelEvent
179  * @internal
180  */
181  void wheelEvent(QWheelEvent *event) override;
182 
183  /**
184  * @reimp
185  *
186  * Reimplemented for internal reasons, the API is not affected.
187  *
188  * @see QWidget::mousePressEvent
189  * @internal
190  */
191  void mousePressEvent(QMouseEvent *event) override;
192 
193  /**
194  * @reimp
195  *
196  * Reimplemented for internal reasons, the API is not affected.
197  *
198  * @see QWidget::mouseReleaseEvent
199  * @internal
200  */
201  void mouseReleaseEvent(QMouseEvent *event) override;
202 
203 private:
204  friend class KWebViewPrivate<KWebView>;
205  KWebViewPrivate<KWebView> *const d;
206 };
207 
208 #endif // KWEBVIEW_H
A re-implementation of QWebView that provides integration with KDE frameworks.
Definition: kwebview.h:57
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Dec 2 2021 22:54:54 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.