src/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) 2006 by Patrice Tremblay                                *
   5  *   Copyright (C) 2007 by Kevin Ottens (ervin@kde.org)                    *
   6  *                                                                         *
   7  *   This program is free software; you can redistribute it and/or modify  *
   8  *   it under the terms of the GNU General Public License as published by  *
   9  *   the Free Software Foundation; either version 2 of the License, or     *
  10  *   (at your option) any later version.                                   *
  11  *                                                                         *
  12  *   This program is distributed in the hope that it will be useful,       *
  13  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  14  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  15  *   GNU General Public License for more details.                          *
  16  *                                                                         *
  17  *   You should have received a copy of the GNU General Public License     *
  18  *   along with this program; if not, write to the                         *
  19  *   Free Software Foundation, Inc.,                                       *
  20  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA          *
  21  ***************************************************************************/
  22
  23 #ifndef KURLNAVIGATOR_H
  24 #define KURLNAVIGATOR_H
  25
  26 #include <kurl.h>
  27 #include <QWidget>
  28
  29 class KFilePlacesModel;
  30 class QMouseEvent;
  31
  32 /**
  33  * @brief Navigation bar which contains the current shown URL.
  34  *
  35  * The URL navigator offers two modes:
  36  * - Editable:     Represents the 'classic' mode, where the current URL
  37  *                 is editable inside a line editor.
  38  * - Non editable: The URL is represented by a number of buttons, where
  39  *                 clicking on a button results in activating the URL
  40  *                 the button represents. This mode also supports drag
  41  *                 and drop of items.
  42  *
  43  * The mode can be changed by a toggle button located on the left side of
  44  * the navigator.
  45  *
  46  * The URL navigator also remembers the URL history and allows to go
  47  * back and forward within this history.
  48  */
  49 class KUrlNavigator : public QWidget
  50 {
  51     Q_OBJECT
  52
  53 public:
  54     KUrlNavigator(KFilePlacesModel* placesModel, const KUrl& url, QWidget* parent);
  55     virtual ~KUrlNavigator();
  56
  57     /** Returns the current active URL. */
  58     const KUrl& url() const;
  59
  60     /** Returns the portion of the current active URL up to the button at index. */
  61     KUrl url(int index) const;
  62
  63     /** Returns the amount of items in the history */
  64     int historySize() const;
  65
  66     /** Returns the saved position from the history */
  67     QPoint savedPosition() const;
  68
  69     /**
  70      * Goes back one step in the URL history. The signals
  71      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
  72      * are submitted.
  73      */
  74     void goBack();
  75
  76     /**
  77      * Goes forward one step in the URL history. The signals
  78      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
  79      * are submitted.
  80      */
  81     void goForward();
  82
  83     /**
  84      * Goes up one step of the URL path. The signals
  85      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
  86      * are submitted.
  87      */
  88     void goUp();
  89
  90     /**
  91      * Goes to the home URL. The signals UrlNavigator::urlChanged
  92      * and UrlNavigator::historyChanged are submitted.
  93      */
  94     void goHome();
  95
  96     /**
  97      * Sets the home URL used by goHome().
  98      */
  99     void setHomeUrl(const QString& homeUrl);
 100
 101     /**
 102      * @return True, if the URL is editable by the user within a line editor.
 103      *         If false is returned, each part of the URL is presented by a button
 104      *         for fast navigation.
 105      */
 106     bool isUrlEditable() const;
 107
 108     /**
 109      * Allows to edit the URL of the navigation bar if \a editable
 110      * is true, and sets the focus accordingly.
 111      * If \a editable is false, each part of
 112      * the URL is presented by a button for a fast navigation.
 113      */
 114     void setUrlEditable(bool editable);
 115
 116     /**
 117      * Set the URL navigator to the active mode, if \a active
 118      * is true. The active mode is default. Using the URL navigator
 119      * in the inactive mode is useful when having split views,
 120      * where the inactive view is indicated by an inactive URL
 121      * navigator visually.
 122      */
 123     void setActive(bool active);
 124
 125     /**
 126      * Returns true, if the URL navigator is in the active mode.
 127      * @see UrlNavigator::setActive()
 128      */
 129     bool isActive() const;
 130
 131     /**
 132      * Sets whether or not to show hidden files in lists
 133      */
 134     void setShowHiddenFiles( bool show );
 135
 136     /**
 137      * Returns true if the URL navigator is set to show hidden files
 138      */
 139     bool showHiddenFiles() const; // TODO rename, looks like a verb
 140
 141     /**
 142      * Handles the dropping of the URLs \a urls to the given
 143      * destination \a destination and emits the signal urlsDropped.
 144      */
 145     void dropUrls(const KUrl::List& urls,
 146                   const KUrl& destination);
 147
 148 public slots:
 149     /**
 150      * Sets the current active URL.
 151      * The signals UrlNavigator::urlChanged and UrlNavigator::historyChanged
 152      * are submitted.
 153      */
 154     void setUrl(const KUrl& url);
 155
 156     /**
 157      * Activates the URL navigator (UrlNavigator::isActive() will return true)
 158      * and emits the signal 'activationChanged()'.
 159      */
 160     void requestActivation();
 161
 162     /**
 163      * Stores the coordinates of the contents into
 164      * the current history element.
 165      */
 166     void storeContentsPosition(int x, int y);
 167
 168 signals:
 169     /**
 170      * Is emitted, if the URL navigator has been activated by
 171      * a user interaction.
 172      */
 173     void activated();
 174
 175     /**
 176      * Is emitted, if the URL has been changed e. g. by
 177      * the user.
 178      * @see setUrl()
 179      */
 180     void urlChanged(const KUrl& url);
 181
 182     /**
 183      * Is emitted, if the history has been changed. Usually
 184      * the history is changed if a new URL has been selected.
 185      */
 186     void historyChanged();
 187
 188     /**
 189      * Is emitted if the URLs \a urls have been dropped
 190      * to the destination \a destination.
 191      */
 192     void urlsDropped(const KUrl::List& urls,
 193                      const KUrl& destination);
 194
 195 protected:
 196     /**
 197      * If the Escape key is pressed, the navigation bar should switch
 198      * to the browse mode.
 199      */
 200     virtual void keyReleaseEvent(QKeyEvent* event);
 201
 202     /**
 203      * Paste the clipboard content as URL, if the middle mouse
 204      * button has been clicked.
 205      */
 206     virtual void mouseReleaseEvent(QMouseEvent* event);
 207
 208 private:
 209     Q_PRIVATE_SLOT(d, void slotReturnPressed(const QString& text))
 210     Q_PRIVATE_SLOT(d, void slotRemoteHostActivated())
 211     Q_PRIVATE_SLOT(d, void slotProtocolChanged(const QString& protocol))
 212     Q_PRIVATE_SLOT(d, void switchView())
 213     //Q_PRIVATE_SLOT(d, void slotRedirection(const KUrl&, const KUrl&))
 214
 215 private:
 216     class Private;
 217     Private* const d;
 218
 219     Q_DISABLE_COPY( KUrlNavigator )
 220 };
 221
 222 #endif