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
31 * \inmodule KIOGui
32 *
33 * \brief Object that helps with keeping track of URLs in file-manager like interfaces.
34 *
35 * \since 5.93
36 */
37class KIOGUI_EXPORT KCoreUrlNavigator : public QObject
38{
39 Q_OBJECT
40
41public:
42 KCoreUrlNavigator(const QUrl &url = QUrl(), QObject *parent = nullptr);
43 ~KCoreUrlNavigator() override;
44
45 /*!
46 * \property KCoreUrlNavigator::currentLocationUrl
47 */
48 Q_PROPERTY(QUrl currentLocationUrl READ currentLocationUrl WRITE setCurrentLocationUrl NOTIFY currentLocationUrlChanged)
49
50 QUrl currentLocationUrl() const;
51 void setCurrentLocationUrl(const QUrl &url);
52 Q_SIGNAL void currentLocationUrlChanged();
53
54 /*!
55 * Is emitted, before the location URL is going to be changed to \a newUrl.
56 *
57 * The signal KCoreUrlNavigator::urlChanged() will be emitted after the change
58 * has been done. Connecting to this signal is useful to save the state
59 * of a view with KCoreUrlNavigator::saveLocationState().
60 */
61 Q_SIGNAL void currentUrlAboutToChange(const QUrl &newUrl);
62
63 /*!
64 * \property KCoreUrlNavigator::historySize
65 *
66 * The amount of locations in the history. The data for each
67 * location can be retrieved by KCoreUrlNavigator::locationUrl() and
68 * KCoreUrlNavigator::locationState().
69 */
70 Q_PROPERTY(int historySize READ historySize NOTIFY historySizeChanged)
71 int historySize() const;
72 Q_SIGNAL void historySizeChanged();
73
74 /*!
75 * When the URL is changed and the new URL (e.g.\ /home/user1/)
76 * is a parent of the previous URL (e.g.\ /home/user1/data/stuff),
77 * then this signal is emitted and \a url is set to the child
78 * directory of the new URL which is an ancestor of the old URL
79 * (in the example paths this would be /home/user1/data/).
80 * This signal allows file managers to pre-select the directory
81 * that the user is navigating up from.
82 * \since 5.95
83 */
84 Q_SIGNAL void urlSelectionRequested(const QUrl &url);
85
86 /*!
87 * \property KCoreUrlNavigator::historyIndex
88 *
89 * The history index of the current location, where
90 * 0 <= history index < KCoreUrlNavigator::historySize(). 0 is the most
91 * recent history entry.
92 */
93 Q_PROPERTY(int historyIndex READ historyIndex NOTIFY historyIndexChanged)
94 int historyIndex() const;
95 Q_SIGNAL void historyIndexChanged();
96
97 /*!
98 * Is emitted, if the history has been changed. Usually
99 * the history is changed if a new URL has been selected.
100 */
101 Q_SIGNAL void historyChanged();
102
103 /*!
104 * Returns URL of the location given by the \a historyIndex. If \a historyIndex
105 * is smaller than 0, the URL of the current location is returned.
106 */
107 Q_INVOKABLE QUrl locationUrl(int historyIndex = -1) const;
108
109 /*!
110 * Saves the location state described by \a state for the current location. It is recommended
111 * that at least the scroll position of a view is remembered and restored when traversing
112 * through the history. Saving the location state should be done when the signal
113 * KCoreUrlNavigator::urlAboutToBeChanged() has been emitted. Restoring the location state (see
114 * KCoreUrlNavigator::locationState()) should be done when the signal KCoreUrlNavigator::urlChanged()
115 * has been emitted.
116 *
117 * Example:
118 * \code
119 * urlNavigator->saveLocationState(QPoint(x, y));
120 * \endcode
121 *
122 */
123 Q_INVOKABLE void saveLocationState(const QVariant &state);
124
125 /*!
126 * Returns Location state given by \a historyIndex. If \a historyIndex
127 * is smaller than 0, the state of the current location is returned.
128 * \sa KCoreUrlNavigator::saveLocationState()
129 */
130 Q_INVOKABLE QVariant locationState(int historyIndex = -1) const;
131
132 /*!
133 * Goes back one step in the URL history. The signals
134 * KCoreUrlNavigator::urlAboutToBeChanged(), KCoreUrlNavigator::urlChanged() and
135 * KCoreUrlNavigator::historyChanged() are emitted if true is returned. False is returned
136 * if the beginning of the history has already been reached and hence going back was
137 * not possible. The history index (see KCoreUrlNavigator::historyIndex()) is
138 * increased by one if the operation was successful.
139 */
140 Q_INVOKABLE bool goBack();
141
142 /*!
143 * Goes forward one step in the URL history. The signals
144 * KCoreUrlNavigator::urlAboutToBeChanged(), KCoreUrlNavigator::urlChanged() and
145 * KCoreUrlNavigator::historyChanged() are emitted if true is returned. False is returned
146 * if the end of the history has already been reached and hence going forward
147 * was not possible. The history index (see KCoreUrlNavigator::historyIndex()) is
148 * decreased by one if the operation was successful.
149 */
150 Q_INVOKABLE bool goForward();
151
152 /*!
153 * Goes up one step of the URL path and remembers the old path
154 * in the history. The signals KCoreUrlNavigator::urlAboutToBeChanged(),
155 * KCoreUrlNavigator::urlChanged() and KCoreUrlNavigator::historyChanged() are
156 * emitted if true is returned. False is returned if going up was not
157 * possible as the root has been reached.
158 */
159 Q_INVOKABLE bool goUp();
160
161private:
162 friend class KCoreUrlNavigatorPrivate;
163 std::unique_ptr<KCoreUrlNavigatorPrivate> const d;
164};
165
166#endif
167

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