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 | |
33 | class KUrl; |
34 | template<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 | */ |
56 | class KDEWEBKIT_EXPORT KWebView : public QWebView |
57 | { |
58 | Q_OBJECT |
59 | Q_PROPERTY(bool externalContentAllowed READ isExternalContentAllowed WRITE setAllowExternalContent) |
60 | public: |
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 | |
102 | Q_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 | |
171 | protected: |
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 | |
202 | private: |
203 | friend class KWebViewPrivate<KWebView>; |
204 | KWebViewPrivate<KWebView> * const d; |
205 | }; |
206 | |
207 | #endif // KWEBVIEW_H |
208 | |