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