File indexing completed on 2024-11-03 03:41:11
0001 /* 0002 SPDX-FileCopyrightText: 2006-2010 Peter Penz <peter.penz@gmx.at> 0003 SPDX-FileCopyrightText: 2006 Aaron J. Seigo <aseigo@kde.org> 0004 SPDX-FileCopyrightText: 2007 Kevin Ottens <ervin@kde.org> 0005 SPDX-FileCopyrightText: 2007 Urs Wolfer <uwolfer @ kde.org> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 0010 #ifndef KURLNAVIGATOR_H 0011 #define KURLNAVIGATOR_H 0012 0013 #include "kiofilewidgets_export.h" 0014 0015 #include <QByteArray> 0016 #include <QUrl> 0017 #include <QWidget> 0018 0019 #include <memory> 0020 0021 class QMouseEvent; 0022 0023 class KFilePlacesModel; 0024 class KUrlComboBox; 0025 0026 class KUrlNavigatorPrivate; 0027 0028 /** 0029 * @class KUrlNavigator kurlnavigator.h <KUrlNavigator> 0030 * 0031 * @brief Widget that allows to navigate through the paths of an URL. 0032 * 0033 * The URL navigator offers two modes: 0034 * - Editable: The URL of the location is editable inside an editor. 0035 * By pressing RETURN the URL will get activated. 0036 * - Non editable ("breadcrumb view"): The URL of the location is represented by 0037 * a number of buttons, where each button represents a path 0038 * of the URL. By clicking on a button the path will get 0039 * activated. This mode also supports drag and drop of items. 0040 * 0041 * The mode can be changed by clicking on the empty area of the URL navigator. 0042 * It is recommended that the application remembers the setting 0043 * or allows to configure the default mode (see KUrlNavigator::setUrlEditable()). 0044 * 0045 * The URL navigator remembers the URL history during navigation and allows to go 0046 * back and forward within this history. 0047 * 0048 * In the non editable mode ("breadcrumb view") it can be configured whether 0049 * the full path should be shown. It is recommended that the application 0050 * remembers the setting or allows to configure the default mode (see 0051 * KUrlNavigator::setShowFullPath()). 0052 * 0053 * The typical usage of the KUrlNavigator is: 0054 * - Create an instance providing a places model and an URL. 0055 * - Create an instance of QAbstractItemView which shows the content of the URL 0056 * given by the URL navigator. 0057 * - Connect to the signal KUrlNavigator::urlChanged() and synchronize the content of 0058 * QAbstractItemView with the URL given by the URL navigator. 0059 * 0060 * It is recommended, that the application remembers the state of the QAbstractItemView 0061 * when the URL has been changed. This allows to restore the view state when going back in history. 0062 * KUrlNavigator offers support for remembering the view state: 0063 * - The signal urlAboutToBeChanged() will be emitted before the URL change takes places. 0064 * This allows the application to store the view state by KUrlNavigator::saveLocationState(). 0065 * - The signal urlChanged() will be emitted after the URL change took place. This allows 0066 * the application to restore the view state by getting the values from 0067 * KUrlNavigator::locationState(). 0068 */ 0069 class KIOFILEWIDGETS_EXPORT KUrlNavigator : public QWidget 0070 { 0071 Q_OBJECT 0072 0073 public: 0074 /** @since 4.5 */ 0075 KUrlNavigator(QWidget *parent = nullptr); 0076 0077 /** 0078 * @param placesModel Model for the places which are selectable inside a 0079 * menu. A place can be a bookmark or a device. If it is 0, 0080 * no places selector is displayed. 0081 * @param url URL which is used for the navigation or editing. 0082 * @param parent Parent widget. 0083 */ 0084 KUrlNavigator(KFilePlacesModel *placesModel, const QUrl &url, QWidget *parent); 0085 ~KUrlNavigator() override; 0086 0087 /** 0088 * @return URL of the location given by the \a historyIndex. If \a historyIndex 0089 * is smaller than 0, the URL of the current location is returned. 0090 * @since 4.5 0091 */ 0092 QUrl locationUrl(int historyIndex = -1) const; 0093 0094 /** 0095 * Saves the location state described by \a state for the current location. It is recommended 0096 * that at least the scroll position of a view is remembered and restored when traversing 0097 * through the history. Saving the location state should be done when the signal 0098 * KUrlNavigator::urlAboutToBeChanged() has been emitted. Restoring the location state (see 0099 * KUrlNavigator::locationState()) should be done when the signal KUrlNavigator::urlChanged() 0100 * has been emitted. 0101 * 0102 * Example: 0103 * \code 0104 * QByteArray state; 0105 * QDataStream data(&state, QIODevice::WriteOnly); 0106 * data << QPoint(x, y); 0107 * data << ...; 0108 * ... 0109 * urlNavigator->saveLocationState(state); 0110 * \endcode 0111 * 0112 */ 0113 void saveLocationState(const QByteArray &state); 0114 0115 /** 0116 * @return Location state given by \a historyIndex. If \a historyIndex 0117 * is smaller than 0, the state of the current location is returned. 0118 * @see KUrlNavigator::saveLocationState() 0119 * @since 4.5 0120 */ 0121 QByteArray locationState(int historyIndex = -1) const; 0122 0123 /** 0124 * Goes back one step in the URL history. The signals 0125 * KUrlNavigator::urlAboutToBeChanged(), KUrlNavigator::urlChanged() and 0126 * KUrlNavigator::historyChanged() are emitted if true is returned. False is returned 0127 * if the beginning of the history has already been reached and hence going back was 0128 * not possible. The history index (see KUrlNavigator::historyIndex()) is 0129 * increased by one if the operation was successful. 0130 */ 0131 bool goBack(); 0132 0133 /** 0134 * Goes forward one step in the URL history. The signals 0135 * KUrlNavigator::urlAboutToBeChanged(), KUrlNavigator::urlChanged() and 0136 * KUrlNavigator::historyChanged() are emitted if true is returned. False is returned 0137 * if the end of the history has already been reached and hence going forward 0138 * was not possible. The history index (see KUrlNavigator::historyIndex()) is 0139 * decreased by one if the operation was successful. 0140 */ 0141 bool goForward(); 0142 0143 /** 0144 * Goes up one step of the URL path and remembers the old path 0145 * in the history. The signals KUrlNavigator::urlAboutToBeChanged(), 0146 * KUrlNavigator::urlChanged() and KUrlNavigator::historyChanged() are 0147 * emitted if true is returned. False is returned if going up was not 0148 * possible as the root has been reached. 0149 */ 0150 bool goUp(); 0151 0152 /** 0153 * Goes to the home URL and remembers the old URL in the history. 0154 * The signals KUrlNavigator::urlAboutToBeChanged(), KUrlNavigator::urlChanged() 0155 * and KUrlNavigator::historyChanged() are emitted. 0156 * 0157 * @see KUrlNavigator::setHomeUrl() 0158 */ 0159 // KDE5: Remove the home-property. It is sufficient to invoke 0160 // KUrlNavigator::setLocationUrl(homeUrl) on application-side. 0161 void goHome(); 0162 0163 /** 0164 * Sets the home URL used by KUrlNavigator::goHome(). If no 0165 * home URL is set, the default home path of the user is used. 0166 */ 0167 // KDE5: Remove the home-property. It is sufficient to invoke 0168 // KUrlNavigator::setLocationUrl(homeUrl) on application-side. 0169 void setHomeUrl(const QUrl &url); 0170 0171 QUrl homeUrl() const; 0172 0173 /** 0174 * Allows to edit the URL of the navigation bar if \a editable 0175 * is true, and sets the focus accordingly. 0176 * If \a editable is false, each part of 0177 * the URL is presented by a button for a fast navigation ("breadcrumb view"). 0178 */ 0179 void setUrlEditable(bool editable); 0180 0181 /** 0182 * @return True, if the URL is editable within a line editor. 0183 * If false is returned, each part of the URL is presented by a button 0184 * for fast navigation ("breadcrumb view"). 0185 */ 0186 bool isUrlEditable() const; 0187 0188 /** 0189 * Shows the full path of the URL even if a place represents a part of the URL. 0190 * Assuming that a place called "Pictures" uses the URL /home/user/Pictures. 0191 * An URL like /home/user/Pictures/2008 is shown as [Pictures] > [2008] 0192 * in the breadcrumb view, if showing the full path is turned off. If 0193 * showing the full path is turned on, the URL is shown 0194 * as [/] > [home] > [Pictures] > [2008]. 0195 */ 0196 void setShowFullPath(bool show); 0197 0198 /** 0199 * @return True, if the full path of the URL should be shown in the breadcrumb view. 0200 * @since 4.2 0201 */ 0202 bool showFullPath() const; 0203 0204 /** 0205 * Set the URL navigator to the active mode, if \a active 0206 * is true. The active mode is default. The inactive mode only differs 0207 * visually from the active mode, no change of the behavior is given. 0208 * 0209 * Using the URL navigator in the inactive mode is useful when having split views, 0210 * where the inactive view is indicated by an inactive URL 0211 * navigator visually. 0212 */ 0213 void setActive(bool active); 0214 0215 /** 0216 * @return True, if the URL navigator is in the active mode. 0217 * @see KUrlNavigator::setActive() 0218 */ 0219 bool isActive() const; 0220 0221 /** 0222 * Sets the places selector visible, if \a visible is true. 0223 * The places selector allows to select the places provided 0224 * by the places model passed in the constructor. Per default 0225 * the places selector is visible. 0226 */ 0227 void setPlacesSelectorVisible(bool visible); 0228 0229 /** @return True, if the places selector is visible. */ 0230 bool isPlacesSelectorVisible() const; 0231 0232 /** 0233 * @return The currently entered, but not accepted URL. 0234 * It is possible that the returned URL is not valid. 0235 */ 0236 QUrl uncommittedUrl() const; 0237 0238 /** 0239 * @return The amount of locations in the history. The data for each 0240 * location can be retrieved by KUrlNavigator::locationUrl() and 0241 * KUrlNavigator::locationState(). 0242 */ 0243 int historySize() const; 0244 0245 /** 0246 * @return The history index of the current location, where 0247 * 0 <= history index < KUrlNavigator::historySize(). 0 is the most 0248 * recent history entry. 0249 */ 0250 int historyIndex() const; 0251 0252 /** 0253 * @return The used editor when the navigator is in the edit mode 0254 * @see KUrlNavigator::setUrlEditable() 0255 */ 0256 KUrlComboBox *editor() const; 0257 0258 /** 0259 * Set the URL schemes that the navigator should allow navigating to. 0260 * 0261 * If the passed list is empty, all schemes are supported. Examples for 0262 * schemes are @c "file" or @c "ftp". 0263 * 0264 * @sa QFileDialog::setSupportedSchemes 0265 * @since 5.103 0266 */ 0267 void setSupportedSchemes(const QStringList &schemes); 0268 0269 /** 0270 * Returns the URL schemes that the navigator should allow navigating to. 0271 * 0272 * If the returned list is empty, all schemes are supported. 0273 * 0274 * @sa QFileDialog::supportedSchemes 0275 * @since 5.103 0276 */ 0277 QStringList supportedSchemes() const; 0278 0279 /** 0280 * The child widget that received the QDropEvent when dropping on the URL 0281 * navigator. You can pass this widget to KJobWidgets::setWindow() 0282 * if you need to show a drop menu with KIO::drop(). 0283 * @return Child widget that has received the last drop event, or nullptr if 0284 * nothing has been dropped yet on the URL navigator. 0285 * @since 5.37 0286 * @see KIO::drop() 0287 */ 0288 QWidget *dropWidget() const; 0289 0290 /** 0291 * Sets whether to show hidden folders in the subdirectories popup. 0292 * @since 5.87 0293 */ 0294 void setShowHiddenFolders(bool showHiddenFolders); 0295 0296 /** 0297 * Returns whether to show hidden folders in the subdirectories popup. 0298 * @since 5.87 0299 */ 0300 bool showHiddenFolders() const; 0301 0302 /** 0303 * Sets whether to sort hidden folders in the subdirectories popup last. 0304 * @since 5.87 0305 */ 0306 void setSortHiddenFoldersLast(bool sortHiddenFoldersLast); 0307 0308 /** 0309 * Returns whether to sort hidden folders in the subdirectories popup last. 0310 * @since 5.87 0311 */ 0312 bool sortHiddenFoldersLast() const; 0313 0314 public Q_SLOTS: 0315 /** 0316 * Sets the location to \a url. The old URL is added to the history. 0317 * The signals KUrlNavigator::urlAboutToBeChanged(), KUrlNavigator::urlChanged() 0318 * and KUrlNavigator::historyChanged() are emitted. Use 0319 * KUrlNavigator::locationUrl() to read the location. 0320 */ 0321 void setLocationUrl(const QUrl &url); 0322 0323 /** 0324 * Activates the URL navigator (KUrlNavigator::isActive() will return true) 0325 * and emits the signal KUrlNavigator::activated(). 0326 * @see KUrlNavigator::setActive() 0327 */ 0328 void requestActivation(); 0329 0330 #if !defined(K_DOXYGEN) 0331 // KDE5: Remove and listen for focus-signal instead 0332 void setFocus(); 0333 #endif 0334 0335 Q_SIGNALS: 0336 /** 0337 * Is emitted, if the URL navigator has been activated by 0338 * an user interaction 0339 * @see KUrlNavigator::setActive() 0340 */ 0341 void activated(); 0342 0343 /** 0344 * Is emitted, if the location URL has been changed e. g. by 0345 * the user. 0346 * @see KUrlNavigator::setUrl() 0347 */ 0348 void urlChanged(const QUrl &url); 0349 0350 /** 0351 * Is emitted, before the location URL is going to be changed to \a newUrl. 0352 * The signal KUrlNavigator::urlChanged() will be emitted after the change 0353 * has been done. Connecting to this signal is useful to save the state 0354 * of a view with KUrlNavigator::saveLocationState(). 0355 */ 0356 void urlAboutToBeChanged(const QUrl &newUrl); 0357 0358 /** 0359 * Is emitted, if the editable state for the URL has been changed 0360 * (see KUrlNavigator::setUrlEditable()). 0361 */ 0362 void editableStateChanged(bool editable); 0363 0364 /** 0365 * Is emitted, if the history has been changed. Usually 0366 * the history is changed if a new URL has been selected. 0367 */ 0368 void historyChanged(); 0369 0370 /** 0371 * Is emitted if a dropping has been done above the destination 0372 * \a destination. The receiver must accept the drop event if 0373 * the dropped data can be handled. 0374 */ 0375 void urlsDropped(const QUrl &destination, QDropEvent *event); 0376 0377 /** 0378 * This signal is emitted when the Return or Enter key is pressed. 0379 */ 0380 void returnPressed(); 0381 0382 /** 0383 * Is emitted if the URL \a url should be opened in a new inactive tab because 0384 * the user clicked on a breadcrumb with the middle mouse button or 0385 * left-clicked with the ctrl modifier pressed. 0386 */ 0387 void tabRequested(const QUrl &url); 0388 0389 /** 0390 * Is emitted if the URL \a url should be opened in a new active tab because 0391 * the user clicked on a breadcrumb with the middle mouse button with 0392 * the shift modifier pressed or left-clicked with both the ctrl and shift 0393 * modifiers pressed. 0394 * @since 5.89 0395 */ 0396 void activeTabRequested(const QUrl &url); 0397 0398 /** 0399 * Is emitted if the URL \a url should be opened in a new window because 0400 * the user left-clicked on a breadcrumb with the shift modifier pressed. 0401 * @since 5.89 0402 */ 0403 void newWindowRequested(const QUrl &url); 0404 0405 /** 0406 * When the URL is changed and the new URL (e.g.\ /home/user1/) 0407 * is a parent of the previous URL (e.g.\ /home/user1/data/stuff), 0408 * then this signal is emitted and \p url is set to the child 0409 * directory of the new URL which is an ancestor of the old URL 0410 * (in the example paths this would be /home/user1/data/). 0411 * This signal allows file managers to pre-select the directory 0412 * that the user is navigating up from. 0413 * @since 5.37.0 0414 */ 0415 void urlSelectionRequested(const QUrl &url); 0416 0417 protected: 0418 #if !defined(K_DOXYGEN) 0419 /** 0420 * If the Escape key is pressed, the navigation bar should switch 0421 * to the breadcrumb view. 0422 * @see QWidget::keyPressEvent() 0423 */ 0424 void keyPressEvent(QKeyEvent *event) override; 0425 0426 /** 0427 * Reimplemented for internal purposes. 0428 */ 0429 void keyReleaseEvent(QKeyEvent *event) override; 0430 0431 /** 0432 * Paste the clipboard content as URL, if the middle mouse 0433 * button has been clicked. 0434 * @see QWidget::mouseReleaseEvent() 0435 */ 0436 void mouseReleaseEvent(QMouseEvent *event) override; 0437 0438 /** 0439 * Reimplemented to activate on middle mousse button click 0440 */ 0441 void mousePressEvent(QMouseEvent *event) override; 0442 0443 void resizeEvent(QResizeEvent *event) override; 0444 0445 void wheelEvent(QWheelEvent *event) override; 0446 0447 bool eventFilter(QObject *watched, QEvent *event) override; 0448 #endif 0449 0450 private: 0451 friend class KUrlNavigatorPrivate; 0452 std::unique_ptr<KUrlNavigatorPrivate> const d; 0453 0454 Q_DISABLE_COPY(KUrlNavigator) 0455 }; 0456 0457 #endif