src/urlnavigator.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  *                                                                         *
   6  *   This program is free software; you can redistribute it and/or modify  *
   7  *   it under the terms of the GNU General Public License as published by  *
   8  *   the Free Software Foundation; either version 2 of the License, or     *
   9  *   (at your option) any later version.                                   *
  10  *                                                                         *
  11  *   This program 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         *
  14  *   GNU General Public License for more details.                          *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU General Public License     *
  17  *   along with this program; if not, write to the                         *
  18  *   Free Software Foundation, Inc.,                                       *
  19  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA          *
  20  ***************************************************************************/
  21
  22 #ifndef URLNAVIGATOR_H
  23 #define URLNAVIGATOR_H
  24
  25 #include <kurl.h>
  26 #include <QWidget>
  27 #include <QLinkedList>
  28
  29 class QHBoxLayout;
  30 class QLabel;
  31 class QLineEdit;
  32 class QMouseEvent;
  33 class QToolButton;
  34
  35 class KUrl;
  36 class KFileItem;
  37 class KUrlComboBox;
  38
  39 class BookmarkSelector;
  40 class UrlNavigatorButton;
  41 class ProtocolCombo;
  42
  43 /**
  44  * @brief Navigation bar which contains the current shown URL.
  45  *
  46  * The URL navigator offers two modes:
  47  * - Editable:     Represents the 'classic' mode, where the current URL
  48  *                 is editable inside a line editor.
  49  * - Non editable: The URL is represented by a number of buttons, where
  50  *                 clicking on a button results in activating the URL
  51  *                 the button represents. This mode also supports drag
  52  *                 and drop of items.
  53  *
  54  * The mode can be changed by a toggle button located on the left side of
  55  * the navigator.
  56  *
  57  * The URL navigator also remembers the URL history and allows to go
  58  * back and forward within this history.
  59 */
  60
  61 typedef QLinkedList<KUrl> UrlStack;
  62
  63 class UrlNavigator : public QWidget
  64 {
  65     Q_OBJECT
  66
  67 public:
  68     /**
  69      * @brief Represents the history element of an URL.
  70      *
  71      * A history element contains the URL, the name of the current file
  72      * (the 'current file' is the file where the cursor is located) and
  73      * the x- and y-position of the content.
  74      */
  75     class HistoryElem {
  76     public:
  77         HistoryElem();
  78         HistoryElem(const KUrl& url);
  79         ~HistoryElem(); // non virtual
  80
  81         const KUrl& url() const { return m_url; }
  82
  83         void setCurrentFileName(const QString& name) { m_currentFileName = name; }
  84         const QString& currentFileName() const { return m_currentFileName; }
  85
  86         void setContentsX(int x) { m_contentsX = x; }
  87         int contentsX() const { return m_contentsX; }
  88
  89         void setContentsY(int y) { m_contentsY = y; }
  90         int contentsY() const { return m_contentsY; }
  91
  92     private:
  93         KUrl m_url;
  94         QString m_currentFileName;
  95         int m_contentsX;
  96         int m_contentsY;
  97     };
  98
  99     UrlNavigator(const KUrl& url, QWidget* parent);
 100     virtual ~UrlNavigator();
 101
 102     /** Returns the current active URL. */
 103     const KUrl& url() const;
 104
 105     /** Returns the portion of the current active URL up to the button at index. */
 106     KUrl url(int index) const;
 107
 108     /**
 109      * Returns the complete URL history. The index 0 indicates the oldest
 110      * history element.
 111      * @param index     Output parameter which indicates the current
 112      *                  index of the location.
 113      */
 114     const QLinkedList<HistoryElem>& history(int& index) const;
 115
 116     /**
 117      * Goes back one step in the URL history. The signals
 118      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 119      * are submitted.
 120      */
 121     void goBack();
 122
 123     /**
 124      * Goes forward one step in the URL history. The signals
 125      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 126      * are submitted.
 127      */
 128     void goForward();
 129
 130     /**
 131      * Goes up one step of the URL path. The signals
 132      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 133      * are submitted.
 134      */
 135     void goUp();
 136
 137     /**
 138      * Goes to the home URL. The signals UrlNavigator::urlChanged
 139      * and UrlNavigator::historyChanged are submitted.
 140      */
 141     void goHome();
 142
 143     /**
 144      * @return True, if the URL is editable by the user within a line editor.
 145      *         If false is returned, each part of the URL is presented by a button
 146      *         for fast navigation.
 147      */
 148     bool isUrlEditable() const;
 149
 150     /**
 151      * Switches to the edit mode and assures that the keyboard focus
 152      * is assigned.
 153      */
 154     void editUrl(bool editOrBrowse); //TODO: switch to an enum
 155
 156     /**
 157      * Set the URL navigator to the active mode, if \a active
 158      * is true. The active mode is default. Using the URL navigator
 159      * in the inactive mode is useful when having split views,
 160      * where the inactive view is indicated by a an inactive URL
 161      * navigator visually.
 162      */
 163     void setActive(bool active);
 164
 165     /**
 166      * Returns true, if the URL navigator is in the active mode.
 167      * @see UrlNavigator::setActive()
 168      */
 169     bool isActive() const { return m_active; }
 170
 171     /**
 172      * Sets whether or not to show hidden files in lists
 173      */
 174     void setShowHiddenFiles( bool show );
 175
 176     /**
 177      * Returns true if the URL navigator is set to show hidden files
 178      */
 179     bool showHiddenFiles() { return m_showHiddenFiles; }
 180
 181     /**
 182      * Handles the dropping of the URLs \a urls to the given
 183      * destination \a destination and emits the signal urlsDropped.
 184      */
 185     void dropUrls(const KUrl::List& urls,
 186                   const KUrl& destination);
 187
 188 public slots:
 189     /**
 190      * Sets the current active URL.
 191      * The signals UrlNavigator::urlChanged and UrlNavigator::historyChanged
 192      * are submitted.
 193      */
 194     void setUrl(const KUrl& url);
 195
 196     /**
 197      * Activates the URL navigator (UrlNavigator::isActive() will return true)
 198      * and emits the signal 'activationChanged()'.
 199      */
 200     void requestActivation();
 201
 202     /**
 203      * Stores the coordinates of the contents into
 204      * the current history element.
 205      */
 206     void storeContentsPosition(int x, int y);
 207
 208 signals:
 209     /**
 210      * Is emitted, if the URL navigator has been activated by
 211      * a user interaction.
 212      */
 213     void activated();
 214
 215     /**
 216      * Is emitted, if the URL has been changed e. g. by
 217      * the user.
 218      * @see setUrl()
 219      */
 220     void urlChanged(const KUrl& url);
 221
 222     /**
 223      * Is emitted, if the history has been changed. Usually
 224      * the history is changed if a new URL has been selected.
 225      */
 226     void historyChanged();
 227
 228     /**
 229      * Is emitted if the URLs \a urls have been dropped
 230      * to the destination \a destination.
 231      */
 232     void urlsDropped(const KUrl::List& urls,
 233                      const KUrl& destination);
 234
 235 protected:
 236     /**
 237      * If the Escape key is pressed, the navigation bar should switch
 238      * to the browse mode.
 239      */
 240     virtual void keyReleaseEvent(QKeyEvent* event);
 241
 242     /**
 243      * Paste the clipboard content as URL, if the middle mouse
 244      * button has been clicked.
 245      */
 246     virtual void mouseReleaseEvent(QMouseEvent* event);
 247
 248 private slots:
 249     void slotReturnPressed(const QString& text);
 250     void slotUrlActivated(const KUrl& url);
 251     void slotRemoteHostActivated();
 252     void slotProtocolChanged(const QString& protocol);
 253     void slotRedirection(const KUrl&, const KUrl&);
 254
 255     /**
 256      * Switches the navigation bar between the breadcrumb view and the
 257      * traditional view (see setUrlEditable()) and is connected to the clicked signal
 258      * of the navigation bar button.
 259      */
 260     void switchView();
 261
 262 private:
 263     /**
 264      * Allows to edit the Url of the navigation bar if \a editable
 265      * is true. If \a editable is false, each part of
 266      * the Url is presented by a button for a fast navigation.
 267      */
 268     void setUrlEditable(bool editable);
 269
 270     /**
 271      * Updates the history element with the current file item
 272      * and the contents position.
 273      */
 274     void updateHistoryElem();
 275     void updateContent();
 276
 277     /**
 278      * Updates all buttons to have one button for each part of the
 279      * path \a path. Existing buttons, which are available by m_navButtons,
 280      * are reused if possible. If the path is longer, new buttons will be
 281      * created, if the path is shorter, the remaining buttons will be deleted.
 282      * @param startIndex    Start index of path part (/), where the buttons
 283      *                      should be created for each following part.
 284      */
 285     void updateButtons(const QString& path, int startIndex);
 286
 287     /**
 288      * Deletes all URL navigator buttons. m_navButtons is
 289      * empty after this operation.
 290      */
 291     void deleteButtons();
 292
 293     /**
 294      * Appends the widget at the end of the URL navigator. It is assured
 295      * that the filler widget remains as last widget to fill the remaining
 296      * width.
 297      */
 298     void appendWidget(QWidget* widget);
 299
 300 private:
 301     bool m_active;
 302     bool m_showHiddenFiles;
 303     int m_historyIndex;
 304
 305     QHBoxLayout* m_layout;
 306
 307     QLinkedList<HistoryElem> m_history;
 308     QToolButton* m_toggleButton;
 309     BookmarkSelector* m_bookmarkSelector;
 310     KUrlComboBox* m_pathBox;
 311     ProtocolCombo* m_protocols;
 312     QLabel* m_protocolSeparator;
 313     QLineEdit* m_host;
 314     QLinkedList<UrlNavigatorButton*> m_navButtons;
 315     QWidget* m_filler;
 316     //UrlStack m_urls;
 317 };
 318
 319 #endif