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 QPushButton;
  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      * Handles the dropping of the URLs \a urls to the given
 173      * destination \a destination and emits the signal urlsDropped.
 174      */
 175     void dropUrls(const KUrl::List& urls,
 176                   const KUrl& destination);
 177
 178 public slots:
 179     /**
 180      * Sets the current active URL.
 181      * The signals UrlNavigator::urlChanged and UrlNavigator::historyChanged
 182      * are submitted.
 183      */
 184     void setUrl(const KUrl& url);
 185
 186     /**
 187      * Activates the URL navigator (UrlNavigator::isActive() will return true)
 188      * and emits the signal 'activationChanged()'.
 189      */
 190     void requestActivation();
 191
 192     /**
 193      * Stores the coordinates of the contents into
 194      * the current history element.
 195      */
 196     void storeContentsPosition(int x, int y);
 197
 198 signals:
 199     /**
 200      * Is emitted, if the URL navigator has been activated by
 201      * a user interaction.
 202      */
 203     void activated();
 204
 205     /**
 206      * Is emitted, if the URL has been changed e. g. by
 207      * the user.
 208      * @see setUrl()
 209      */
 210     void urlChanged(const KUrl& url);
 211
 212     /**
 213      * Is emitted, if the history has been changed. Usually
 214      * the history is changed if a new URL has been selected.
 215      */
 216     void historyChanged();
 217
 218     /**
 219      * Is emitted if the URLs \a urls have been dropped
 220      * to the destination \a destination.
 221      */
 222     void urlsDropped(const KUrl::List& urls,
 223                      const KUrl& destination);
 224
 225 protected:
 226     /**
 227      * If the Escape key is pressed, the navigation bar should switch
 228      * to the browse mode.
 229      */
 230     virtual void keyReleaseEvent(QKeyEvent* event);
 231
 232     /**
 233      * Paste the clipboard content as URL, if the middle mouse
 234      * button has been clicked.
 235      */
 236     virtual void mouseReleaseEvent(QMouseEvent* event);
 237
 238 private slots:
 239     void slotReturnPressed(const QString& text);
 240     void slotUrlActivated(const KUrl& url);
 241     void slotRemoteHostActivated();
 242     void slotProtocolChanged(const QString& protocol);
 243     void slotRedirection(const KUrl&, const KUrl&);
 244
 245     /**
 246      * Switches the navigation bar between the breadcrumb view and the
 247      * traditional view (see setUrlEditable()) and is connected to the clicked signal
 248      * of the navigation bar button.
 249      */
 250     void switchView();
 251
 252 private:
 253     /**
 254      * Allows to edit the Url of the navigation bar if \a editable
 255      * is true. If \a editable is false, each part of
 256      * the Url is presented by a button for a fast navigation.
 257      */
 258     void setUrlEditable(bool editable);
 259
 260     /**
 261      * Updates the history element with the current file item
 262      * and the contents position.
 263      */
 264     void updateHistoryElem();
 265     void updateContent();
 266
 267     /**
 268      * Updates all buttons to have one button for each part of the
 269      * path \a path. Existing buttons, which are available by m_navButtons,
 270      * are reused if possible. If the path is longer, new buttons will be
 271      * created, if the path is shorter, the remaining buttons will be deleted.
 272      * @param startIndex    Start index of path part (/), where the buttons
 273      *                      should be created for each following part.
 274      */
 275     void updateButtons(const QString& path, int startIndex);
 276
 277     /**
 278      * Deletes all URL navigator buttons. m_navButtons is
 279      * empty after this operation.
 280      */
 281     void deleteButtons();
 282
 283     /**
 284      * Appends the widget at the end of the URL navigator. It is assured
 285      * that the filler widget remains as last widget to fill the remaining
 286      * width.
 287      */
 288     void appendWidget(QWidget* widget);
 289
 290 private:
 291     bool m_active;
 292     int m_historyIndex;
 293
 294     QHBoxLayout* m_layout;
 295
 296     QLinkedList<HistoryElem> m_history;
 297     QPushButton* m_toggleButton;
 298     BookmarkSelector* m_bookmarkSelector;
 299     KUrlComboBox* m_pathBox;
 300     ProtocolCombo* m_protocols;
 301     QLabel* m_protocolSeparator;
 302     QLineEdit* m_host;
 303     QLinkedList<UrlNavigatorButton*> m_navButtons;
 304     QWidget* m_filler;
 305     //UrlStack m_urls;
 306 };
 307
 308 #endif