KIO

kcoreurlnavigator.h
1 /*
2  SPDX-FileCopyrightText: 2006-2010 Peter Penz <[email protected]>
3  SPDX-FileCopyrightText: 2006 Aaron J. Seigo <[email protected]>
4  SPDX-FileCopyrightText: 2007 Kevin Ottens <[email protected]>
5  SPDX-FileCopyrightText: 2007 Urs Wolfer <uwolfer @ kde.org>
6  SPDX-FileCopyrightText: 2022 Carson Black <[email protected]>
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 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  */
36 class KIOGUI_EXPORT KCoreUrlNavigator : public QObject
37 {
38  Q_OBJECT
39 
40 public:
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 
152 private:
153  friend class KCoreUrlNavigatorPrivate;
154  std::unique_ptr<KCoreUrlNavigatorPrivate> const d;
155 };
156 
157 #endif
Q_PROPERTY(...)
Object that helps with keeping track of URLs in file-manager like interfaces.
A combo box showing a number of recent URLs/directories.
Definition: kurlcombobox.h:42
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Feb 7 2023 04:00:35 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.