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 | |
33 | class KUrl; |
34 | template<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 | */ |
55 | class KDEWEBKIT_EXPORT KGraphicsWebView : public QGraphicsWebView |
56 | { |
57 | Q_OBJECT |
58 | |
59 | public: |
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 | |
101 | Q_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 | |
170 | protected: |
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 | |
201 | private: |
202 | friend class KWebViewPrivate<KGraphicsWebView>; |
203 | KWebViewPrivate<KGraphicsWebView> * const d; |
204 | }; |
205 | |
206 | #endif // KWEBVIEW_H |
207 | |