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 <montel@kde.org>
7 * Copyright (C) 2008 Michael Howell <mhowell123@gmail.com>
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 <QtWebKit/QWebView>
32
33class KUrl;
34template<class T> class KWebViewPrivate;
35
36/**
37 * @short A re-implementation of QWebView that provides KDE integration.
38 *
39 * This is a drop-in replacement for QWebView that provides full KDE
40 * integration through @ref KWebPage as well as additional signals that
41 * capture middle, shift and ctrl mouse clicks on links and URL pasting
42 * from the selection clipboard.
43 *
44 * The specific functionality provided by this class (over and above what
45 * would be acheived by using KWebPage with a QWebView) is that scrolling
46 * with the mouse wheel while holding down CTRL zooms the page (see
47 * QWebView::setZoomFactor) and several useful signals are emitted when
48 * the user performs certain actions.
49 *
50 * See the signal documentation for more details.
51 *
52 * @author Urs Wolfer <uwolfer @ kde.org>
53 * @author Dawit Alemayehu <adawit @ kde.org>
54 * @since 4.4
55 */
56class KDEWEBKIT_EXPORT KWebView : public QWebView
57{
58 Q_OBJECT
59 Q_PROPERTY(bool externalContentAllowed READ isExternalContentAllowed WRITE setAllowExternalContent)
60public:
61 /**
62 * Constructs a KWebView object with parent @p parent.
63 *
64 * Set @p createCustomPage to false to prevent the creation of a
65 * @ref KWebPage object for KDE integration. Doing so allows you to
66 * avoid unnecessary object creation and deletion if you are going to
67 * use a subclass of KWebPage.
68 *
69 * @param parent the parent object
70 * @param createCustomPage if @c true, the view's page is set to an
71 * instance of KWebPage
72 */
73 explicit KWebView(QWidget *parent = 0, bool createCustomPage = true);
74
75 /**
76 * Destroys the KWebView.
77 */
78 ~KWebView();
79
80 /**
81 * Returns true if access to remote content is allowed.
82 *
83 * By default access to remote content is allowed.
84 *
85 * @see setAllowExternalContent()
86 * @see KWebPage::isExternalContentAllowed()
87 */
88 bool isExternalContentAllowed() const;
89
90 /**
91 * Set @p allow to false if you want to prevent access to remote content.
92 *
93 * If this function is set to false only resources on the local system
94 * can be accessed through this class. By default fetching external content
95 * is allowed.
96 *
97 * @see isExternalContentAllowed()
98 * @see KWebPage::setAllowExternalContent(bool)
99 */
100 void setAllowExternalContent(bool allow);
101
102Q_SIGNALS:
103 /**
104 * Emitted when a URL from the selection clipboard is pasted on this view.
105 *
106 * This is triggered when the user clicks on the page with the middle
107 * mouse button when there is something in the global mouse selection
108 * clipboard. This is typically only possible on X11.
109 *
110 * Uri filters are applied to the selection clipboard to generate @p url.
111 *
112 * If the content in the selection clipboard is not a valid url and a
113 * default search engine is configured, @p url will be set to a query
114 * to the default search engine.
115 *
116 * @param url url generated from the selection clipboard content
117 *
118 * @deprecated use selectionClipboardUrlPasted(KUrl, bool) instead
119 * @see QClipboard
120 */
121#ifndef KDE_NO_DEPRECATED
122 KDE_DEPRECATED void selectionClipboardUrlPasted(const KUrl &url);
123#endif
124
125 /**
126 * Emitted when a URL from the selection clipboard is pasted on this view.
127 *
128 * This is triggered when the user clicks on the page with the middle
129 * mouse button when there is something in the global mouse selection
130 * clipboard. This is typically only possible on X11.
131 *
132 * Uri filters are applied to the selection clipboard to generate @p url.
133 *
134 * If the content in the selection clipboard is not a valid URL and a
135 * default search engine is configured, @p searchText will be set to the
136 * content of the clipboard (250 characters maximum) and @p url will be
137 * set to a query to the default search engine.
138 *
139 * @param url the URL generated from the selection clipboard content
140 * @param searchText content of the selection clipboard if it is not a
141 * valid URL
142 *
143 * @see KUriFilter
144 * @see QClipboard
145 * @since 4.6
146 */
147 void selectionClipboardUrlPasted(const KUrl &url, const QString& searchText);
148
149 /**
150 * Emitted when a link is clicked with the left mouse button while SHIFT is
151 * held down.
152 *
153 * A KDE user would typically expect this to result in the triggering of a
154 * "save link as" action.
155 *
156 * @param url the URL of the clicked link
157 */
158 void linkShiftClicked(const KUrl &url);
159
160 /**
161 * Emitted when a link is clicked with the middle mouse button or clicked
162 * with the left mouse button while CTRL is held down.
163 *
164 * Typically, the user would expect this to result in the URL being opened
165 * in a new tab or window.
166 *
167 * @param url the URL of the clicked link
168 */
169 void linkMiddleOrCtrlClicked(const KUrl &url);
170
171protected:
172 /**
173 * @reimp
174 *
175 * Reimplemented for internal reasons, the API is not affected.
176 *
177 * @see QWidget::wheelEvent
178 * @internal
179 */
180 void wheelEvent(QWheelEvent *event);
181
182 /**
183 * @reimp
184 *
185 * Reimplemented for internal reasons, the API is not affected.
186 *
187 * @see QWidget::mousePressEvent
188 * @internal
189 */
190 virtual void mousePressEvent(QMouseEvent *event);
191
192 /**
193 * @reimp
194 *
195 * Reimplemented for internal reasons, the API is not affected.
196 *
197 * @see QWidget::mouseReleaseEvent
198 * @internal
199 */
200 virtual void mouseReleaseEvent(QMouseEvent *event);
201
202private:
203 friend class KWebViewPrivate<KWebView>;
204 KWebViewPrivate<KWebView> * const d;
205};
206
207#endif // KWEBVIEW_H
208