1/*
2 SPDX-FileCopyrightText: 2006-2010 Peter Penz <peter.penz@gmx.at>
3 SPDX-FileCopyrightText: 2006 Aaron J. Seigo <aseigo@kde.org>
4 SPDX-FileCopyrightText: 2007 Kevin Ottens <ervin@kde.org>
5 SPDX-FileCopyrightText: 2007 Urs Wolfer <uwolfer @ kde.org>
6 SPDX-FileCopyrightText: 2022 Carson Black <uhhadd@gmail.com>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KCOREURLNAVIGATOR_H
12#define KCOREURLNAVIGATOR_H
13
14#include "kiogui_export.h"
15
16#include <QByteArray>
17#include <QObject>
18#include <QUrl>
19
20#include <memory>
21
22class QMouseEvent;
23
24class KFilePlacesModel;
25class KUrlComboBox;
26
27class KCoreUrlNavigatorPrivate;
28
29/**
30 * @class KCoreUrlNavigator kcoreurlnavigator.h <KCoreUrlNavigator>
31 *
32 * @brief Object that helps with keeping track of URLs in file-manager like interfaces.
33 *
34 * @since 5.93
35 */
36class KIOGUI_EXPORT KCoreUrlNavigator : public QObject
37{
38 Q_OBJECT
39
40public:
41 KCoreUrlNavigator(const QUrl &url = QUrl(), QObject *parent = nullptr);
42 ~KCoreUrlNavigator() override;
43
44 Q_PROPERTY(QUrl currentLocationUrl READ currentLocationUrl WRITE setCurrentLocationUrl NOTIFY currentLocationUrlChanged)
45
46 QUrl currentLocationUrl() const;
47 void setCurrentLocationUrl(const QUrl &url);
48 Q_SIGNAL void currentLocationUrlChanged();
49
50 /**
51 * Is emitted, before the location URL is going to be changed to \a newUrl.
52 * The signal KCoreUrlNavigator::urlChanged() will be emitted after the change
53 * has been done. Connecting to this signal is useful to save the state
54 * of a view with KCoreUrlNavigator::saveLocationState().
55 */
56 Q_SIGNAL void currentUrlAboutToChange(const QUrl &newUrl);
57
58 /**
59 * The amount of locations in the history. The data for each
60 * location can be retrieved by KCoreUrlNavigator::locationUrl() and
61 * KCoreUrlNavigator::locationState().
62 */
63 Q_PROPERTY(int historySize READ historySize NOTIFY historySizeChanged)
64 int historySize() const;
65 Q_SIGNAL void historySizeChanged();
66
67 /**
68 * When the URL is changed and the new URL (e.g.\ /home/user1/)
69 * is a parent of the previous URL (e.g.\ /home/user1/data/stuff),
70 * then this signal is emitted and \p url is set to the child
71 * directory of the new URL which is an ancestor of the old URL
72 * (in the example paths this would be /home/user1/data/).
73 * This signal allows file managers to pre-select the directory
74 * that the user is navigating up from.
75 * @since 5.95
76 */
77 Q_SIGNAL void urlSelectionRequested(const QUrl &url);
78
79 /**
80 * The history index of the current location, where
81 * 0 <= history index < KCoreUrlNavigator::historySize(). 0 is the most
82 * recent history entry.
83 */
84 Q_PROPERTY(int historyIndex READ historyIndex NOTIFY historyIndexChanged)
85 int historyIndex() const;
86 Q_SIGNAL void historyIndexChanged();
87
88 /**
89 * Is emitted, if the history has been changed. Usually
90 * the history is changed if a new URL has been selected.
91 */
92 Q_SIGNAL void historyChanged();
93
94 /**
95 * @return URL of the location given by the \a historyIndex. If \a historyIndex
96 * is smaller than 0, the URL of the current location is returned.
97 */
98 Q_INVOKABLE QUrl locationUrl(int historyIndex = -1) const;
99
100 /**
101 * Saves the location state described by \a state for the current location. It is recommended
102 * that at least the scroll position of a view is remembered and restored when traversing
103 * through the history. Saving the location state should be done when the signal
104 * KCoreUrlNavigator::urlAboutToBeChanged() has been emitted. Restoring the location state (see
105 * KCoreUrlNavigator::locationState()) should be done when the signal KCoreUrlNavigator::urlChanged()
106 * has been emitted.
107 *
108 * Example:
109 * \code
110 * urlNavigator->saveLocationState(QPoint(x, y));
111 * \endcode
112 *
113 */
114 Q_INVOKABLE void saveLocationState(const QVariant &state);
115
116 /**
117 * @return Location state given by \a historyIndex. If \a historyIndex
118 * is smaller than 0, the state of the current location is returned.
119 * @see KCoreUrlNavigator::saveLocationState()
120 */
121 Q_INVOKABLE QVariant locationState(int historyIndex = -1) const;
122
123 /**
124 * Goes back one step in the URL history. The signals
125 * KCoreUrlNavigator::urlAboutToBeChanged(), KCoreUrlNavigator::urlChanged() and
126 * KCoreUrlNavigator::historyChanged() are emitted if true is returned. False is returned
127 * if the beginning of the history has already been reached and hence going back was
128 * not possible. The history index (see KCoreUrlNavigator::historyIndex()) is
129 * increased by one if the operation was successful.
130 */
131 Q_INVOKABLE bool goBack();
132
133 /**
134 * Goes forward one step in the URL history. The signals
135 * KCoreUrlNavigator::urlAboutToBeChanged(), KCoreUrlNavigator::urlChanged() and
136 * KCoreUrlNavigator::historyChanged() are emitted if true is returned. False is returned
137 * if the end of the history has already been reached and hence going forward
138 * was not possible. The history index (see KCoreUrlNavigator::historyIndex()) is
139 * decreased by one if the operation was successful.
140 */
141 Q_INVOKABLE bool goForward();
142
143 /**
144 * Goes up one step of the URL path and remembers the old path
145 * in the history. The signals KCoreUrlNavigator::urlAboutToBeChanged(),
146 * KCoreUrlNavigator::urlChanged() and KCoreUrlNavigator::historyChanged() are
147 * emitted if true is returned. False is returned if going up was not
148 * possible as the root has been reached.
149 */
150 Q_INVOKABLE bool goUp();
151
152private:
153 friend class KCoreUrlNavigatorPrivate;
154 std::unique_ptr<KCoreUrlNavigatorPrivate> const d;
155};
156
157#endif
158

source code of kio/src/gui/kcoreurlnavigator.h