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