kfile/kurlnavigator.h

   1 /*****************************************************************************
   2  * Copyright (C) 2006 by Peter Penz <peter.penz@gmx.at>                      *
   3  * Copyright (C) 2006 by Aaron J. Seigo <aseigo@kde.org>                     *
   4  * Copyright (C) 2007 by Kevin Ottens <ervin@kde.org>                        *
   5  * Copyright (C) 2007 by Urs Wolfer <uwolfer @ kde.org>                      *
   6  *                                                                           *
   7  * This library is free software; you can redistribute it and/or             *
   8  * modify it under the terms of the GNU Library General Public               *
   9  * License version 2 as published by the Free Software Foundation.           *
  10  *                                                                           *
  11  * This library is distributed in the hope that it will be useful,           *
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of            *
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU         *
  14  * Library General Public License for more details.                          *
  15  *                                                                           *
  16  * You should have received a copy of the GNU Library General Public License *
  17  * along with this library; see the file COPYING.LIB.  If not, write to      *
  18  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,      *
  19  * Boston, MA 02110-1301, USA.                                               *
  20  *****************************************************************************/
  21
  22 #ifndef KURLNAVIGATOR_H
  23 #define KURLNAVIGATOR_H
  24
  25 #include <kfile_export.h>
  26
  27 #include <kurl.h>
  28 #include <QtGui/QWidget>
  29
  30 class KFilePlacesModel;
  31 class KUrlComboBox;
  32 class QMouseEvent;
  33
  34 /**
  35  * @brief Allows to navigate through the paths of an URL.
  36  *
  37  * The URL navigator offers two modes:
  38  * - Editable:     Represents the 'classic' mode, where the URL
  39  *                 is editable inside a line editor. By pressing RETURN
  40  *                 the URL will get activated.
  41  * - Non editable ("breadcrumb view"): The URL is represented by a
  42  *                 number of buttons, where each button represents a path
  43  *                 of the URL. By clicking on a button the path will get
  44  *                 activated. This mode also supports drag and drop of items.
  45  *
  46  * The mode can be changed by clicking on the empty area of the URL navigator.
  47  * It is recommended that the application remembers the setting
  48  * or allows to configure the default mode (see KUrlNavigator::setUrlEditable()).
  49  *
  50  * The URL navigator remembers the URL history during navigation and allows to go
  51  * back and forward within this history.
  52  *
  53  * In the non editable mode ("breadcrumb view") it can be configured whether
  54  * the full path should be shown. It is recommended that the application
  55  * remembers the setting or allows to configure the default mode (see
  56  * KUrlNavigator::setShowFullPath()).
  57  *
  58  * The typical usage of the KUrlNavigator is:
  59  * - Create an instance providing a places model and an URL.
  60  * - Create an instance of QAbstractItemView which shows the content of the URL
  61  *   given by the URL navigator.
  62  * - Connect to the signal KUrlNavigator::urlChanged() and synchronize the content of
  63  *   QAbstractItemView with the URL given by the URL navigator.
  64  */
  65 class KFILE_EXPORT KUrlNavigator : public QWidget
  66 {
  67     Q_OBJECT
  68
  69 public:
  70     /**
  71      * @param placesModel    Model for the places which are selectable inside a
  72      *                       menu. A place can be a bookmark or a device. If it is 0,
  73                              there is no places selector displayed.
  74      * @param url            URL which is used for the navigation or editing.
  75      * @param parent         Parent widget.
  76      */
  77     KUrlNavigator(KFilePlacesModel* placesModel, const KUrl& url, QWidget* parent);
  78     virtual ~KUrlNavigator();
  79
  80     /** Returns the current URL. */
  81     const KUrl& url() const;
  82
  83     /**
  84      * Returns the currently entered, but not accepted URL.
  85      * Attention: It is possible that the returned URL is not valid!
  86      */
  87     KUrl uncommittedUrl() const;
  88
  89     /**
  90      * Returns the portion of the current URL up to the path part given
  91      * by \a index. Assuming that the current URL is /home/peter/Documents/Music,
  92      * then the following URLs are returned for an index:
  93      * - index <= 0: /home
  94      * - index is 1: /home/peter
  95      * - index is 2: /home/peter/Documents
  96      * - index >= 3: /home/peter/Documents/Music
  97      */
  98     KUrl url(int index) const;
  99
 100     /**
 101      * Goes back one step in the URL history. The signals
 102      * KUrlNavigator::urlChanged() and KUrlNavigator::historyChanged()
 103      * are emitted if true is returned. False is returned if the beginning
 104      * of the history has already been reached and hence going back was not
 105      * possible. The history index (see KUrlNavigator::historyIndex()) is
 106      * increased by one if the operation was successful.
 107      */
 108     bool goBack();
 109
 110     /**
 111      * Goes forward one step in the URL history. The signals
 112      * KUrlNavigator::urlChanged() and KUrlNavigator::historyChanged()
 113      * are emitted if true is returned. False is returned if the end
 114      * of the history has already been reached and hence going forward
 115      * was not possible. The history index (see KUrlNavigator::historyIndex()) is
 116      * decreased by one if the operation was successful.
 117      */
 118     bool goForward();
 119
 120     /**
 121      * Goes up one step of the URL path and remembers the old path
 122      * in the history. The signals KUrlNavigator::urlChanged() and
 123      * KUrlNavigator::historyChanged() are emitted if true is returned.
 124      * False is returned if going up was not possible as the root has
 125      * been reached.
 126      */
 127     bool goUp();
 128
 129     /**
 130      * Goes to the home URL and remembers the old URL in the history.
 131      * The signals KUrlNavigator::urlChanged()
 132      * and KUrlNavigator::historyChanged() are emitted.
 133      *
 134      * @see KUrlNavigator::setHomeUrl()
 135      */
 136     void goHome();
 137
 138     /**
 139      * Sets the home URL used by KUrlNavigator::goHome(). If no
 140      * home URL is set, the default home path of the user is used.
 141      */
 142     void setHomeUrl(const QString& homeUrl);
 143
 144     /**
 145      * Allows to edit the URL of the navigation bar if \a editable
 146      * is true, and sets the focus accordingly.
 147      * If \a editable is false, each part of
 148      * the URL is presented by a button for a fast navigation ("breadcrumb view").
 149      */
 150     void setUrlEditable(bool editable);
 151
 152     /**
 153      * @return True, if the URL is editable within a line editor.
 154      *         If false is returned, each part of the URL is presented by a button
 155      *         for fast navigation ("breadcrumb view").
 156      */
 157     bool isUrlEditable() const;
 158
 159     /**
 160      * Shows the full path of the URL even if a place represents a part of the URL.
 161      * Assuming that a place called "Pictures" uses the URL /home/user/Pictures.
 162      * An URL like /home/user/Pictures/2008 is shown as [Pictures] > [2008]
 163      * in the breadcrumb view, if showing the full path is turned off. If
 164      * showing the full path is turned on, the URL is shown
 165      * as [/] > [home] > [Pictures] > [2008].
 166      * @since 4.2
 167      */
 168     void setShowFullPath(bool show);
 169
 170     /**
 171      * @return True, if the full path of the URL should be shown in the breadcrumb view.
 172      * @since 4.2
 173      */
 174     bool showFullPath() const;
 175
 176     /**
 177      * Set the URL navigator to the active mode, if \a active
 178      * is true. The active mode is default. The inactive mode only differs
 179      * visually from the active mode, no change of the behavior is given.
 180      *
 181      * Using the URL navigator in the inactive mode is useful when having split views,
 182      * where the inactive view is indicated by an inactive URL
 183      * navigator visually.
 184      */
 185     void setActive(bool active);
 186
 187     /**
 188      * Returns true, if the URL navigator is in the active mode.
 189      * @see KUrlNavigator::setActive()
 190      */
 191     bool isActive() const;
 192
 193     /**
 194      * Sets the places selector visible, if \a visible is true.
 195      * The places selector allows to select the places provided
 196      * by the places model passed in the constructor. Per default
 197      * the places selector is visible.
 198      */
 199     void setPlacesSelectorVisible(bool visible);
 200
 201     /** Returns true, if the places selector is visible. */
 202     bool isPlacesSelectorVisible() const;
 203
 204     /** Returns the amount of items in the history. */
 205     int historySize() const;
 206
 207     /**
 208      * Returns the history index of the current URL, where
 209      * 0 <= history index < KUrlNavigator::historySize(). As long
 210      * as KUrlNavigator::goBack() is not invoked, the history index
 211      * stays on 0.
 212      */
 213     int historyIndex() const;
 214
 215     /**
 216      * Returns the saved root URL for the current URL
 217      * (see KUrlNavigator::saveRootUrl()).
 218      */
 219     const KUrl& savedRootUrl() const;
 220
 221     /**
 222      * Returns the saved contents position of the upper left corner
 223      * for the current URL.
 224      */
 225     QPoint savedPosition() const;
 226
 227     /**
 228      * Returns the used editor when the navigator is in the edit mode
 229      * (see KUrlNavigator::setUrlEditable()).
 230      */
 231     KUrlComboBox* editor() const;
 232
 233     /**
 234      * If an application supports only some special protocols, they can be set
 235      * with \a protocols .
 236      */
 237     void setCustomProtocols(const QStringList &protocols);
 238
 239     /**
 240      * Returns the custom protocols if they are set, QStringList() otherwise.
 241      */
 242     QStringList customProtocols() const;
 243
 244 public Q_SLOTS:
 245     /**
 246      * Sets the active URL to \a url. The old URL is added to the history.
 247      * The signals KUrlNavigator::urlChanged() and KUrlNavigator::historyChanged()
 248      * are emitted.
 249      */
 250     void setUrl(const KUrl& url);
 251
 252     /**
 253      * Activates the URL navigator (KUrlNavigator::isActive() will return true)
 254      * and emits the signal KUrlNavigator::activated().
 255      */
 256     void requestActivation();
 257
 258     /**
 259      * Saves the used root URL of the content for the current history element.
 260      * Saving the root URL might be useful if the item view is represented by a tree or
 261      * columns, where it is mandatory to restore the root URL to iterating
 262      * through the history.
 263      */
 264     void saveRootUrl(const KUrl& url);
 265
 266     /**
 267      * Saves the coordinates of the contents for
 268      * the current history element. The contents of the URL is usually shown
 269      * inside an instance of QAbstractItemView. It is recommended to invoke this
 270      * slot whenever the upper left position of the QAbstractItemView has been
 271      * changed to be able to restore the position when going back in history.
 272      *
 273      * @see KUrlNavigator::savedPosition()
 274      */
 275     void savePosition(int x, int y);
 276
 277     /* @see QWidget::setFocus() */
 278     void setFocus();
 279
 280 Q_SIGNALS:
 281     /**
 282      * Is emitted, if the URL navigator has been activated by
 283      * a user interaction.
 284      */
 285     void activated();
 286
 287     /**
 288      * Is emitted, if the URL has been changed e. g. by
 289      * the user.
 290      * @see KUrlNavigator::setUrl()
 291      */
 292     void urlChanged(const KUrl& url);
 293
 294     /**
 295      * Is emitted, if the editable state for the URL has been changed
 296      * (see KUrlNavigator::setUrlEditable()).
 297      */
 298     void editableStateChanged(bool editable);
 299
 300     /**
 301      * Is emitted, if the history has been changed. Usually
 302      * the history is changed if a new URL has been selected.
 303      */
 304     void historyChanged();
 305
 306     /**
 307      * Is emitted if the URLs \a urls have been dropped
 308      * to the destination \a destination.
 309      */
 310     // KDE5: remove, as the signal has been replaced by
 311     // urlsDropped(const KUrl& destination, QDropEvent* event)
 312     void urlsDropped(const KUrl::List& urls,
 313                      const KUrl& destination);
 314
 315     /**
 316      * Is emitted if a dropping has been done above the destination
 317      * \a destination. The receiver must accept the drop event if
 318      * the dropped data can be handled.
 319      *
 320      * @since 4.2
 321      */
 322     void urlsDropped(const KUrl& destination, QDropEvent* event);
 323
 324     /**
 325      * This signal is emitted when the Return or Enter key is pressed.
 326      */
 327     void returnPressed();
 328
 329 protected:
 330     /*
 331      * If the Escape key is pressed, the navigation bar should switch
 332      * to the breadcrumb view.
 333      * @see QWidget::keyReleaseEvent()
 334      */
 335     virtual void keyReleaseEvent(QKeyEvent* event);
 336
 337     /*
 338      * Paste the clipboard content as URL, if the middle mouse
 339      * button has been clicked.
 340      * @see QWidget::mouseReleaseEvent()
 341      */
 342     virtual void mouseReleaseEvent(QMouseEvent* event);
 343
 344     /* @see QWidget::resizeEvent() */
 345     virtual void resizeEvent(QResizeEvent* event);
 346
 347     virtual bool eventFilter(QObject* watched, QEvent* event);
 348
 349 private:
 350     Q_PRIVATE_SLOT(d, void slotReturnPressed())
 351     Q_PRIVATE_SLOT(d, void slotRemoteHostActivated())
 352     Q_PRIVATE_SLOT(d, void slotProtocolChanged(const QString& protocol))
 353     Q_PRIVATE_SLOT(d, void switchView())
 354     Q_PRIVATE_SLOT(d, void dropUrls(const KUrl& destination, QDropEvent*))
 355     Q_PRIVATE_SLOT(d, void openPathSelectorMenu())
 356     Q_PRIVATE_SLOT(d, void updateButtonVisibility())
 357     Q_PRIVATE_SLOT(d, void switchToBreadcrumbMode())
 358     Q_PRIVATE_SLOT(d, void updateContent())
 359
 360 private:
 361     class Private;
 362     Private* const d;
 363
 364     Q_DISABLE_COPY(KUrlNavigator)
 365 };
 366
 367 #endif