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 <khbox.h>
  26 #include <kurl.h>
  27 #include <QLinkedList>
  28
  29 class QLabel;
  30 class QLineEdit;
  31 class QCheckBox;
  32
  33 class KUrl;
  34 class KFileItem;
  35 class KUrlComboBox;
  36
  37 class BookmarkSelector;
  38 class ProtocolCombo;
  39
  40 /**
  41  * @brief Navigation bar which contains the current shown URL.
  42  *
  43  * The URL navigator offers two modes:
  44  * - Editable:     Represents the 'classic' mode, where the current Url
  45  *                 is editable inside a line editor.
  46  * - Non editable: The URL is represented by a number of buttons, where
  47  *                 clicking on a button results in activating the URL
  48  *                 the button represents. This mode also supports drag
  49  *                 and drop of items.
  50  *
  51  * The mode can be changed by a toggle button located on the left side of
  52  * the navigator.
  53  *
  54  * The URL navigator also remembers the URL history and allows to go
  55  * back and forward within this history.
  56 */
  57
  58 typedef QLinkedList<KUrl> UrlStack;
  59
  60 class UrlNavigator : public KHBox
  61 {
  62     Q_OBJECT
  63
  64 public:
  65     /**
  66      * @brief Represents the history element of an Url.
  67      *
  68      * A history element contains the Url, the name of the current file
  69      * (the 'current file' is the file where the cursor is located) and
  70      * the x- and y-position of the content.
  71      */
  72     class HistoryElem {
  73     public:
  74         HistoryElem();
  75         HistoryElem(const KUrl& url);
  76         ~HistoryElem(); // non virtual
  77
  78         const KUrl& url() const { return m_url; }
  79
  80         void setCurrentFileName(const QString& name) { m_currentFileName = name; }
  81         const QString& currentFileName() const { return m_currentFileName; }
  82
  83         void setContentsX(int x) { m_contentsX = x; }
  84         int contentsX() const { return m_contentsX; }
  85
  86         void setContentsY(int y) { m_contentsY = y; }
  87         int contentsY() const { return m_contentsY; }
  88
  89     private:
  90         KUrl m_url;
  91         QString m_currentFileName;
  92         int m_contentsX;
  93         int m_contentsY;
  94     };
  95
  96     UrlNavigator(const KUrl& url, QWidget* parent);
  97     virtual ~UrlNavigator();
  98
  99     /** Returns the current active Url. */
 100     const KUrl& url() const;
 101
 102     /** Returns the portion of the current active Url up to the button at index. */
 103     KUrl url(int index) const;
 104
 105     /**
 106      * Returns the complete Url history. The index 0 indicates the oldest
 107      * history element.
 108      * @param index     Output parameter which indicates the current
 109      *                  index of the location.
 110      */
 111     const QLinkedList<HistoryElem>& history(int& index) const;
 112
 113     /**
 114      * Goes back one step in the Url history. The signals
 115      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 116      * are submitted.
 117      */
 118     void goBack();
 119
 120     /**
 121      * Goes forward one step in the Url history. The signals
 122      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 123      * are submitted.
 124      */
 125     void goForward();
 126
 127     /**
 128      * Goes up one step of the Url path. The signals
 129      * UrlNavigator::urlChanged and UrlNavigator::historyChanged
 130      * are submitted.
 131      */
 132     void goUp();
 133
 134     /**
 135      * Goes to the home Url. The signals UrlNavigator::urlChanged
 136      * and UrlNavigator::historyChanged are submitted.
 137      */
 138     void goHome();
 139
 140     /**
 141      * @return True, if the Url is editable by the user within a line editor.
 142      *         If false is returned, each part of the Url is presented by a button
 143      *         for fast navigation.
 144      */
 145     bool isUrlEditable() const;
 146
 147     /**
 148      * Switches to the edit mode and assures that the keyboard focus
 149      * is assigned.
 150      */
 151     void editUrl(bool editOrBrowse); //TODO: switch to an enum
 152
 153     /**
 154      * Set the URL navigator to the active mode, if \a active
 155      * is true. The active mode is default. Using the URL navigator
 156      * in the inactive mode is useful when having split views,
 157      * where the inactive view is indicated by a an inactive URL
 158      * navigator visually.
 159      */
 160     void setActive(bool active);
 161
 162     /**
 163      * Returns true, if the URL navigator is in the active mode.
 164      * @see UrlNavigator::setActive()
 165      */
 166     bool isActive() const { return m_active; }
 167
 168     /**
 169      * Handles the dropping of the URLs \a urls to the given
 170      * destination \a destination and emits the signal urlsDropped.
 171      */
 172     void dropUrls(const KUrl::List& urls,
 173                   const KUrl& destination);
 174
 175 public slots:
 176     /**
 177      * Sets the current active URL.
 178      * The signals UrlNavigator::urlChanged and UrlNavigator::historyChanged
 179      * are submitted.
 180      */
 181     void setUrl(const KUrl& url);
 182
 183     /**
 184      * Activates the URL navigator (UrlNavigator::isActive() will return true)
 185      * and emits the signal 'activationChanged()'.
 186      */
 187     void requestActivation();
 188
 189     /**
 190      * Stores the coordinates of the contents into
 191      * the current history element.
 192      */
 193     void storeContentsPosition(int x, int y);
 194
 195 signals:
 196     /**
 197      * Is emitted, if the URL navigator has been activated by
 198      * a user interaction.
 199      */
 200     void activated();
 201
 202     /**
 203      * Is emitted, if the URL has been changed e. g. by
 204      * the user.
 205      * @see setUrl()
 206      */
 207     void urlChanged(const KUrl& url);
 208
 209     /**
 210      * Is emitted, if the history has been changed. Usually
 211      * the history is changed if a new URL has been selected.
 212      */
 213     void historyChanged();
 214
 215     /**
 216      * Is emitted if the URLs \a urls have been dropped
 217      * to the destination \a destination.
 218      */
 219     void urlsDropped(const KUrl::List& urls,
 220                      const KUrl& destination);
 221
 222 protected:
 223     /** If the Escape key is pressed, the navigation bar should switch
 224         to the browse mode. */
 225     virtual void keyReleaseEvent(QKeyEvent* event);
 226
 227 private slots:
 228     void slotReturnPressed(const QString& text);
 229     void slotUrlActivated(const KUrl& url);
 230     void slotRemoteHostActivated();
 231     void slotProtocolChanged(const QString& protocol);
 232     void slotRedirection(const KUrl&, const KUrl&);
 233
 234     /**
 235      * Switches the navigation bar between the editable and noneditable
 236      * state (see setUrlEditable()) and is connected to the clicked signal
 237      * of the navigation bar button.
 238      */
 239     void slotClicked();
 240
 241 private:
 242     bool m_active;
 243     int m_historyIndex;
 244     QLinkedList<HistoryElem> m_history;
 245     QCheckBox* m_toggleButton;
 246     BookmarkSelector* m_bookmarkSelector;
 247     KUrlComboBox* m_pathBox;
 248     ProtocolCombo* m_protocols;
 249     QLabel* m_protocolSeparator;
 250     QLineEdit* m_host;
 251     QLinkedList<QWidget*> m_navButtons;
 252     //UrlStack m_urls;
 253
 254     /**
 255      * Allows to edit the Url of the navigation bar if \a editable
 256      * is true. If \a editable is false, each part of
 257      * the Url is presented by a button for a fast navigation.
 258      */
 259     void setUrlEditable(bool editable);
 260
 261     /**
 262      * Updates the history element with the current file item
 263      * and the contents position.
 264      */
 265     void updateHistoryElem();
 266     void updateContent();
 267 };
 268
 269 #endif