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 | |
22 | class QMouseEvent; |
23 | |
24 | class KFilePlacesModel; |
25 | class KUrlComboBox; |
26 | |
27 | class 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 | */ |
37 | class KIOGUI_EXPORT KCoreUrlNavigator : public QObject |
38 | { |
39 | Q_OBJECT |
40 | |
41 | public: |
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 | |
161 | private: |
162 | friend class KCoreUrlNavigatorPrivate; |
163 | std::unique_ptr<KCoreUrlNavigatorPrivate> const d; |
164 | }; |
165 | |
166 | #endif |
167 | |