2008-10-23 Yael Aharon <yael.aharon@nokia.com>
[WebKit-https.git] / WebKit / qt / Api / qwebhistory.cpp
1 /*
2     Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies)
3
4     This library is free software; you can redistribute it and/or
5     modify it under the terms of the GNU Library General Public
6     License as published by the Free Software Foundation; either
7     version 2 of the License, or (at your option) any later version.
8
9     This library is distributed in the hope that it will be useful,
10     but WITHOUT ANY WARRANTY; without even the implied warranty of
11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12     Library General Public License for more details.
13
14     You should have received a copy of the GNU Library General Public License
15     along with this library; see the file COPYING.LIB.  If not, write to
16     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17     Boston, MA 02110-1301, USA.
18 */
19
20 #include "config.h"
21 #include "qwebhistory.h"
22 #include "qwebhistory_p.h"
23
24 #include "PlatformString.h"
25 #include "Image.h"
26 #include "Page.h"
27 #include "PageGroup.h"
28
29 #include <QSharedData>
30
31 /*!
32   \class QWebHistoryItem
33   \ingroup explicitly-shared
34   \since 4.4
35   \brief The QWebHistoryItem class represents one item in the history of a QWebPage
36
37   Each QWebHistoryItem instance represents an entry in the history stack of a Web page,
38   containing information about the page, its location, and when it was last visited.
39
40   The following table shows the properties of the page held by the history item, and
41   the functions used to access them.
42
43   \table
44   \header \o Function      \o Description
45   \row    \o title()       \o The page title.
46   \row    \o url()         \o The location of the page.
47   \row    \o originalUrl() \o The URL used to access the page.
48   \row    \o lastVisited() \o The date and time of the user's last visit to the page.
49   \row    \o icon()        \o The icon associated with the page that was provided by the server.
50   \endtable
51
52   \note QWebHistoryItem objects are value based and \l{explicitly shared}.
53
54   \sa QWebHistory, QWebPage::history(), QWebHistoryInterface
55 */
56
57 /*!
58   Constructs a history item from \a other.
59 */
60 QWebHistoryItem::QWebHistoryItem(const QWebHistoryItem &other)
61     : d(other.d)
62 {
63 }
64
65 /*!
66   Assigns the \a other history item to this.
67 */
68 QWebHistoryItem &QWebHistoryItem::operator=(const QWebHistoryItem &other)
69 {
70     d = other.d;
71     return *this;
72 }
73
74 /*!
75   Destroys the history item.
76 */
77 QWebHistoryItem::~QWebHistoryItem()
78 {
79 }
80
81 /*!
82  Returns the original URL associated with the history item.
83
84  \sa url()
85 */
86 QUrl QWebHistoryItem::originalUrl() const
87 {
88     if (d->item)
89         return QUrl(d->item->originalURL().string());
90     return QUrl();
91 }
92
93
94 /*!
95  Returns the URL associated with the history item.
96
97  \sa originalUrl(), title(), lastVisited()
98 */
99 QUrl QWebHistoryItem::url() const
100 {
101     if (d->item)
102         return QUrl(d->item->url().string());
103     return QUrl();
104 }
105
106
107 /*!
108  Returns the title of the page associated with the history item.
109
110  \sa icon(), url(), lastVisited()
111 */
112 QString QWebHistoryItem::title() const
113 {
114     if (d->item)
115         return d->item->title();
116     return QString();
117 }
118
119
120 /*!
121  Returns the date and time that the page associated with the item was last visited.
122
123  \sa title(), icon(), url()
124 */
125 QDateTime QWebHistoryItem::lastVisited() const
126 {
127     //FIXME : this will be wrong unless we correctly set lastVisitedTime ourselves
128     if (d->item)
129         return QDateTime::fromTime_t((uint)d->item->lastVisitedTime());
130     return QDateTime();
131 }
132
133
134 /*!
135  Returns the icon associated with the history item.
136
137  \sa title(), url(), lastVisited()
138 */
139 QIcon QWebHistoryItem::icon() const
140 {
141     if (d->item)
142         return *d->item->icon()->nativeImageForCurrentFrame();
143     return QIcon();
144 }
145
146 /*!
147   \internal
148 */
149 QWebHistoryItem::QWebHistoryItem(QWebHistoryItemPrivate *priv)
150 {
151     d = priv;
152 }
153
154 /*!
155     \since 4.5
156     Returns whether this is a valid history item.
157 */
158 bool QWebHistoryItem::isValid() const
159 {
160     return d->item;
161 }
162
163 /*!
164   \class QWebHistory
165   \since 4.4
166   \brief The QWebHistory class represents the history of a QWebPage
167
168   Each QWebPage instance contains a history of visited pages that can be accessed
169   by QWebPage::history(). QWebHistory represents this history and makes it possible
170   to navigate it.
171
172   The history uses the concept of a \e{current item}, dividing the pages visited
173   into those that can be visited by navigating \e back and \e forward using the
174   back() and forward() functions. The current item can be obtained by calling
175   currentItem(), and an arbitrary item in the history can be made the current
176   item by passing it to goToItem().
177
178   A list of items describing the pages that can be visited by going back can be
179   obtained by calling the backItems() function; similarly, items describing the
180   pages ahead of the current page can be obtained with the forwardItems() function.
181   The total list of items is obtained with the items() function.
182
183   Just as with containers, functions are available to examine the history in terms
184   of a list. Arbitrary items in the history can be obtained with itemAt(), the total
185   number of items is given by count(), and the history can be cleared with the
186   clear() function.
187
188   \sa QWebHistoryItem, QWebHistoryInterface, QWebPage
189 */
190
191
192 QWebHistory::QWebHistory()
193     : d(0)
194 {
195 }
196
197 QWebHistory::~QWebHistory()
198 {
199     delete d;
200 }
201
202 /*!
203   Clears the history.
204
205   \sa count(), items()
206 */
207 void QWebHistory::clear()
208 {
209     RefPtr<WebCore::HistoryItem> current = d->lst->currentItem();
210     int capacity = d->lst->capacity();
211     d->lst->setCapacity(0);    
212
213     WebCore::Page* page = d->lst->page();
214     if (page && page->groupPtr())
215         page->groupPtr()->removeVisitedLinks();
216
217     d->lst->setCapacity(capacity);
218     d->lst->addItem(current.get());
219     d->lst->goToItem(current.get());
220 }
221
222 /*!
223   Returns a list of all items currently in the history.
224
225   \sa count(), clear()
226 */
227 QList<QWebHistoryItem> QWebHistory::items() const
228 {
229     const WebCore::HistoryItemVector &items = d->lst->entries();
230
231     QList<QWebHistoryItem> ret;
232     for (int i = 0; i < items.size(); ++i) {
233         QWebHistoryItemPrivate *priv = new QWebHistoryItemPrivate(items[i].get());
234         ret.append(QWebHistoryItem(priv));
235     }
236     return ret;
237 }
238
239 /*!
240   Returns the list of items in the backwards history list.
241   At most \a maxItems entries are returned.
242
243   \sa forwardItems()
244 */
245 QList<QWebHistoryItem> QWebHistory::backItems(int maxItems) const
246 {
247     WebCore::HistoryItemVector items(maxItems);
248     d->lst->backListWithLimit(maxItems, items);
249
250     QList<QWebHistoryItem> ret;
251     for (int i = 0; i < items.size(); ++i) {
252         QWebHistoryItemPrivate *priv = new QWebHistoryItemPrivate(items[i].get());
253         ret.append(QWebHistoryItem(priv));
254     }
255     return ret;
256 }
257
258 /*!
259   Returns the list of items in the forward history list.
260   At most \a maxItems entries are returned.
261
262   \sa backItems()
263 */
264 QList<QWebHistoryItem> QWebHistory::forwardItems(int maxItems) const
265 {
266     WebCore::HistoryItemVector items(maxItems);
267     d->lst->forwardListWithLimit(maxItems, items);
268
269     QList<QWebHistoryItem> ret;
270     for (int i = 0; i < items.size(); ++i) {
271         QWebHistoryItemPrivate *priv = new QWebHistoryItemPrivate(items[i].get());
272         ret.append(QWebHistoryItem(priv));
273     }
274     return ret;
275 }
276
277 /*!
278   Returns true if there is an item preceding the current item in the history;
279   otherwise returns false.
280
281   \sa canGoForward()
282 */
283 bool QWebHistory::canGoBack() const
284 {
285     return d->lst->backListCount() > 0;
286 }
287
288 /*!
289   Returns true if we have an item to go forward to; otherwise returns false.
290
291   \sa canGoBack()
292 */
293 bool QWebHistory::canGoForward() const
294 {
295     return d->lst->forwardListCount() > 0;
296 }
297
298 /*!
299   Set the current item to be the previous item in the history and goes to the
300   corresponding page; i.e., goes back one history item.
301
302   \sa forward(), goToItem()
303 */
304 void QWebHistory::back()
305 {
306     d->lst->goBack();
307     WebCore::Page* page = d->lst->page();
308     page->goToItem(currentItem().d->item, WebCore::FrameLoadTypeIndexedBackForward);
309 }
310
311 /*!
312   Sets the current item to be the next item in the history and goes to the
313   corresponding page; i.e., goes forward one history item.
314
315   \sa back(), goToItem()
316 */
317 void QWebHistory::forward()
318 {
319     d->lst->goForward();
320     WebCore::Page* page = d->lst->page();
321     page->goToItem(currentItem().d->item, WebCore::FrameLoadTypeIndexedBackForward);
322 }
323
324 /*!
325   Sets the current item to be the specified \a item in the history and goes to the page.
326
327   \sa back(), forward()
328 */
329 void QWebHistory::goToItem(const QWebHistoryItem &item)
330 {
331     d->lst->goToItem(item.d->item);
332     WebCore::Page* page = d->lst->page();
333     page->goToItem(currentItem().d->item, WebCore::FrameLoadTypeIndexedBackForward);
334 }
335
336 /*!
337   Returns the item before the current item in the history.
338 */
339 QWebHistoryItem QWebHistory::backItem() const
340 {
341     WebCore::HistoryItem *i = d->lst->backItem();
342     QWebHistoryItemPrivate *priv = new QWebHistoryItemPrivate(i);
343     return QWebHistoryItem(priv);
344 }
345
346 /*!
347   Returns the current item in the history.
348 */
349 QWebHistoryItem QWebHistory::currentItem() const
350 {
351     WebCore::HistoryItem *i = d->lst->currentItem();
352     QWebHistoryItemPrivate *priv = new QWebHistoryItemPrivate(i);
353     return QWebHistoryItem(priv);
354 }
355
356 /*!
357   Returns the item after the current item in the history.
358 */
359 QWebHistoryItem QWebHistory::forwardItem() const
360 {
361     WebCore::HistoryItem *i = d->lst->forwardItem();
362     QWebHistoryItemPrivate *priv = new QWebHistoryItemPrivate(i);
363     return QWebHistoryItem(priv);
364 }
365
366 /*!
367   Returns the item at index \a i in the history.
368 */
369 QWebHistoryItem QWebHistory::itemAt(int i) const
370 {
371     WebCore::HistoryItem *item = d->lst->itemAtIndex(i);
372
373     QWebHistoryItemPrivate *priv = new QWebHistoryItemPrivate(item);
374     return QWebHistoryItem(priv);
375 }
376
377 /*!
378     Returns the total number of items in the history.
379 */
380 int QWebHistory::count() const
381 {
382     return d->lst->entries().size();
383 }
384